Configure Kubernetes access management
Prerequisites
- An existing Okta Privileged Access team with the Kubernetes access management feature enabled
- An existing K8s cluster
- A device with Terraform and the OktaPAM Terraform provider installed and configured
- A device with the Okta Privileged Access client v1.61.2 or greater installed
- A device with kubectl installed
Prepare the OktaPAM Terraform provider
To start, admins must create a Terraform file that defines the cluster resources to create within Okta Privileged Access. This file also needs to include authentication information for a specific Okta Privileged Access team. For details, see Authentication.
Example
terraform { required_providers { oktapam = { source = "okta/oktapam" version = "0.2.1" } } } provider "oktapam" { # Authentication options oktapam_key = # An Okta PAM API Key oktapam_secret = # An Okta PAM API Secret oktapam_team = # An Okta PAM Team Name }
Configure Okta Privileged Access for Kubernetes access management
For Okta Privileged Access to manage access to Kubernetes clusters, both Okta Privileged Access and managed clusters need to be configured with information about each other.
To effectively manage each cluster, it's essential to create and update a cluster object that includes both the API server address and TLS certificate of the cluster. Each kubernetes-managed cluster must be configured to use Okta Privileged Access as an OIDC authentication endpoint. The OktaPAM Terraform provider supports kubernetes-specific resources that are used to configure Okta Privileged Access with this information for each cluster.
After resources for your cluster have been created in Okta Privileged Access, Okta Privileged Access administrators can review information about the clusters from the Kubernetes section of the Okta Privileged Access console.
-
Clusters: Displays a list of all previously added clusters. Teams can quickly see the associated labels on this page as well. Clicking a specific cluster opens a detailed view where teams can retrieve the OIDC authentication URL associated with the cluster.
-
Clusters Groups: Displays a list of all previously added cluster groups. Teams can see labels for each cluster group on this page.
Task 1: Add a cluster to Okta Privileged Access
First, Okta Privileged Access resource administrators must add resource blocks that define one or more K8s cluster resources to create within Okta Privileged Access. Each cluster resource has an associated OIDC URL that is later used to configure authentication for the specific cluster. Teams can add multiple clusters at the same time, but they must create a separate resource block for each cluster.
Teams can optionally define one or more label selectors for the cluster resource. These labels allow teams to control group access to each cluster.
| Request | |
|---|---|
| Parameter | Description |
| auth_mechanism | The specific mechanism used to provide auth details to the cluster. Currently, only OIDC_RSA2048 is supported. |
| key | A human-readable name is used to identify the cluster within Okta Privileged Access. It can't include spaces. Allowed characters: A-Z, 0–9. |
| labels | A map of labels used to control group access in Okta Privileged Access. |
| Response | |
| Property | Description |
| id | The ID of the created resource within Okta Privileged Access. |
| oidc_issuer_url | The OIDC Issuer URL to use when configuring your K8s cluster. |
| Example
resource "oktapam_kubernetes_cluster" "asa_docs" { auth_mechanism = "OIDC_RSA2048" key = "asadocs" labels = { env = "prod", tier = "gold" } } |
|
Task 2: Update Okta Privileged Access with cluster information
Okta Privileged Access needs additional information about clusters that it's managing for it to manage kubectl configuration files and ensure that users can access clusters. This information includes the API server address of the cluster and the certificate that is used for the HTTPS connection established with the cluster’s API server. Depending on how your cluster was created and where it's hosted, you can retrieve this information from a Terraform state file (for clusters built with Terraform) or from the cluster management console or API server.
| Request | |
|---|---|
| Parameter | Description |
| cluster_id | The ID of the cluster is returned from the oktapam_kubernetes_cluster resource. |
| api_url | The HTTPS URL for the Kubernetes cluster. This is the endpoint that is configured in the user’s kubeconfig files by the Okta Privileged Access client. |
| public_certificate | PEM encoded TLS certificate used by the cluster’s API server. This certificate is used by kubectl to verify the certificate presented by the cluster’s API server. For AWS EKS clusters, the trusted certificate is displayed on the AWS EKS details page. However, the certificate data must be converted to PEM format before it can be passed to this resource. The base64 -decode command can perform this conversion. |
| Response | |
| Property | Description |
| id | The ID of the created resource within Okta Privileged Access. |
| oidc_issuer_url | The OIDC Issuer URL to use when configuring your K8s cluster. |
| Example
resource "oktapam_kubernetes_cluster_connection" "asa_docs" { cluster_id = oktapam_kubernetes_cluster.asa_docs.id api_url = data.tls_certificate.asa_docs.url public_certificate = data.tls_certificate.asa_docs.certificates[0].cert_pem } |
|
Task 3: Create a cluster group
Finally, admins must create one or more cluster group resource blocks. Cluster groups map existing Okta Privileged Access groups to Kubernetes clusters and allow teams to define specific labels and claims for each group. Teams can add multiple cluster groups at the same time, but they must create a separate resource block for each group.
Labels control which cluster members of a group can access. For example, a team might apply the env: prod selector to some clusters and the env: dev selector to others. Then they might only assign the prod label to a specific group.
When specifying the claims that Okta Privileged Access should include in tokens, be certain the key name of the claim created in Okta Privileged Access exactly matches the key name configured in a cluster role binding. Similarly, if the Kubernetes cluster claim value specified in the role binding specifies a prefix to be used (AWS EKS), ensure that the claim value configured in Okta Privileged Access includes the prefix and claim value.
For example, if the EKS cluster’s OIDC configuration is configured with a groupsPrefix value of pam, and a groupsClaim value of groups, then when creating a ClusterGroup in Okta Privileged Access, the claim that is configured should be groups = pam:<groupname>, where <groupname> is the name of a rolebinding that has been created on the cluster.
Claims are included in tokens minted by Okta Privileged Access and are used by Kubernetes clusters to map a token to a Kubernetes role binding. All members of a group receive this role when they interact with an associated cluster.
This feature doesn't create or manage role bindings on the cluster. Roles and role bindings mapped to claims must be pre-configured on the cluster.
| Request | |
|---|---|
| Parameter | Description |
| cluster_selector | A label selector is used to match K8s clusters. |
| group_name | The human-readable name of an existing Okta Privileged Access group. Values are case-sensitive. |
| claims | A map of claims to include with user credentials for use with cluster authentication. Claims correspond to preconfigured role bindings on the cluster. |
| Response | |
| Property | Description |
| id | The ID of the created resource within Okta Privileged Access. |
| Example
resource "oktapam_kubernetes_cluster_group" "asa_docs" { cluster_selector = "env=prod" group_name = "existingGroup" claims = { groups = "ExampleGroup" } } |
|
Task 4: Configure your cluster
After the team creates resources within Okta Privileged Access, admins must configure a cluster to use Okta Privileged Access for authentication.
When a team adds a cluster with the OktaPam Terraform provider, they receive a unique OIDC authentication URL. Admins use the URL to force the cluster to authenticate users with Okta Privileged Access. See the Kubernetes documentation.
Minikube clusters
If you plan on testing the Kubernetes access management functionality on a minikube cluster, the following table outlines the parameters that need to be passed to the minikube startup command.
| Minikube startup arguments | |
|---|---|
| Parameter | Description |
| apiserver.authorization-mode | Set this to RBAC to enable Kubernetes RBAC on the cluster. |
| apiserver.oidc-issuer-url | The OIDC URL generated by Okta Privileged Access when the Cluster was created. This can be viewed in the Cluster Details page in the Okta Privileged Access dashboard. |
| apiserver.oidc-username-claim | The JWT claim that defines the username. Enter sub. |
| apiserver.oidc-groups-claim | The JWT claim that defines the group. This value should match one or more Group Claims that are configured in Okta Privileged Access ClusterGroups. Usually this is set to groups. |
| apiserver.oidc-client-id | Set this to kubernetes. |
| Example minikube startup command
minikube start \ --extra-config=apiserver.authorization-mode=Node,RBAC \ --extra-config=apiserver.oidc-issuer-url=\ https://app.scaleft.com/v1/teams/XXXXXX/kubernetes/clusters/XXXX-XXXX-XXXX-XXXX \ --extra-config=apiserver.oidc-username-claim=sub \ --extra-config=apiserver.oidc-client-id=kubernetes \ --extra-config=apiserver.oidc-groups-claim=groups |
|
AWS EKS cluster
AWS EKS clusters require more configuration to authenticate clusters with Okta Privileged Access. The following table provides a simple example of how to configure an EKS cluster. For more details, see the EKS Cluster Authentication documentation. An example YAML file for associating identities with EKS clusters, enabling authentication and access with Okta Privileged Access, is documented below for use with eksctl CLI.
| EKS Configuration | |
|---|---|
| Parameter | Description |
| IssuerUrl | A label selector is used to match K8s clusters. |
| ClientId | The human-readable name of an existing Okta Privileged Access Group. Values are case-sensitive. |
| UsernameClaim | A map of claims to include with user credentials for use with cluster authentication. Claims correspond to preconfigured role bindings on the cluster. |
| GroupsClaim | A JWT claim that defines the group. This value should match one or more Group Claims that are configured in Okta Privileged Access ClusterGroups. Usually this is set to groups. |
| UsernamePrefix | Optional. A string prepended to users accounts to prevent clashes. Enter any descriptive string, example: ASAUser:. |
| GroupsPrefix | Optional. A string prepended to user groups to prevent clashes. Enter any descriptive string, example: ASAGroup:. |
| Example Associate Identity Provider file (for use with eksctl)
apiVersion: eksctl.io/v1alpha5 kind: ClusterConfig metadata: name: eks-k8s-beta region: us-east-1 identityProviders: - name: okta-asa-k8s type: oidc issuerUrl: <ASA OIDC URL> clientId: kubernetes usernameClaim: sub groupsClaim: groups Example Cluster Role kind: ClusterRole apiVersion: rbac.authorization.k8s.io/v1 metadata: name: ASA-readonly rules: - apiGroups: ["*"] resources: ["*"] verbs: ["get", "list"] Example Role Binding kind: ClusterRoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: ASA-readonly-binding roleRef: kind: ClusterRole name: ASA-readonly apiGroup: rbac.authorization.k8s.io subjects: - kind: Group name: ASAGroup:ExampleGroup apiGroup: rbac.authorization.k8s.io |
|