Prerequisites​

Before you begin, ensure you have the following:

• Access to the Microsoft Entra Admin Center with administrative privileges.
• A running AWS EKS cluster with the necessary permissions for access and management.
• The kubelogin plugin installed for authenticating to the EKS cluster using OIDC.
• The kubectl CLI tool installed.
• The aws cli tool installed.

Understanding SSO, OIDC, and Microsoft Entra​

In the context of enhancing digital security and user experience, we prioritize the integration of three key elements: Single Sign-On (SSO), OpenID Connect (OIDC), and Microsoft Entra. Here’s how they connect:

• Single Sign-On (SSO) serves as the foundation, enabling users to access multiple applications with one set of login credentials, significantly simplifying the authentication process.

• OpenID Connect (OIDC) builds on the SSO framework by providing an authentication layer, which uses straightforward identity verification to ensure secure and seamless access across services.

• Microsoft Entra (formerly known as Azure Active Directory) is Microsoft's comprehensive identity and access management solution. It supports the implementation of both Single Sign-On (SSO) and OpenID Connect (OIDC), enabling organizations to securely manage user identities and enforce access controls. With its reliable set of tools, Microsoft Entra simplifies authentication, enhances security, and ensures seamless access to applications and services, making it an essential platform for modern identity management.

Together, these technologies streamline the login process, reinforce security, and enhance the user experience by allowing secure, seamless navigation across our digital ecosystem.

Microsoft Entra Overview​

Microsoft Entra, formerly known as Azure Active Directory (Azure AD), is a modern identity and access management solution designed for secure access to applications and services. It provides features like Single Sign-On (SSO), identity federation, and seamless integration with on-premises directories such as LDAP and Active Directory. Microsoft Entra supports industry-standard protocols, including OpenID Connect (OIDC), OAuth 2.0, and Security Assertion Markup Language (SAML) 2.0, making it a versatile solution for managing user identities. By leveraging Microsoft Entra, organizations can enhance security, simplify user access, and avoid the complexities of building identity management features from scratch. For more details, see the Microsoft Entra official documentation.

Create a new Microsoft Entra Tenant​

To get started with Microsoft Entra, you need to create a new tenant in the Microsoft Entra Admin Center. Follow these steps:

1. Log in to the Microsoft Entra Admin Center using your Microsoft account.

   

2. In the left sidebar menu, select Overview section and then navigate to Manage tenants tab.

   

3. Click on Create button to create a new tenant.

   

4. Select the configuration type Workforce.

   

5. Fill in the fields for Tenant Name, Domain Name, and Location.

   note

   The Tenant Name and Domain Name kuberocketci are used as a demonstration examples. In your case, it is recommended to choose names that align with your organization's specific needs and naming conventions.

   

6. The new tenant will be created, and you can start configuring it for OIDC integration. Ensure you have switched to the new tenant.

Creating and Configuring OIDC Application in Microsoft Entra​

After creating the tenant, you need to set up an OIDC Application in Microsoft Entra. Here's how you can do it:

1. In the Microsoft Entra Admin Center, in the left sidebar menu, select Applications and then click on App registrations.

   

2. Click on the New registration button to create a new application.

   

3. Fill in the details for the application, such as Name, Supported account types, and Redirect URI (http://localhost:8000/).

   note

   The Name kuberocketci is used as a demonstration example. In your case, it is recommended to choose a name that aligns with your application's specific needs and naming conventions (e.g. your AWS EKS cluster name).

   

4. In the created application, navigate to the Authentication section from the left sidebar menu. In the Implicit grant and hybrid flows section, select ID tokens for the token type. In the Allow public client flows section, set the value to No.

   

5. Navigate to the Certificates & secrets section from the left sidebar menu. In the Client secrets tab, click on the New client secret button to create a new secret.

   

6. Copy the generated client secret value and store it securely.

   

7. Navigate to the Token configuration section and click on Add group claim button. Choose the group type as Security Groups and for the ID token type, select Group ID.

   

8. (Optional) Additionally, add an optional upn claim in the Token configuration section.

   note

   This step is optional and should only be performed if external users (i.e., users with User type: Guest) will be added to the Microsoft Entra Tenant and require access to the Application.

   

9. (Optional) After adding the upn claim, click on the three dots next to it, select Edit, and turn on the Externally authenticated toggle to Yes value.

   note

   This step is optional and should only be performed if external users (i.e., users with User type: Guest) will be added to the Microsoft Entra Tenant and require access to the Application.

   

10. Navigate to the API permissions section. Ensure that the User.Read permission is added under the Microsoft Graph API. If not, click on the Add a permission button, select Microsoft Graph, and add the User.Read permission. After adding the permission, click on the Grant admin consent for 'Tenant name' button to grant the required permissions.

    

11. (Optional) Additionally, for Microsoft Graph API, add the OpenId permissions, such as openid, email, and profile.

    note

    This step is optional and should only be performed if external users (i.e., users with User type: Guest) will be added to the Microsoft Entra Tenant and require access to the Application.

    

12. The OIDC Application in Microsoft Entra is now configured and ready for integration with AWS EKS.

Creating Users and Groups in Microsoft Entra​

To create users and groups in Microsoft Entra, follow these steps:

Creating a Group​

1. In the Microsoft Entra Admin Center, in the left sidebar menu, select Groups and then All groups. Click on New group button to create a new group(s) for users who will have access to the AWS EKS cluster.

   

2. Fill in the details for the group, such as Group type and Group name. Click on the Create button to create the group.

   

3. The group will be created, and you can start adding users to it.

Adding Users to the Group​

1. In the Microsoft Entra Admin Center, in the left sidebar menu, select Users and then click on All users. In the New user tab, click on the Create new user button to create a new user.

   

2. Fill in the details for the user, such as User principal name, Mail nickname, Display name, and temporary password. In the Properties tab you can set the First name, Last name, and other details.

   

3. In the Assignment tab, click on the Add group button. In the Select Group window, choose the group(s) you created earlier (e.g., oidc-cluster-admins) and click on the Select button.

   

4. Click on the Review + create button to create the user. The user will be created and added to the group(s) you selected.

Configuring Microsoft Entra as an Identity Provider in AWS EKS​

There are two methods to configure Microsoft Entra as an Identity Provider in AWS EKS: through the AWS Management Console and using Terraform.

Method 1: Using the AWS Management Console​

1. Log in to the AWS Management Console and navigate to the Amazon EKS console. Select the EKS cluster you want to configure and click on the Access tab.

   

2. In the OIDC identity providers section, click on the Associate identity provider button.

   

3. Fill in the following details:

   • Name: Entra

   • Issuer URL: https://login.microsoftonline.com/<Tenant-ID>/, where <Tenant-ID> is the Directory (tenant) ID. Ensure that the URL ends with /.

   • Client ID: <Application (client) ID>, which corresponds to the Application (client) ID of the OIDC Application.

   • Username Claim: upn.

   • Groups Claim: groups.

     

4. The process of applying the changes may take a few minutes. Once completed, the Microsoft Entra OIDC identity provider will be associated with the AWS EKS cluster.

Method 2: Using Terraform​

To configure Microsoft Entra as an Identity Provider in AWS EKS using Terraform, you can use AWS EKS Terraform module. Here's an example of how you can do it:

• variables.tf:

variable "cluster_identity_providers" {
  description = "Configuration for OIDC identity provider"
  type        = any
  default     = {}
}

• terraform.tfvars:

cluster_identity_providers = {
  entra = {
    client_id    = "<Application (client) ID>"
    issuer_url   = "https://sts.windows.net/<Tenant ID>/"
    groups_claim = "groups"
    username_claim  = "upn"
  }
}

• main.tf:

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "20.14.0"
  ...
  # OIDC Identity provider
  cluster_identity_providers = var.cluster_identity_providers
}

After applying the Terraform configuration, the Microsoft Entra OIDC identity provider will be associated with the AWS EKS cluster.

Configuring RBAC Resources in AWS EKS cluster for Microsoft Entra User Groups​

In this section, user authorization will be configured using Kubernetes Role-Based Access Control (RBAC). Microsoft Entra groups will be linked to Kubernetes ClusterRoles through ClusterRoleBinding resources, enabling precise control over resource access within the EKS cluster. Additionally, Roles and RoleBindings can be used for more granular access control within specific namespaces.

1. Log in to the AWS EKS cluster and create the following ClusterRoleBinding resource, which associates the Microsoft Entra group oidc-cluster-admins with the cluster-admin Kubernetes Cluster Role. Replace <your-microsoft-entra-admin-group-object-id> with the Object ID of the oidc-cluster-admins group, which can be found on the Group overview page in the Microsoft Entra admin center.

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: oidc-cluster-admins
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: cluster-admin
   subjects:
     - kind: Group
       name: <your-microsoft-entra-admin-group-object-id>
       apiGroup: rbac.authorization.k8s.io
   

   Save the above YAML to a file, for example, clusterrolebinding.yaml, and apply it to the EKS cluster using the following command:

   kubectl apply -f clusterrolebinding.yaml
   

   The oidc-cluster-admins group will now have cluster-admin permissions within the EKS cluster.

Authenticating to AWS EKS using Microsoft Entra with kubectl​

To authenticate to the AWS EKS cluster using Microsoft Entra, you can use the kubectl CLI tool with the kubelogin plugin. The kubelogin plugin simplifies the OIDC authentication process by handling the token exchange and session management. Here's how you can authenticate to the EKS cluster:

1. Create or update the kubeconfig file with the OIDC configuration. Replace <cluster-name> with the name of your EKS cluster and <region-code> with the AWS region code where the cluster is located.

   aws eks update-kubeconfig --region <region-code> --name <cluster-name>
   

2. Execute the following command to create a new kubeconfig context using the kubelogin plugin. Replace <cluster-name> with the name of your EKS cluster.

   kubectl config set-credentials "eks" \
     --exec-api-version=client.authentication.k8s.io/v1beta1 \
     --exec-command=kubelogin \
     --exec-arg=get-token \
     --exec-arg=--oidc-issuer-url \
     --exec-arg=https://sts.windows.net/<Tenant ID>/ \
     --exec-arg=--oidc-client-id \
     --exec-arg=<Application (client) ID> \
     --exec-arg=--oidc-client-secret \
     --exec-arg=<Application (client) Secret>
   

   Replace <Tenant ID>, <Application (client) ID>, and <Application (client) Secret> with the corresponding values from the OIDC Application in the Microsoft Entra Admin Center.

   note

   You can test the authentication to the EKS cluster immediately by running the following command:

   kubectl --user=eks get nodes
   

3. Set the context for the kubeconfig file to use the eks user and the OIDC configuration. Replace <cluster-name> with the name of your EKS cluster.

   kubectl config set-context eks --user=eks --cluster=<cluster-name>
   

   To switch to the eks context, execute the following command:

   kubectl config use-context eks
   

   Test the authentication by running the following command:

   kubectl get nodes
   

Configuring KubeRocketCI Portal with Microsoft Entra OIDC Authentication​

1. Starting from version 3.10, KubeRocketCI platform supports Microsoft Entra as an Identity Provider for OIDC authentication in the Portal UI. To configure Microsoft Entra OIDC authentication, navigate to the edp-install Helm chart repository and set the following values in the values.yaml file:

   ...
   edp-headlamp:
     enabled: true
     config:
       oidc:
         enabled: true
         issuerUrl: "https://sts.windows.net/<Tenant ID>/"
         clientID: "<Application (client) ID>"
         clientSecretName: "<name of the secret containing the client-secret value>"
         clientSecretKey: "clientSecret"
   ...
   

   Replace <Tenant ID> and <Application (client) ID> with the corresponding values from the OIDC Application in the Microsoft Entra Admin Center. Also, specify the name of the Kubernetes Secret containing the Application Client secret value in the clientSecretName field.

2. In the Microsoft Entra Admin Center, navigate to the created OIDC Application and select the Authentication section. In the Redirect URIs field, add the URL of the KubeRocketCI Portal, for example, https://portal-<krci-namespace>.<dns-wildcard>/oidc-callback.

   

3. After applying the changes, the KubeRocketCI Portal will be configured to use Microsoft Entra OIDC authentication. Users will be able to log in to the Portal using Sign In option.

   

Conclusion​

Integrating OpenID Connect (OIDC) authentication with Microsoft Entra in AWS EKS is a powerful way to enhance security and streamline user access management. By leveraging the capabilities of SSO, OIDC, and Microsoft Entra, organizations can simplify authentication processes, enforce access controls, and ensure secure navigation across cloud-native environments. Whether you're managing user identities, enhancing compliance, or improving user experience, this integration provides a robust solution to meet your identity and access management needs. By following the steps outlined in this guide, you can configure Microsoft Entra as an Identity Provider in AWS EKS, authenticate users using OIDC, and secure access to your EKS clusters and KubeRocketCI Portal effectively.

Prerequisites​

Before you begin, ensure you have the following:

• A running AWS EKS cluster with the necessary permissions for access and management.
• Forked and cloned the edp-cluster-add-ons repository.
• The kubelogin plugin installed for authenticating to the EKS cluster using OIDC.
• The kubectl cli tool installed.
• The aws cli tool installed.
• Keycloak installed and configured with the kuberocketci-rbac Helm chart, which can be found in the add-ons repository.
• The Keycloak-operator installed.

Understanding SSO, OIDC, and Keycloak​

In the context of enhancing digital security and user experience, we prioritize the integration of three key elements: Single Sign-On (SSO), OpenID Connect (OIDC), and the Keycloak solution. Here’s how they connect:

• Single Sign-On (SSO) serves as the foundation, enabling users to access multiple applications with one set of login credentials, significantly simplifying the authentication process.

• OpenID Connect (OIDC) builds on the SSO framework by providing an authentication layer, which uses straightforward identity verification to ensure secure and seamless access across services.

• Keycloak acts as the orchestrator, implementing both SSO and OIDC to manage user identities and security protocols efficiently. It provides a comprehensive platform for securing applications and services with minimal hassle for end-users.

Together, these technologies streamline the login process, reinforce security, and enhance the user experience by allowing secure, seamless navigation across our digital ecosystem.

What is SSO?​

Single sign-on (SSO) is a user authentication method that lets you use one set of login credentials (such as a username and password) to access multiple applications. The primary benefits of SSO include an improved user experience by eliminating the need for multiple passwords and logins, and enhanced security through centralized management of user access. Organizations widely adopt SSO to streamline their authentication processes and reduce the likelihood of password fatigue among users, thereby decreasing the risk of security breaches. For more information, see Single sign-on on Wikipedia.

This diagram shows the following steps:

1. User logs in once at the single sign-on (SSO) gateway by providing their credentials.
2. The SSO gateway authenticates the user, creates a session, and then allows the user to access multiple applications.
3. When the user attempts to access Application 1, the application verifies the user's session with the SSO gateway.
4. The SSO gateway confirms that the session is valid, and Application 1 grants the user access.

The same process is repeated for Application 2 and Application 3. Since the user's session is already established with the SSO gateway, they do not need to log in again to access these applications.

Understanding OIDC​

OpenID Connect (OIDC) is an authentication layer on top of the OAuth 2.0 protocol. It lets clients verify the identity of the end user based on authentication by an authorization server and get basic profile information about the end user in an interoperable and REST-like manner. OIDC uses JSON Web Tokens (JWTs) to securely transmit information about an end user from the identity provider to the client. This protocol is essential for modern web applications, providing a more secure and streamlined method for user authentication and authorization. Reference: OIDC Specification

OIDC enables single sign-on (SSO) functionality, simplifying the user experience by allowing individuals to use a single set of credentials across multiple applications. The protocol also supports robust security features, including token revocation and introspection, enhancing overall application security.

This diagram simplifies the OIDC flow into its core components:

1. User (U): The end user who wants to access the client application.
2. Client Application (C): The application requiring authentication from the user.
3. Authorization Server (AS): The server that authenticates the user and issues tokens to the client application.
4. Resource Server (RS): The server hosting protected resources that the client application wants to access on behalf of the user.

The sequence starts with the user requesting access to the client application, moving through authentication with the authorization server, and ending with the client application accessing protected resources.

Keycloak Overview​

Keycloak is an open-source identity and access management solution for modern applications and services. It offers features like single sign-on (SSO), social login, and identity brokering, making it a comprehensive solution for managing user identities. Keycloak integrates seamlessly with LDAP (Lightweight Directory Access Protocol) and Active Directory and supports OpenID Connect (OIDC), OAuth 2.0, and Security Assertion Markup Language (SAML) 2.0. By using Keycloak, organizations can enhance their security and provide a better user experience without building complex identity management features from scratch. For more details, see the Keycloak official documentation.

Keycloak Configuration​

The first step to enable OIDC authentication to the AWS EKS cluster using Keycloak is to set up Keycloak with the necessary configurations, such as realm, client, groups, and other settings. For this purpose, we will use the kuberocketci-rbac Helm chart available in the edp-cluster-add-ons repository.

1. Clone the forked edp-cluster-add-ons repository and navigate to the clusters/core/addons/kuberocketci-rbac directory.

2. In the values.yaml file, set the kubernetes.enabled field to true to enable the creation of the necessary Keycloak resources:

   values.yaml

   kubernetes:
     enabled: true
   

3. If you use the External Secrets Operator to manage secrets, ensure the AWS Parameter Store object contains the correct Client Secret value for the keycloak-client-eks-secret secret:

   AWS Parameter Store object

   {
     ...
     "keycloak-client-eks-secret": {
       "clientSecret": "<Client_Secret_Value>"
     },
     ...
   }
   

   If you are not using the External Secrets Operator, you can create the keycloak-client-eks-secret secret manually:

   kubectl create secret generic keycloak-client-eks-secret \
     --from-literal=clientSecret=<Client_Secret_Value>
   

4. Install the kuberocketci-rbac Helm chart. You can use the kubectl cli tool or Argo CD for this purpose.

   • kubectl

   Ensure you are in the clusters/core/addons/kuberocketci-rbac directory if you want to install the chart with the kubectl command. For example:

   kubectl upgrade --install kuberocketci-rbac -n security .
   

   • Argo CD

   If you are using Argo CD to deploy charts in the edp-cluster-add-ons repository, ensure that the following fields for the kuberocketci-rbac Helm chart are correctly set in the values.yaml file in the clusters/core/apps directory:

   values.yaml

   kuberocketci-rbac:
     createNamespace: false
     enable: true
   

   After the installation is complete, check that the Keycloak resources, such as the realm, client, and groups, have been created successfully.

Adding Users to Groups in Keycloak​

To manage user access to the AWS EKS cluster, you need to assign users to specific groups in Keycloak. These groups will define the permissions for users accessing the AWS EKS cluster.

1. Log in to the Keycloak admin console and navigate to the shared realm.

2. Select the Users section from the left sidebar menu and select the user you want to add to a group. Navigate to the Groups tab and click on the Join Group button to add the user to a group.

   

3. Select the group you want to add the user to (e.g., oidc-cluster-admins). Click on the Join button to add the user to the selected group.

   

4. Repeat the process of adding users to groups for all users who need access to the AWS EKS cluster.

Configuring Keycloak as an Identity Provider in AWS EKS​

There are two methods to configure Keycloak as an identity provider in AWS EKS: using the AWS Management Console or Terraform.

Method 1: Using the AWS Management Console​

1. Log in to the AWS Management Console and navigate to the Amazon EKS service. Select the EKS cluster you want to configure and click on the Access tab.

   

2. In the OIDC identity providers section, click on the Associate identity provider button.

   

3. Fill in the following details for the Keycloak Identity Provider:

   • Name: Keycloak

   • Issuer URL: https://<keycloak_url>/auth/realms/shared, where <keycloak_url> is the URL of your Keycloak instance.

   • Client ID: eks.

   • Groups Claim: groups.

     

4. The process of applying the changes may take a few minutes. Once completed, you will see the Keycloak Identity Provider associated with your EKS cluster.

Method 2: Using Terraform​

To configure Keycloak as an Identity Provider in AWS EKS cluster using Terraform, you can use the AWS EKS Terraform module. Here's an example of how to define the Keycloak Identity Provider in Terraform configuration files:

• variables.tf:

variable "cluster_identity_providers" {
  description = "Configuration for OIDC identity provider"
  type        = any
  default     = {}
}

• terraform.tfvars:

cluster_identity_providers = {
  keycloak = {
    client_id    = "eks"
    issuer_url   = "https://<keycloak_url>/auth/realms/shared"
    groups_claim = "groups"
  }
}

• main.tf:

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "20.14.0"
  ...
  # OIDC Identity provider
  cluster_identity_providers = var.cluster_identity_providers
}

After applying the Terraform configuration, the Keycloak identity provider will be associated with your EKS cluster.

Authenticating to AWS EKS cluster using kubectl​

1. Configure kubeconfig file to use the Keycloak Identity Provider for authentication to the AWS EKS cluster. You can use the following template:

   kubeconfig

   apiVersion: v1
   preferences: {}
   kind: Config
   
   clusters:
   - cluster:
       server: https://<eks_cluster_endpoint>.eks.amazonaws.com
       certificate-authority-data: <eks_cluster_ca>
     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>
   

   Replace the placeholders with the actual values:

   • <eks_cluster_endpoint>: The endpoint of your AWS EKS cluster.
   • <eks_cluster_ca>: The CA certificate of your AWS EKS cluster.
   • <keycloak_user_email>: The email address of the Keycloak user.
   • <keycloak_url>: The URL of your Keycloak instance.
   • <keycloak_client_secret>: The Client secret of the eks Keycloak client (provided during the Keycloak Configuration step).

2. Save the kubeconfig file and set the KUBECONFIG environment variable to point to the file:

   export KUBECONFIG=<path_to_kubeconfig_file>
   

3. Test the authentication to the AWS EKS cluster by running the following command:

   kubectl get nodes
   

   After the first command execution, you will be prompted to log in to Keycloak. Enter your credentials to authenticate and access the EKS cluster. If the authentication is successful, you will see the list of nodes in the EKS cluster.

Configuring KubeRocketCI Portal with Keycloak OIDC Authentication​

The KubeRocketCI platform natively supports Keycloak as an Identity Provider for OIDC authentication.

1. To configure the KubeRocketCI Portal with Keycloak OIDC authentication, navigate to the edp-install Helm chart and set the following values in the values.yaml file:

   values.yaml

   edp-headlamp:
     enabled: true
     config:
       oidc:
         enabled: true
         issuerUrl: "https://<keycloak_url>/auth/realms/shared"
         clientID: "eks"
         clientSecretName: "keycloak-client-headlamp-secret"
         clientSecretKey: "clientSecret"
   

   Replace the keycloak_url with the URL of your Keycloak instance.

2. Ensure the AWS Parameter Store object contains the correct Client Secret value for the keycloak-client-headlamp-secret secret:

   AWS Parameter Store object

   {
     ...
     "keycloak-client-headlamp-secret": "<Client_Secret_Value>"
     ...
   }
   

3. After setting the values, install the edp-install Helm chart to apply the changes:

   helm upgrade --install krci --namespace krci .
   

4. After applying the changes, the KubeRocketCI Portal will be configured to use Keycloak OIDC authentication. Users will be able to log in to the Portal using Sign In option.

   

Conclusion​

Integrating OpenID Connect (OIDC) authentication with Keycloak in AWS EKS enhances security and simplifies user access management. By leveraging Keycloak's capabilities, you can implement a reliable Single Sign-On (SSO) solution that meets your organization's security standards. This guide has provided step-by-step instructions to configure Keycloak as an Identity Provider, set up necessary Keycloak resources, and enable OIDC authentication for the KubeRocketCI Portal. By following these steps, you can ensure secure and seamless access to your EKS clusters and KubeRocketCI Portal, improving both security and user experience.