Skip to main content
Version: 3.9.0

EKS OIDC With Keycloak

This article provides the instruction of configuring Keycloak as OIDC Identity Provider for EKS. The example is implemented following the KubeRocketCI add-ons approach.

Prerequisites​

To follow the instruction, check the following prerequisites:

  1. (Optional) Terraform version 1.5.7
  2. Kubelogin version >= v1.25.1
  3. (Optional) EDP Cluster Add-ons Solution is applied
  4. (Optional) External Secrets Operator
  5. A running Keycloak instance
  6. The Keycloak operator is deployed
  7. The Keycloak Realm's OIDC discovery URL and jwks_uri endpoints are publicly accessible
note

To connect OIDC with a cluster, install and configure the kubelogin plugin. For Windows, it is recommended to download the kubelogin as a binary and add it to your PATH.

Solution Overview​

This architecture encompasses three primary resource types: AWS (EKS), Keycloak, and Kubernetes. Within this setup, the Keycloak resources, once established, remain static, facilitating the assignment of claims based on user group memberships. This stability contrasts with the dynamic nature of other resources, which may be created, modified, or deleted as necessary. Of particular importance within the Kubernetes ecosystem are the RoleBindings and ClusterRoles/Roles. These elements define a permissions framework, where Roles specify the permissions available, and RoleBindings serve to associate those Roles with specific Keycloak groups. This association ensures that members of a group are granted only the permissions that are pertinent to their role.

EKS Keycloak OIDC

Keycloak Configuration​

The initial step involves setting up the Keycloak operator (configure connections to the Keycloak instance) and along creation its associated resources, including realms, clients, roles, and groups.

  1. Create user with necessary privileges to Keycloak:

    Store user credentials in AWS Parameter Store:

    AWS Parameter Store
    {
    "keycloak": {
    "username": "<KEYCLOAK_USERNAME>",
    "password": "<KEYCLOAK_PASSWORD>"
    }
    }
  2. Begin by installing the kuberocketci-rbac add-on. This can be accomplished through the use of the add-ons method, as detailed in the addons approach. Utilize the following values in the values.yaml file:

    values.yaml
    keycloakUrl: "https://example.com"
    # -- This block enable the creation of Keycloak operator resources for the
    # EKS OIDC configuration, such as client, client scope, and realm groups.
    kubernetes:
    enabled: true
  3. Activate the kuberocketci-rbac add-on within the application settings:

    values.yaml
    kuberocketci-rbac:
    createNamespace: true
    enable: true

This add-ons facilitates sets up a broker realm to manage traffic redirection between external Identity Providers (IdP) and internal clients. Additionally, it creates a shared realm that encompasses all clients, including to EKS, Sonar, Nexus, and Portal.

The KubeRocketCI RBAC add-on creates Keycloak groups that are used in the KubeRocketCI platform to manage access to resources. For more details refer to the KubeRocketCI Groups documentation.

AWS Configuration​

Configure Identity provider in kubernetes cluster

For integrating OpenID Connect (OIDC) with Amazon EKS through terraform, it's essential to update the EKS module within your terraform repository. The relevant repository can be found at KubeRocketCI's terraform-aws-platform. Adjust the module by incorporating the following configuration in the eks/template.tfvars file:

eks/template.tfvars
# OIDC Identity provider configuration
cluster_identity_providers = {
keycloak = {
client_id = "eks"
issuer_url = "https://example.com/auth/realms/shared"
groups_claim = "groups"
}
}

This configuration snippet specifies the Keycloak as the OIDC Identity Provider for your EKS cluster. It includes the client ID (eks), the issuer URL (pointing to the Keycloak realm), and the claim used for groups (groups). This setup ensures that authentication and authorization mechanisms for accessing the EKS cluster are correctly configured to use Keycloak as the identity provider.

Kubeconfig​

Template for kubeconfig:

apiVersion: v1
preferences: {}
kind: Config

clusters:
- cluster:
server: https://<eks_url>.eks.amazonaws.com
certificate-authority-data: <certificate_authority_data>
name: eks

contexts:
- context:
cluster: eks
user: <keycloak_user_email>
name: eks

current-context: eks

users:
- name: <keycloak_user_email>
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: kubectl
args:
- oidc-login
- get-token
- -v1
- --oidc-issuer-url=https://<keycloak_url>/auth/realms/shared
- --oidc-client-id=eks
- --oidc-client-secret=<keycloak_client_secret>

Flag -v1 can be used for debug, in a common case it's not needed and can be deleted.

To find the client secret:

  1. Open Keycloak
  2. Choose Shared realm
  3. Find eks keycloak client
  4. Open Credentials tab
  5. Copy Secret

Access Validation​

To validate access to the Kubernetes cluster by using the default cluster-admin role. Assign the user the oidc-cluster-admins Keycloak group.

To add a user to a Keycloak group, follow these steps:

  1. Open Keycloak
  2. Choose Shared realm
  3. Open user screen with search field
  4. Find a user and open the configuration
  5. Open Groups tab
  6. In Available Groups, choose an oidc-cluster-admins group
  7. Click the Join button
  8. The group should appear in the User's Group Membership list

As a result, the required access mapping is implemented using the following resources:

Keycloak Group NameKubernetes ClusterRoleKubernetes ClusterRoleBinding
oidc-cluster-adminscluster-admin (built-in)cluster-admin

In this configuration, the Keycloak oidc-cluster-admins group is mapped to the Kubernetes cluster-admin role. This setup grants members of the oidc-cluster-admins group the necessary permissions to perform administrator management in the Kubernetes cluster. You can further customize access by associating different Keycloak groups with specific Kubernetes roles.

KubeRocketCI follows the same approach for managing access to its resources. For more information, refer to the KubeRocketCI Groups documentation.

Follow the steps below to test the configuration:

  • Run kubectl command, it is important to specify the correct kubeconfig:

    KUBECONFIG=<path_to_oidc_kubeconfig> kubectl get ingresses -n <namespace_name>
  • After the first run and redirection to the Keycloak login page, log in using credentials (login:password) or using SSO Provider. In case of the successful login, you will receive the following notification that can be closed:

    OIDC Successful Login

  • As the result, a respective response from the Kubernetes will appear in the console in case a user is configured correctly and is a member of the correct group and Roles/RoleBindings.

  • If something is not set up correctly, the following output error will be displayed:

    Error from server (Forbidden): ingresses.networking.k8s.io is forbidden:
    User "https://<keycloak_url>/auth/realms/shared#<keycloak_user_id>"
    cannot list resource "ingresses" in API group "networking.k8s.io" in the namespace "<namespace_name>"

Session Update​

To update the session, clear cache. The default location for the login cache:

rm -rf ~/.kube/cache

Access Cluster via Lens​

To access the Kubernetes cluster via Lens, follow the steps below to configure it:

  • Add a new kubeconfig to the location where Lens has access. The default location of the kubeconfig is ~/.kube/config but it can be changed by navigating to File -> Preferences -> Kubernetes -> Kubeconfig Syncs;
  • (Optional) Using Windows, it is recommended to reboot the system after adding a new kubeconfig;
  • Authenticate on the Keycloak login page to be able to access the cluster.
note

Lens does not add namespaces of the project automatically, so it is necessary to add them manually, simply go to Settings -> Namespaces and add the namespaces of a project.

Changing the Lifespan of an Access Token​

By default, the Keycloak token has a lifespan of 5 minutes. To modify this duration refer to the guidelines outlined in this document.