You are viewing the documentation for Blueriq 16. Documentation for other versions is available in our documentation directory.

This guide describes how to migrate from the custom security mode to one of the OIDC security modes.

When using the Custom security mode, it is possible to create users and groups in the Studio via User Management. These users and groups are saved in XML files on the file system. The location of these files is configured in Studio service configuration (Studio\Services\StudioService.exe.config).

This guide describes how to migrate these users and groups from Studio to Keycloak so that it is possible to switch to one of the OIDC security modes.

Note that in the XML files Blueriq groups are called "roles", therefore in this guide, because it is dealing only with the XML, groups will be referred to as (Blueriq) roles.

Before continuing with this guide, it is recommended to read the Keycloak configuration page (and the Managing Users & Groups & Roles section in particular) in order to familiarize yourself with Keycloak.

Step 1: Migrate Roles

This step can be skipped when using a custom authorization mode (custom, NTLM custom or OIDC custom). When using such a mode, the roles are linked to users in UserAccess.xml. This file specifies which roles each user has (if any). In this case it is not necessary to create any roles in Keycloak.

When using OIDC without custom authorization, the roles a user has must be defined in Keycloak. When the user logs in, these external roles or groups are mapped to Blueriq roles, giving the user the permissions associated with these roles. This mapping is defined in the RoleMappings.xml, below is an example of a role mapping:

<RoleMappings>
  <RoleMapping>
    <Group>studio-admin</Group>
	<UserRole>Administrator</UserRole>
  </RoleMapping>
</RoleMappings>

This example will map the Keycloak role 'studio-admin' to the Blueriq role 'Administrator'. Each RoleMapping element must contain a single and unique UserRole element, but may contain multiple Group elements.

By default the Blueriq roles are saved in the folder Studio\Configuration\Security\UserRoles, where each role is saved in its own XML file. These files also contain which permissions are granted to a role. Under any security mode, users can only be granted permissions via Blueriq roles. The permissions of a role do not need to be migrated to Keycloak, these remain defined in the Studio configuration.

To migrate, for each Blueriq role:

  • Create a role in Keycloak with the same name as the Blueriq role
  • Create a group in Keycloak with the same name as the Blueriq role
  • Open the newly created group, and in the Role Mappings tab assign the role created in the previous step to the group.
  • Add a RoleMapping to the RoleMappings.xml file which maps the Keycloak group to the Blueriq role

Do not delete the Blueriq roles from the file system, as these contain the permissions granted by the roles.

Step 2: Migrate Users

By default the users are saved in the file Studio\Configuration\Security\Users\Users.xml, which stores each user and its password in encrypted form.

Which Blueriq roles a user has is defined in UserAccess.xml

For each user:

  • Create a user in Keycloak
    • Enter the username
    • Add the groups which are assigned to the user in UserAccess.xml 
    • Set the Required User Action to "Update Password"
  • Save the user
  • On the Credentials tab, set a temporary password
  • Let the user know they can log into Keycloak with the temporary password and set a new password (see below)

Once the migration is successful there is no longer any need for the file Studio\Configuration\Security\Users\Users.xml and it could be deleted.

How a user can set the first password 

Step 3: Update Configuration

  • Update Studio\Services\StudioService.exe.config and switch to the OIDC security mode
    • Disable the custom security configuration element by setting the enabled attribute to false

    • Enable the oidc or oidccustom configuration element depending on your preference by setting the enabled attribute to true

  • Update the IIS proxy to use the Keycloak token endpoint:
    • Open IIS manager
    • Expand the Blueriq website
    • Select the Identity folder
    • Select the URL Rewrite feature
    • Disable the rule Identity_Studio
    • Enable the rule Identity_Keycloak
  • Restart the Studio server in Windows Services

Step 4: Verify

  • Review the Studio log, to make sure it is using the correct configuration (mode, authority, role mappings), for example:

    ... | Authentication
... |   Mode:                 Oidc
... |   Authority:            http://localhost:16098/Keycloak/realms/BlueriqStudio15
... |   Client:               studio-server
... |   Role mappings:        ../Configuration/Security/RoleMappings
... |     Administrator       studio-admin
  • Verify that users can login and have the correct permissions

Note that logging into the Studio is not possible with a temporary password.

Step 5: Clean Up

If it all works, the Blueriq users can be deleted, but the user profiles may remain.

When using OIDC (and not OIDC custom) UserAccess.xml is also no longer used.

  • No labels

Didn't find the answer you were looking for? Try the advanced search!