Configuring keycloak using OICD

Hey everyone, In this blog we will see how you can configure Keycloak using OICD. Before we start, make sure you have deployed Keycloak, we will be self-hosting it on Elestio.

What is Keycloak?

Keycloak is an open-source Identity and Access Management (IAM) solution that provides tools for managing authentication and authorization. It enables single sign-on (SSO) and identity federation, supporting various protocols like OpenID Connect, OAuth 2.0, and SAML 2.0, which allows integration with a wide range of applications and services. Keycloak's features include user management, role-based access control, multi-factor authentication, and customization options through themes and extensions. It operates as a central authentication server, issuing tokens to clients and validating them to ensure secure access to protected resources, making it ideal for enterprise SSO, cloud and microservices architectures, and secure API management.

Introduction to OIDC

OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0, designed to verify user identities and provide user profile information in a standardized and secure manner. It facilitates single sign-on (SSO) by issuing ID tokens, which are JSON Web Tokens (JWT) containing user information such as name and email, after successful authentication by an authorization server. OIDC is widely used across web, mobile, and cloud applications, offering and secure user authentication and enabling integration with various identity providers.

Creating an OIDC Client in Keycloak

Integrating Keycloak with your Identity Provider (IDP) server using OpenID Connect (OIDC) involves creating and configuring an OIDC client. This client acts as an intermediary that handles authentication requests and responses between your application and the IDP server. Proper configuration of the OIDC client ensures secure communication and accurate handling of authentication tokens.

Steps to Create the OIDC Client

1. Access the Clients Section :
   • Begin by selecting the appropriate realm from the left pane in Keycloak. The realm represents your security domain, where all configurations and user data are stored.
   • Navigate to Clients. This section lists all the clients (applications) that can request authentication from Keycloak.
2. Create a New Client :
   • Click Create in the right pane. This action initiates the process of setting up a new client.
   • Enter a name in the Client ID field. This name will be used as the client_id in OIDC authentication requests. It uniquely identifies your client application within the realm.
   • Click Save to proceed. Saving the client ID takes you to the client configuration page where you can specify further details.
3. Configure the Client :Setting the correct redirect URIs is crucial as it ensures the IDP server can safely redirect users back to your application after authentication, maintaining the flow’s security.
   • In the client configuration page, set the Client Protocol field to openid-connect. This protocol facilitates secure authentication and authorization.
   • Set the Access Type to confidential. Confidential clients are capable of keeping their credentials secure, making them suitable for server-side applications.
   • Add the Valid Redirect URIs for the IDP server. These URIs specify where the IDP server should redirect users after successful authentication. The URL should follow the structure https://[CNAME]/*, ensuring it aligns with your server’s configuration. For example, https://www.idpserver.com/*.

Adding Scope to the Client

Scopes in Keycloak define the permissions and data included in authentication tokens. Adding a client scope customizes the information shared during the authentication process, ensuring that only the necessary data is transmitted.

1. Access Client Scopes :
   • Navigate to the Client Scopes section by selecting the relevant realm in the left pane.
   • Click Create to initiate the creation of a new client scope.
2. Create a New Scope :Adding a scope helps control what information is shared and how it is presented in tokens, contributing to a more secure and efficient authentication process.
   • Enter idpvscope in the Name field. This name will help you identify the scope later.
   • Set the Display on Consent screen option to OFF. Disabling this option ensures that the scope will not be displayed on the user consent screen during authentication.
   • Click Save to finalize the creation of the scope.

Mapping the Client Scope

Mapping client scopes involves adding claims to tokens. Claims are pieces of information about the user, such as username or group memberships, that the IDPV server requires. Proper mapping ensures that the necessary data is included in the tokens issued during authentication.

1. Add a Mapper :
   • In the left pane, go to Client Scopes and select the newly created scope.
   • In the right pane, navigate to Mappers > Create.
2. Create Protocol Mapper :Adding mappers for specific attributes like preferred_username ensures that these details are included in the tokens, making them available for the IDPV server to use during authentication.
   • For the User Attribute Mapper Type , configure the following:
   • Name : preferred_username
   • Mapper Type : User Attribute
   • User Attribute : cn
   • Token Claim Name : preferred_username
   • Click Save to save this mapper.
3. Add Group Membership Mapper :Including group membership information in tokens helps manage user roles and permissions, ensuring that only authorized users can access specific resources.
   • For the Group Membership Mapper Type , configure the following:
   • Name : groups
   • Mapper Type : Group Membership
   • Token Claim Name : groups
   • Click Save to save this mapper.
4. Repeat for Additional Claims : Similarly, add other required claims to ensure that all necessary information is included in the tokens. Each claim added through mappers enhances the granularity and control over user data shared during authentication.

Adding Scope to the OpenID Client

After configuring the necessary claims, the next step is to apply the scope to the OpenID client. This ensures that tokens issued for this client will include the required claims, completing the setup for secure and customized authentication.

1. Apply Scope to OpenID Client :Applying the scope to the OpenID client ensures that the authentication tokens issued will contain the claims defined in the scope, providing the necessary information to the IDPV server.
   • In the left pane, select Clients.
   • In the right pane, choose the client you created earlier and go to the Client Scopes tab.
   • Under Default Client Scopes , select the previously created scope and click Add selected.

Thanks for reading ❤️

Thank you so much for reading and do check out the Elestio resources and Official Keycloak documentation to learn more about Keycloak. Click the button below to create your service on Elestio. See you in the next one👋