Keycloak Access Management

You can use Keycloak to manage access privileges to applications and dashboards.

Note: Use of the REST API server is not supported in an on premises environment, such as on Windows and Linux. To use the HCL Compass REST API server in a supported environment, deploy the HCL Compass REST API server to a Kubernetes environment. For more information, see Getting Started with HCL Compass Helm Chart.

Compass Access Management

Compass uses Keycloak for SSO identify to verify user identity and Keycloak roles to determine access to Compass applications. For each Compass application, the Compass server publishes a role to Keycloak in the form of:
ccm-{repoName}-{dbName}-application-access

Where repoName is the name of the repository and dbName is the name of the database for the Compass application.

These application access roles must be assigned to a user in Keycloak for the user to see the application as an option upon signing in. At login, Compass uses the users Keycloak assigned roles to allow access to applications. If the user exists in the Compass application and has the appropriate Keycloak application access role assigned to them,then the user will see that application displayed after signing in using SSO.

When users are added or removed from a Compass application, the Compass server assigns and unassigns the corresponding access role to users.

In the case of invalid assignments, a Compass administrator can also trigger a revalidation of role assignmed to users for an application from the Server Setup page in the UI. To do this, navigate to the Server Setup tab in the sidebar and click the Validate SSO button. If all operations were successful, a notification displays.

When this validation option is selected, any users that exist in the Compass application but do not yet exist as users in Keycloak will be created. All roles assigned to users in Keycloak will be revalidated and added or removed depending on whether they exist as members within the Compass application.

Keycloak Admin instructions for new application access

Upon creation of a new Compass application, the Keycloak administrative user must perform additional steps to ensure that users can access the new application. After signing in, the administrative user will see a set of instructions in the UI explaining that they must navigate to the Keycloak administration console and assign themselves the corresponding access role for the newly created application. To do this, navigate to the Users tab in Keycloak and select your username from the list of users. Click on the Role Mappings tab and select your Compass client from the Client Roles dropdown menu. You can then see the access role for your new application available in the Available Roles section. Select your role from the Available Roles section and click the Add selected button to assign the access role to yourself.

After assigning the role to yourself, navigate back to Compass and click the refresh button next to the My Applications header. You should then see your new application in your list of available applications. Click the Let's go button to sign in to your new application.

If you have users that already exist in your application, you must navigate to the Server Setup option on the sidebar and select the Validate SSO button. This ensures that your existing users will be created in Keycloak and assigned the application access role for this new application.

OpenSearch Dashboards Access Management

OpenSearch Dashboards uses Keycloak for SSO user identity verficiation and Keycloak roles to determine access to each Compass applciations analytics data.

For each Compass application, the Compass server publishes two roles to Keycloak:
ccm-{repoName}-{dbName}-dashboards-editor 
ccm-{repoName}-{dbName}-dashboards-viewer

Where repoName is the name of the repository and dbName is the name of the database for the application.

These same two roles are also published to OpenSearch Dashboards with the appropriate rights (read/write or read).

You must create a new client in Keycloak for OpenSearch Dashboards. Add this client to your realm by selecting the Clients option in the Keycloak sidebar. In the Client ID field, enter dashboards-client. In the Root URL field, enter the URL that points to where your OpenSearch Dashboards server is located. Then, click Save.

Configure your dashboard client in the Settings screen. Select the openid-connect option from the dropdown menu for the Client Protocol field. Select confidential as the Access Type for the client. Enter the Valid Redirect URI as the value that you entered for the Root URL field and add /*. Click Save. All other fields are optional.

After creating your OpenSearch dashboards client in Keycloak, you must copy the dashboard client secret to the keycloak.dashboards.client secret property in the keycloak.properties file.

A Role Mapper must be configured in Keycloak to add the ashboard roles assigned to the Keycloak users' token. From the user token, OpenSearch Dashboards allows the user the appropriate access to Dashboards based upon the role. To create the Role Mapper in Keycloak:
  1. Click the Clients tab and select your OpenSearch Dashboards client from the list of clients.
  2. Navigate to the Mappers section for the dashboards client and click the Create button to create a new role mapper.
  3. Give your role mapper a name and select the User Client Role option from the Mapper Type dropdown menu.
  4. Select your dashboards client from the Client ID dropdown menu.
  5. For the Token Claim Name option, enter roles.
  6. Ensure that Add to ID token and Add to access token options are both turned ON. Save the role mapper.

By default, the Compass server assigns the ccm-{repoName}-{dbName}-dashboards-viewer role to all users that exist in an application. As users are added or removed from a Compass application, the Compass server assigns or unassigns the corresponding viewer role to users.

Note: The ccm-{repoName}-{dbName}-dashboards-editor role must be explicitly assigned by the Keycloak admin to users.