Configuring KeyCloak

Single sign-on service in Salt.Box is provided by KeyCloak identity and access management sowtware.
KeyCloak is a free software released under the Apache License 2.0 license.

Signing in

Log in to the web interface of the identity and access management subsystem at:
https://<address_of_Salt.Box_server>/auth/keycloak/
If Salt.Box is deployed in Docker, use the password for the admin account saved in the file
/secrets/keycloak-admin-password located in the project folder Fig. 1.

Figure 1. KeyCloak login dialog

Creating a realm

The admin account belongs to the default Keycloak realm named Master.
For security reasons, it is not recommended to create Salt.Box users in this realm.
Open the list of realms Fig. 2 [1] and click the create_realm_btn button to create a new realm.
Specify a realm name, for example, salt.box, as in Fig. 3, and click the Create button.
The new realm will be created.

Figure 2. Default (Master) realm page


Figure 3. ialog box for creating a new realm

Creating a client

1. Select the Clients menu item of the KeyCloak main menu Fig. 4.
   The Keycloak client is the salt_box_core web application, which is part of Salt.Box.
   Register this application in KeyCloak by clicking the Create Client button Fig. 4 [1] to open the client creation dialog.

   Figure 4. Clients page

2. On the General settings tab Fig. 5, set the parameters as follows:

   Key	Value	Comment
   Client type	OpenID Connect
   Client ID	salt_box_core	required
   Name	client_salt_box_core	any name

   then click Next.

   Figure 5. Creating a client: General settings tab

3. Check these boxes on the Capability config tab Fig. 6:

   Key	Value
   Standard flow	✓
   Direct access grants	✓

   then click Next.

   Figure 6. Creating a client: Capability config tab

4. Do not change parameters on the Login Settings tab Fig. 7, then click Save.
   A new KeyCloak client will be created.

   Figure 7. Creating a client: Login settings tab

Creating a client role

Salt.Box grants permissions of managing collections to users with the collections_admin role.
Create this role for salt_box_core client in salt.box realm.
Follow the steps below.

1. On the Clients page, open the newly created client salt_box_core and go to the Roles tab.
   Click Create role Fig. 8.

   Figure 8. Launching the Salt.Box client installation

2. Enter the role parameters as follows in the role creation dialog Fig. 9:

   Key	Value	Comment
   Role name	collections_admin	required
   Description		any description string

   then click Save.

   Figure 9. Create role dialog box

Just created role can then be assigned to any user Salt.Box: see Assigning a role to a user.
You can also ask the software developer about the names and purposes of other built-in Salt.Box roles and the notation rules for accessing Salt.Box resources.

Creating a user

1. Enter the new user details and create it:

   1. Select the Users menu item of the KeyCloak main menu Fig. 10.
      Click Add user button above the Users table Fig. 10 [1].

      Figure 10. User account management page

   2. Enter user's data in the Create user dialog Fig. 11:

      Key	Value	Comment
      Username	user	required
      Email
      First name
      Last name

      Figure 11. Entering user's data

   3. Specify, if necessary, any additional actions required with the user account, such as a mandatory password change upon the user's first login Fig. 12.
      The Update Password tile will appear in the user creation window Fig. 11 [1].

      Figure 12. Adding required user actions

   4. Click Create Fig. 11.

      A new user will be created, and the User details window will be displayed Fig. 13.

2. Set a password for the user you just created.

   1. On the Users page, open the newly created user account and go to the Credentials tab.
      Click Set password Fig. 13.

      Figure 13. User credentials tab

   2. Set the user password in the dialog box Fig. 14.

      Figure 14. Setting a password for a user

Assigning a role to a user

Now assign the previously created collections_admin role (see Creating a client role) to user account to grant it permissions of managing collections.

1. On the Users page, open the newly created user account and go to the Role mapping tab.
   Click Assign role Fig. 15.

   Figure 15. Role mapping tab

2. Enter collections_admin in search field, click arrow-right button Fig. 16 [1].

   Figure 16. Role mapping tab

3. Check the box next to the collections_admin role entry associated with the salt_box_core client Fig. 16 [2].

4. Click Assign Fig. 16 [3].
   The collections_admin role will be assigned to the user account.
   user will now be able to see the root collection objects.

More information

For more information about configuring KeyCloak please visit:
KeyCloak Documentation