By default Keycloak is installed and configured so that it can be used by Encore and the Studio server using the OIDC protocol.

Keycloak admin credentials

During the installation of Blueriq using the installer, a Keycloak user named admin is created for which a password has been specified during the installation as well.

To change the admin password, take the following steps:

From the Blueriq start page, select User Management

Log in to the Keycloak Admin console using the user named admin and the password as created during the installation.

In the top right corner, select Manage account

Select "Signing in" from the Account Security card.

Select Update from the Basic Authentication section, and choose a new password.

Click "Back to Security Admin Console" from the top left to go back to the Admin console, you may need to sign in again with the new password.

Default configuration

The default configuration is created when installing Blueriq. This configuration is contained within a Keycloak realm which is used by Encore and the Studio server. This section contains an overview of what the default configuration includes.

Clients

Two clients are created in the default configuration.

• studio-server: Used by the Studio backend, this is a private client which has admin access to the Studio
• encore: Used by Encore, this is a public client which retrieves an access token on behalf of a user in order to communicate with the Studio backend

The secret for the studio-server client must also be provided to the Studio backend in [Installation_Folder]\Studio\Services\StudioService.exe.config in the oidc element. This is normally done during installation, but when generating a new secret in Keycloak this must be updated manually.

Adding new clients

It is possible to add new clients for example for (third-party) tools that use the Management Service, such as BMA or the publisher.

1. Log in to Keycloak, and select the correct BlueriqStudio realm
2. Select the "Client" section in the navigation menu on the left
3. Click the "Create client" button
4. Enter a Client ID and click "Next"
5. Switch Client authentication to On for non-public clients
6. Enable "Direct access grants" if you want to support the "password" grant type, this allows this client to request an access token on behalf of a Studio user
7. Enable "Service account roles" if you want to support the "client ceredentials" grant type, this allows this client to request an access token for itself
8. Click "Next"
9. Click "Save"
10. Open the newly created client
11. Select the "Client scopes" tab
12. Click the "Add client scope" button
13. Select the client scope "studio" and add it as a Default client scope

If at step 5 you have enabled the "Service account roles", you also need to assign a valid role to this client via the following steps:

1. Open the newly created client
2. Select the "Service accounts roles" tab
3. Click the "Assign role" button
4. Select which roles you want this client to have, and click "Assign"

To retrieve the client secret associated with the newly created client, do the following:

1. Open the newly created client
2. Select the "Credentials" tab
3. Copy or view the Client secret

Client Scopes

A client scope studio is included in the realm. When requesting an access token, this scope will activate mappers which add additional information to resulting access token. This information is required by the Studio backend in order to validate the token.

Groups & Roles

A group and role studio-admin are created by default during the Studio installation. The group studio-admin has the role studio-admin assigned to it, this role is mapped to the default Administrator role in the Studio server.

Users

The following user is created by default, as member of the studio-admin  group, and therefore has admin access to the Studio server.

• admin: the admin user of Encore

Restoring the default configuration

The default configuration can be restored using the Powershell scripts located at [Installation_Folder]\Studio\Keycloak\setup-keycloak-studio-realm.ps1

For example, you can run the script as follows from the Powershell command line, replacing *** with actual passwords

setup-keycloak-studio-realm.ps1 -KeycloakUrl http://localhost:150/Keycloak -KeycloakAdmin admin -KeycloakAdminSecret *** -RealmName "BlueriqStudio15" -StudioAdmin admin -StudioAdminSecret *** -AdminPageUser administrationpage -AdminPageSecret *** -RuntimeUser runtime -RuntimeSecret *** -StudioConfigPath "C:\Program Files\Blueriq15\Studio\Services\StudioService.exe.config" 

The values for KeycloakAdmin and KeycloakAdminSecret can be found in the file [Installation_Folder]\Keycloak\bin\kc-service.xml.

Values for other password can be chosen at will, but the configuration for applications that must sign in using those passwords, must also be updated.

When restoring the default configuration, the script will also update StudioService.exe.config to set the correct authority url for the newly created realm and the new client secret for the studio-server client.

User Federation: NTLM/LDAP

It is possible to link Keycloak to an Active Directory using User Federation. This will allow users to sign in using their AD credentials. To set this up:

1. Select User Federation from the navigation panel. From the Add provider drop-down, select ldap.
   
   
   
2. Select which vendor is used:
   
   
   
   
3. Enter the connection url, including the ldap:// prefix. The following command line command may assist in determining the correct url: nslookup -type=all _ldap._tcp.
   
   
   
4. Select which credentials Keycloak will use to query the AD, for example as CN=Keycloak,CN=Services,DC=company,DC=com.
   
5. Test authentication to ensure the configuration works.
6. As Edit Mode, choose READ_ONLY
   
7. Select where in the LDAP tree Keycloak can find the Studio users that should be able to log in, for example CN=MyStudioUsers,DC=company,DC=com.
8. Save your changes
9. Sync all users in the top right corner:
   

User Federation: Kerberos

It is possible to link Keycloak to an Active Directory with the Kerberos protocol using User Federation. This will allow users to sign in using their AD credentials. To set this up:

1. Select User Federation from the navigation panel and then select "Add Kerberos providers".
   
2. Choose a UI display name
3. Enter the Kerberos Realm
   
4. Enter the principal for the server 
   
5. Enter the location of the keytab file containing credentials of the given principal
   
6. Set Allow Password Authentication to On:
   
7. Set Edit Mode to READ_ONLY
   
8. In order to test it, a AD user can try to sign in to the Account console for the Studio realm at http://<domain:port>/Keycloak/realms/<realm>/account