Keycloak

Axiomatics Services Manager (ASM) uses Keycloak for authentication and access management services in its implementation.

The configuration needed for the interaction between ASM and Keycloak is below.

Disclaimer

There are many features and options available in Keycloak. However, only settings and configurations explicitly mentioned in the Axiomatics Services Manager documentation are supported. Axiomatics assumes no responsibility or liability for the use of other configuration options.

For more information about Keycloak configuration options, please refer to the Keycloak documentationOpens in a new tab.

Manage users in Keycloak

During the installation of ASM, a Keycloak service is also installed, to serve as an authentication module.

Only a default administrative user is created automatically during the installation. All other users must be created and assigned a role in Keycloak, before they can log in to ASM.

Log in to Keycloak

1. Open a web browser window and go to:

   Default hostname

   https://localhost/auth if you are using the default hostname.

   Custom hostname

   Append /auth to the hostname you are using. For example, https://example.com/auth.

2. Open the Administration Console and use the default credentials to log in:

   • Default username: admin

   • Default password: admin

   note

   Axiomatics strongly recommends changing the password immediately. See Keycloak docs: User CredentialsOpens in a new tab for details.

Create a user in Keycloak

All users, except the default administrative user, must be created and assigned a role in Keycloak before they can log in to ASM.

1. Make sure that the asm realm is selected.

2. In the menu, under the Manage section, click Users.

3. Click Add User.

   The Create user page displays.

4. Enter a name in the Username field, which is required. The rest of the fields are optional.

   note

   The characters ':', '[', ']', '|', and '*' are not allowed in the username.

5. Click Create.

6. Switch to the Credentials tab and click Set password.

7. Use the Password and Password confirmation fields to set and confirm a new password.

8. Toggle the Temporary switch off and click Save.

9. Confirm your action by clicking Save password.

Repeat for as many users you want to add to the system.

Map user roles

1. Make sure that the asm realm is selected.
2. In the menu, under the Manage section, click Users.
3. Use the search field to find the user you wish to assign roles to.
4. Switch to the Role Mapping tab and click Assign role.
5. From the list, select the roles you wish to assign to the user:
   • asm-admins
   • asm-users
   • domain-auditor
6. Click Assign.

The specified roles are assigned to the selected user.

note

All three roles listed above must be assigned in order for the administrator to have access to projects and the administration view. Respectively, for ASM users, it is recommended to have assigned the asm-users and domain-auditor roles.

info

Read more about Policy Designer users and the required role here.

Delete a user in Keycloak

1. Make sure that the asm realm is selected.
2. In the menu, under the Manage section, click Users.
3. Search for the user you wish to delete or go through the list.
4. Click the three dots in the far right side of the user row and select Delete.
5. Confirm your action by clicking Delete.
6. Go to ASM and remove all of the user's project assignments and delete them from the list of users.

Configure Keycloak for Policy Designer

Similar to ASM, Policy Designer uses Keycloak for authentication and access management services. In order for this interaction to take place, you first need to configure Keycloak accordingly.

Integrate an Identity Provider (IdP)

1. Log in to the Keycloak Administration Console and go to the asm realm.

2. In the menu, under the Configure section, click Identity Providers.

3. Choose the same IdP that was set during Policy Designer's configuration.

   The configuration page for the IdP you selected displays.

4. Copy the Redirect URI generated by Keycloak and use it as the redirect (callback) URL required by the IdP, as described in the Keycloak documentationOpens in a new tab.

5. Enter the Client ID and Client Secret provided by the IdP.

   note

   For Bitbucket, the fields are named Consumer Key and Consumer Secret respectively.

6. Click Add.

   The Identity Provider is now configured.

Verify the Policy Designer client configuration

The Policy Designer client comes pre-configured, but occasionally the configuration might be incorrect. Follow the steps below to verify the domain used in the Policy Designer client configuration.

1. In the menu, under the Manage section, click Clients.

2. Find and click the pd Client ID on the table.

3. Check the values of the following fields and update the domain with your own, if necessary:

   • Root URL

     For example, https://<your_domain>/pd

   • Valid Redirect URIs

     For example, https://<your_domain>/pd/*

   • Web Origins

     For example, https://<your_domain>

   • Admin URL

     For example, https://<your_domain>/pd

4. If any updates were made, click Save.

   The Policy Designer client is now configured.

Configure Keycloak for ADS

To enforce authorization and project permissions, a mapper must be configured in Keycloak to map project permissions to claims when ADS is accessing a domain in the domain manager of ASM.

Most of these settings are created automatically during installation. However, a few configuration steps are necessary.

note

The following information assumes the system administrator has access to the Keycloak administration console. See Log in to Keycloak for the first time for first-time login instructions.

Regenerate a client secret

1. Log in to the Keycloak administration console and go to the asm realm.
2. In the menu, under the Manage section, click Clients.
3. Find and click the ads Client ID on the table.
4. Switch to the Credentials tab.
5. Click Regenerate next to the Client secret field.

Copy the value of the Secret field to use it in the configuration of ADS. See ADS docs: Authentication using an authorization serverOpens in a new tab for more information.

Update the mapper for the namespaces claim

1. In the menu, under the Manage section, click Clients.

2. Find and click the ads Client ID on the table.

3. Switch to the Client scopes tab and click the ads-dedicated client scope.

4. Click the Namespaces mapper on the table.

5. In the Claim value field, list the namespaces that the client should have access to.

   tip

   In ASM, namespaces are equivalent to projects.

   Important

   The value should be a JSON Array of strings with the following format: ["namespace", "namespace2", "namespace3/etc"].

6. Click Save to save the mapper.

This concludes the configuration of the Keycloak client for ADS.

What's next?

Assign users to projects and adjust their permissions as described in the Users and projects topic.