How to Integrate Kubernetes + Okta OIDC

Integrating Kubernetes with Okta using OpenID Connect (OIDC) allows seamless authentication for cluster users by leveraging a secure and modern protocol for identity verification. OIDC is particularly beneficial for Kubernetes environments because it eliminates the need for managing static credentials directly in the cluster. Instead, it facilitates dynamic token-based authentication, ensuring that access is both secure and scalable across multiple users and workloads. This approach not only enhances security but also simplifies compliance by providing detailed logging and audit trails for authentication events. Okta acts as an identity provider, enabling centralized user management and Single Sign-On (SSO) for Kubernetes clusters. This guide walks you through the integration process, including configuring Okta, setting up Kubernetes for OIDC, and testing the integration. By enabling this integration, organizations can streamline user access while maintaining a high level of security and compliance.

Prerequisites

Before you begin:

• Okta Account: Create an Okta account if you do not already have one.
• Kubernetes Cluster: A running Kubernetes cluster (tested with v1.24 and above).
• kubectl Installed: Ensure you have the kubectl command-line tool installed and configured to access your cluster.
• DNS Domain: A domain name configured to point to your Kubernetes API server.
• SSL/TLS Configured: Ensure your Kubernetes API server is secured with valid SSL/TLS certificates.

Configure Okta for OIDC Integration

1. Create an Application in Okta:

   • Log in to your Okta account.
   • Navigate to Applications > Create App Integration.
   • Select OIDC – OpenID Connect as the sign-in method.
   • Choose Web Application and click Next.

2. Application Settings:

   • Fill in the following details:
     • App Name: For example, Kubernetes OIDC.
     • Redirect URI: Add your Kubernetes API server’s endpoint: https://<kubernetes-api-server>/oauth2/callback.
     • Logout Redirect URI: Optional, can be left blank.
   • Click Save.

   Ensure the redirect URI is configured correctly to avoid login issues. It is recommended to test with a sample endpoint first.

3. Note Key Credentials:

   After saving, note the following details from the application settings:

   • Client ID
   • Client Secret
   • Issuer URI (e.g., https://<your-okta-domain>/oauth2/default)

   These details will be required when configuring your Kubernetes API server.

4. Assign Users:

   Assign users or groups to the application to define who can access the Kubernetes cluster. This step ensures that only authorized personnel can authenticate with the cluster, improving security.

Configure Kubernetes for OIDC

1. Modify Kubernetes API Server Configuration:

   Update the Kubernetes API server to include OIDC flags. These flags configure the server to authenticate users via the OIDC protocol:

2. --oidc-issuer-url: Specifies the URL of the OIDC provider’s issuer. This URL should match the Issuer URI noted in your Okta application.

3. --oidc-client-id: The client ID generated for your application in Okta. It identifies the Kubernetes API server to the OIDC provider.
4. --oidc-username-claim: Defines the user attribute (e.g., email) that Kubernetes will use as the username.

5. --oidc-groups-claim: Specifies the claim that contains group information, enabling role-based access control (RBAC) based on Okta groups. Depending on how your cluster is deployed, this might involve editing the kube-apiserver configuration file or updating your Kubernetes manifest. Add the following:

    --oidc-issuer-url=https://<your-okta-domain>/oauth2/default \
    --oidc-client-id=<client-id> \
    --oidc-username-claim=email \
    --oidc-groups-claim=groups
   

   Replace <your-okta-domain> and <client-id> with the values obtained from Okta. Be sure to verify that the issuer URL matches exactly with the one provided by Okta.

6. Restart the Kubernetes API Server:

   Apply the configuration changes by restarting the API server. For example:

   sudo systemctl restart kube-apiserver
   

   Depending on your setup, you may need to perform this step on all control plane nodes.

7. Create Kubernetes Role and RoleBinding:

   Define roles and role bindings for Okta users to grant specific permissions within the cluster. For example, you might assign read-only access to development teams for namespaces where application logs are stored, or grant full administrative access to cluster operators managing infrastructure. These roles and bindings align with Kubernetes' RBAC model, ensuring that permissions reflect organizational workflows and security policies. This setup ensures that users have access only to the resources they are authorized to manage.

   • Create a Role:

     apiVersion: rbac.authorization.k8s.io/v1
     kind: Role
     metadata:
       namespace: default
       name: example-role
     rules:
     - apiGroups: [""]
       resources: ["pods"]
       verbs: ["get", "list", "watch"]
     

   • Create a RoleBinding:

     apiVersion: rbac.authorization.k8s.io/v1
     kind: RoleBinding
     metadata:
       name: example-role-binding
       namespace: default
     subjects:
     - kind: User
       name: "<okta-user-email>"  # Replace with Okta user email
       apiGroup: ""
     roleRef:
       kind: Role
       name: example-role
       apiGroup: ""
     

   Apply these configurations using kubectl:

   kubectl apply -f role.yaml
   kubectl apply -f rolebinding.yaml
   

   By creating roles and bindings, you ensure that users are mapped to specific permissions in the Kubernetes environment.

Test OIDC Integration

1. Generate a Token:

   Use the Okta CLI or a browser to log in and generate an OIDC token. For example:

2. Open your browser and navigate to the Okta login page.

3. Enter your Okta credentials and complete any multi-factor authentication prompts.
4. After logging in, look for the token in the callback URL in your browser's address bar. It typically appears as a parameter labeled id_token or access_token.

5. Alternatively, if you are using the Okta CLI, run the command:

   okta login
   

   Follow the prompts to log in and retrieve the token from the output. This typically involves:

   • Accessing the Okta login page.
   • Authenticating with your credentials.
   • Retrieving the token from the callback URL or using an Okta-provided CLI tool.

   If you encounter issues, ensure your Okta application configuration matches the Kubernetes API server settings.

6. Authenticate with kubectl:

   Use the token to configure your Kubernetes context. Update your kubeconfig file:

   kubectl config set-credentials okta-user \
     --token=<oidc-token>
   
   kubectl config set-context okta-context \
     --cluster=<your-cluster-name> \
     --user=okta-user
   
   kubectl config use-context okta-context
   

   This configuration allows you to use Okta authentication for accessing your cluster.

7. Verify Access:

   Test your access to the Kubernetes cluster:

   kubectl get pods
   

   If configured correctly, you should see a list of pods in the default namespace, depending on the role assigned. For more detailed debugging, check the API server logs for authentication requests.

8. Test Group Permissions:

   If you configured group-based access, verify that users in specific groups have the appropriate access levels.

Conclusion

Integrating Kubernetes with Okta using OIDC enhances security and simplifies user management. By centralizing authentication through Okta, you enable scalable and secure access to your Kubernetes cluster. This scalability is particularly advantageous for larger teams and organizations, as it simplifies the management of user access across multiple clusters. It reduces administrative overhead by allowing centralized control of user permissions, ensuring that team members have the right level of access to the resources they need. Additionally, it facilitates onboarding new users and managing their access as teams grow, streamlining operations and improving overall efficiency. Additionally, this integration supports auditing and compliance by providing clear records of user activity. For more advanced configurations, refer to the official Okta and < href="https://kubernetes.io/docs/home/">Kubernetes documentation. Ensure regular reviews of roles and permissions to maintain optimal security.