Skip to main content
Version: 3.14

AWS EKS OIDC Integration

This page shows how to provision the Keycloak realm, client, group, and user resources needed for EKS OIDC by installing the edp-keycloak-operator via Helm and applying its Custom Resources — Keycloak, KeycloakRealm, KeycloakRealmGroup, KeycloakClientScope, KeycloakClient, and KeycloakRealmUser. It covers only the Keycloak-side resource provisioning; for the end-to-end setup of EKS cluster access — associating Keycloak as the EKS OIDC provider and mapping groups to Kubernetes RBAC roles — see Keycloak as OIDC Provider for AWS EKS.

Prerequisites​

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.

Visit Main Site