Version: 3.9

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:

Add the epamedp Helm chart to a local client:

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

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:

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>

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

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

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

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"

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"

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

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

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.

Prerequisites​

Install Keycloak Operator​

Connect Keycloak Operator to Keycloak​

Related Articles​

Prerequisites

Install Keycloak Operator

Connect Keycloak Operator to Keycloak

Related Articles