AWS EKS OIDC Integration

This page serves as a comprehensive guide on integrating Keycloak with the edp-keycloak-operator to act as an identity provider for AWS Elastic Kubernetes Service (EKS). It provides detailed step-by-step instructions for creating the necessary realms, users, roles, and client configurations to seamlessly collaborate between Keycloak and EKS. Additionally, it includes instructions on installing the edp-keycloak-operator using Helm charts.

Prerequisites

• EKS Configuration is performed;
• Helm v3.10.0 is installed;
• Keycloak is installed.

Install Keycloak Operator

info

Alternately, the edp-keycloak-operator can be installed using a GitOps approach via the edp-cluster-add-ons repository. For detailed installation instructions, please refer to the Install via Add-ons guide.

To install the Keycloak operator, follow the steps below:

1. Add the epamedp Helm chart to a local client:

   helm repo add epamedp https://epam.github.io/edp-helm-charts/stable
   helm repo update

2. Install the Keycloak operator:

   helm install keycloak-operator epamedp/keycloak-operator --namespace security --set name=keycloak-operator

Connect Keycloak Operator to Keycloak

info

It is also possible to install Keycloak resources using the edp-cluster-add-ons repository. For details, please refer to the Install via Add-Ons page.

The next stage after installing Keycloak is to integrate it with the Keycloak operator. It can be implemented with the following steps:

1. Create the keycloak secret that contains username and password defined on the configuration step:

   kubectl -n security create secret generic keycloak \
     --from-literal=username=<username> \
     --from-literal=password=<password>

2. Create the Keycloak Custom Resource with the Keycloak instance URL and the secret created in the previous step:

   apiVersion: v1.edp.epam.com/v1
   kind: Keycloak
   metadata:
     name: main
     namespace: security
   spec:
     secret: keycloak                   # Secret name
     url: https://keycloak.example.com  # Keycloak URL

3. Create the KeycloakRealm Custom Resource:

   apiVersion: v1.edp.epam.com/v1
   kind: KeycloakRealm
   metadata:
     name: control-plane
     namespace: security
   spec:
     realmName: control-plane
     keycloakOwner: main

4. Create the KeycloakRealmGroup Custom Resource for both administrators and developers:

   • administrators:

     apiVersion: v1.edp.epam.com/v1
     kind: KeycloakRealmGroup
     metadata:
       name: administrators
       namespace: security
     spec:
       realm: control-plane
       name: eks-oidc-administrator

   • developers:

     apiVersion: v1.edp.epam.com/v1
     kind: KeycloakRealmGroup
     metadata:
       name: developers
       namespace: security
     spec:
       realm: control-plane
       name: eks-oidc-developers

5. Create the KeycloakClientScope Custom Resource:

   apiVersion: v1.edp.epam.com/v1
   kind: KeycloakClientScope
   metadata:
     name: groups-keycloak-eks
     namespace: security
   spec:
     name: groups
     realm: control-plane
     description: "Group Membership"
     protocol: openid-connect
     protocolMappers:
       - name: groups
         protocol: openid-connect
         protocolMapper: "oidc-group-membership-mapper"
         config:
           "access.token.claim": "true"
           "claim.name": "groups"
           "full.path": "false"
           "id.token.claim": "true"
           "userinfo.token.claim": "true"

6. Create the KeycloakClient Custom Resource:

   apiVersion: v1.edp.epam.com/v1
   kind: KeycloakClient
   metadata:
     name: eks
     namespace: security
   spec:
     advancedProtocolMappers: true
     clientId: eks
     directAccess: true
     public: false
     defaultClientScopes:
       - groups
     targetRealm: control-plane
     webUrl: "http://localhost:8000"

7. Create the KeycloakRealmUser Custom Resource for both administrator and developer roles:

   • administrator:

     apiVersion: v1.edp.epam.com/v1
     kind: KeycloakRealmUser
     metadata:
       name: keycloakrealmuser-admin
       namespace: security
     spec:
       realm: control-plane
       username: "administrator"
       firstName: "John"
       lastName: "Snow"
       email: "administrator@example.com"
       enabled: true
       emailVerified: true
       password: "12345678"
       keepResource: true
       requiredUserActions:
         - UPDATE_PASSWORD
       groups:
         - eks-oidc-administrator

   • developer:

     apiVersion: v1.edp.epam.com/v1
     kind: KeycloakRealmUser
     metadata:
       name: keycloakrealmuser-developer
       namespace: security
     spec:
       realm: control-plane
       username: "developers"
       firstName: "John"
       lastName: "Snow"
       email: "developers@example.com"
       enabled: true
       emailVerified: true
       password: "12345678"
       keepResource: true
       requiredUserActions:
         - UPDATE_PASSWORD
       groups:
         - eks-oidc-developers

8. To connect the created Keycloak resources with permissions, it is necessary to bind the created Keycloak groups to Kubernetes roles, e.g., assigning the Keycloak group administrators the Kubernetes Cluster role cluster-admin.

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: oidc-cluster-admins
   subjects:
     - kind: Group
       apiGroup: rbac.authorization.k8s.io
       name: administrators
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: cluster-admin

9. As a result, Keycloak is integrated with the AWS Elastic Kubernetes Service. This integration allows users to easily log in to the EKS cluster using their kubeconfig files and kubelogin, while managing permissions through Keycloak. This seamless integration enhances the user experience and streamlines the management of access control within the KubeRocketCI platform.

Related Articles

• Keycloak Installation
• EKS OIDC With Keycloak