Keycloak integration

Keycloak provides open source identity and access management and can be integrated with DevOps Plan to help you manage your DevOps Plan users.

1. In Keycloak, if you do not already have a Realm, you must create one. Using the Select Realm dropdown menu, select Add Realm. Provide a name for your realm and click Create.
   If you use Keycloak in environments outside of DevOps Plan and you have already created a realm, you can skip this step.
2. In your realm, under Configure, select User Federation or Identity Providers. Which option you choose will depend on which user authentication service you plan to use.
   Note: If you are configuring an identity provider in Keycloak, you must create a new authentication flow for that identity provider so that Keycloak detects users on their first login. The DevOps Plan server automatically creates users in Keycloak when a user is invited.

   This authentication flow must be created and set for the identity providers First Login Flow option. This will ensure that when a user signs in for the first time using the credentials from their identity provider, that the user will be appropriately mapped to the already created user in Keycloak.

   For more information on creating and configuring the authentication flow, see Automatically link existing first login flow.

3. Add a client to your realm by selecting Clients. In the Client ID field, enter in an ID that is specific to DevOps Plan. Enter in values for Client Protocol and Root URL. The Root URL field must point to where your DevOps Plan REST API server is located. Click Save.
4. Configure your client in the Settings screen. Ensure that the Access Type is set to Public, and that you have values entered in both the Valid Redirect URIs and the Web Origins fields. These are the only fields that are required to setup Keycloak with DevOps Plan. All others fields are optional
5. Download the keycloak.json file for the client by selecting the Action dropdown and choosing the Download adapter config option. A dialog box will appear. Select Keycloak OIDC JSON as your format from Format option dropdown and then select Download.
6. Configure Keycloak in DevOps Plan.
   1. enable Keycloak integration in the application.properties file. Set keycloak.enabled=true.
   2. Copy the keycloak.json file to the REST API servers /share folder.
   3. Restart the DevOps Plan REST API server.
   4. The keycloak.api.url property in the keycloak.properties file located in the /share folder must be updated the have the url of where Keycloak is located. The setupKeycloak.pl script must be run to create a system user within Keycloak which the rest-server uses to interact with Keycloak. The syntax for the script is:

      CQPerl setupKeycloak.pl <keycloak_realm> <keycloak_admin_user_name>

7. When configuring DevOps Plan, an DevOps Plan user with the Keycloak login name must be created in the DevOps Plan user administration. The Keycloak login name can vary based upon the User Federation that is being used. By default, DevOps Plan uses the preferred_username field from Keycloak to determine the DevOps Plan username. To change this to email, update the keycloak-mapping-field in the application.properties file.
   Note: DevOps Plan administrative users can add Keycloak users without needing to create a user in the DevOps Plan Administration Tool. The administrative user must:

   • Be a Keycloak user
   • Have the view-users role assigned to them. To check, click Role Mappings > Client Roles > Realm Management > Assigned Role. If view-users is listed in the Assigned Role field, you can create DevOps Plan users without needing to use the DevOps Plan administration tool.

   To create a DevOps Plan user from within the UI, perform the followings steps:

   1. Click the Members tab.
   2. Click the + sign to add a user.
   3. The search box will search for users in Keycloak and in DevOps Plan. If the user is listed in Keycloak, but not listed in DevOps Plan, DevOps Plan will create a DevOps Plan user for that member.
   4. Click Add Member.

   When searching for users, if you encounter a message that says You do not have privileges to view Keycloak users, go to Keycloak and ensure that the DevOps Plan administrative user has the view-users role assigned to them in Keycloak.
8. Additional notes:
   Note: The DevOps Plan REST API server publishes tenant access client roles in Keycloak every time a user has been added to a tenant. The roles will have the following format:

   ccm:{tenantId}:access

   Note: Keycloak stores session information in cookies. The KEYCLOAK_SESSION cookie is used to store the state of the Keycloak session. They Keycloak session duration is based upon the SSO Session Max setting in Keycloak. Upon logging out of DevOps Plan, you are ending your DevOps Plan sessions, but you are not signing out of the active Keycloak session. Therefore, your Keycloak session will remain active until the session expires after the user is inactive for the amount of time that is configured in the SSO Session Idle setting or if the SSO Session Max is reached.