First-Run Configuration of SENSE Keycloak

This page covers the additional configuration required on the SENSE Keycloak realm after its first deployment.

Prerequisites

• The SENSE-configured Keycloak server is running.
• You have realm-administrator access to the imported StackV realm.
• You know the orchestrator host and HTTPS port used by the SENSE Portal.

Keycloak is currently the only supported authentication platform for the SENSE Orchestrator; in the future we plan on supporting external OIDC providers beyond our own Keycloak deployments.

Create Keycloak Server Admin

The SENSE Keycloak server starts by default with a server administrator named tempadmin. This user is, as stated, a temporary user and should be replaced with a more permanent and secure admin user. Make sure you are in the base Keycloak realm, and not the SENSE/StackV one.

1. Select Users, then Add User.
2. Fill out the basic user information, and then click Create.
3. The page should redirect to the user editing screen. Select Credentials and set the password or keys you wish to secure the user.
4. Select Role Mapping, Assign Roles → Realm Roles, and assign the admin role.
5. Logout and log back in with the new user and ensure you have the same admin access. If successful, you can then delete the temporary admin user.

Bootstrap a SENSE System Admin

Next, we will walk through how to create a SENSE user. Move to the StackV realm, and follow a similar process as above:

1. Select Users, and create a new user following the same steps as above, filling out the basic user information and assigning any credentials.
2. Select Role Mapping, Assign Roles → Realm Roles. You will see a list of the SENSE system roles, with the user classes at the top. For this user select the _CLASS_SYSTEM_ADMIN role and assign it.
3. Save the user.

Configure the Portal Client

1. In the Keycloak Console, select the StackV realm.

2. Select Clients, then Portal.

3. Under Access Settings, you need to add a redirect URI for your SENSE Portal with the following pattern:

   https://<orchestrator-host>:<https-port>/*

4. Save the client settings.

The trailing path wildcard shown above is intentional. Never use a whole-host wildcard, a standalone *, or a full wildcard.

Configure the StackV Client

The SENSE Orchestrator has features that proxy the Keycloak Admin REST API for management of groups, users, and roles. These features leverage the StackV client’s service account, which requires specific realm management roles. This makes the StackV client a sensitive element, and so you should not share the StackV client secret with others.

There are two levels of configuration depending on how secure you wish to make the client.

• view-users plus view-realm: Allows the orchestrator read-only user and realm access; this means system admins will need to use the Keycloak admin portal directly to manage user roles and groups.
• manage-users plus manage-realm: Allows the orchestrator full management capabilities; this means the orchestrator can modify and update user roles and groups.

Verify Access

• After setting up the redirects and client configurations, configure the orchestrator with the new client credentials.
• Once it is started, verify that the orchestrator is free of errors.
• Visit the SENSE Portal and login with your created SENSE user.