Table of contents

Introduction

The Studio can be configured to authenticate using OpenID Connect (with Keycloak), NTLM or Kerberos such that users may login using credentials that are managed externally.

Authorization can be achieved either by mapping roles/groups provided by the external provider to Studio roles, or by explicitly assigning users to Studio groups from within the Studio.

You must choose one of these authorization options however, they can not be used concurrently.

OpenID Connect

Studio Server

OIDC authentication and authorization

With the oidc security mode, both authentication and authorization are managed in Keycloak.

First, go to [Blueriq Installation directory]\Studio\Services\StudioService.exe.config and search for <security>. Disable any active security providers by setting enabled attribute to false and enable the oidc element:

<oidc enabled="true" authority="http://localhost:15098/Keycloak/realms/BlueriqStudio15" clientid="studio-server" clientsecret="" rolespath="realm_access.roles">
  <rolemappingdao class="Aquima.Studio.Server.UserAccess.Xml.XmlRoleMappingDao, UserAccess">
    <parameters>
      <parameter value="../Configuration/Security/RoleMappings" />
    </parameters>
  </rolemappingdao>
</oidc>

The authority and client-secret have been configured during installation. To check the validity of the authority url, open [authorityUrl]/.well-known/openid-configuration in your browser, the result should be a JSON response.

To map the roles of an OIDC user to Blueriq roles, see the Role Mappings section.

OIDC authentication and custom authorization

With the oidccustom security mode, only authentication is managed in Keycloak. Authorization is managed in the Studio.

First, go to [Blueriq Installation directory]\Studio\Services\StudioService.exe.config and search for <security>. Disable any active security providers by setting enabled attribute to false and enable the oidccustom element:

<oidccustom enabled="true" authority="http://localhost:15098/Keycloak/realms/BlueriqStudio15" clientid="studio-server" clientsecret="">
  <useraccesdao class="Aquima.Studio.Server.UserAccess.Xml.XmlUserAccessDao, UserAccess">
    <parameters>
      <parameter value="../Configuration/Security/UserAccess" />
    </parameters>
  </useraccesdao>
</oidccustom>

See the User Access Mapping section for more information on how to assign roles to users when using custom authorization.

IIS Configuration

When switching from a non-oidc security mode to one of the two oidc security modes, there is also a proxy configuration that needs to be changed.

In IIS expand the Server > Sites > Blueriq# > Identity item in the left sidebar, and open the URL Rewrite feature:

Disable the rule Identity_Studio, and enable the rule Identity_Keycloak:

User Management

When using OIDC, Studio will connect to a Keycloak server provided with the Blueriq installation. Users may be managed via the admin console of the Keycloak server. This Keycloak server can also be configured to connect to an Active Directory with NTLM or Kerberos.

See the Keycloak configuration guide for more information.

Management Service

When using an OIDC security mode, requests to the management service should use Basic authentication.

Custom

When using the custom security mode, both the users and groups can be managed in the Studio via User Management.

With the default installation, you can login with the default credentials:

• Username: admin

• Password: welcome

NTLM/Kerberos

Studio Server

NTLM/Kerberos authentication and authorization

With these security modes, both authentication and authorization is managed using Active Directory. First, go to [Blueriq Installation directory]\Studio\Services\StudioService.exe.config and search for <security>. Disable any active security providers by setting enabled attribute to false and enable the ntlm element:

<ntlm enabled="true">
  <rolemappingdao class="Aquima.Studio.Server.UserAccess.Xml.XmlRoleMappingDao, UserAccess">
    <parameters>
      <parameter value="../Configuration/Security/RoleMappings"/>
    </parameters>
  </rolemappingdao>
</ntlm>

Alternatively for Kerberos, add the following snippet inside <security> :

<kerberos enabled="true">
  <rolemappingdao class="Aquima.Studio.Server.UserAccess.Xml.XmlRoleMappingDao, UserAccess">
    <parameters>
      <parameter value="../Configuration/Security/RoleMappings"/>
    </parameters>
  </rolemappingdao>
</kerberos>

To map the group of AD user to a Blueriq role, see the Role Mappings sections.

NTLM/Kerberos authentication and custom authorization

With this security mode, only authentication is managed using Active Directory; authorization has to be configured manually per Active Directory user that wants to login to Blueriq Studio. First, go to [Blueriq Installation directory]\Studio\Services\StudioService.exe.config and search for <security>. Disable any active security providers by setting enabled attribute to false and enable the ntlmcustom element:

<ntlmcustom enabled="true">
  <useraccesdao class="Aquima.Studio.Server.UserAccess.Xml.XmlUserAccessDao, UserAccess">
    <parameters>
      <parameter value="../Configuration/Security/UserAccess"/>
    </parameters>
  </useraccesdao>
</ntlmcustom>

Alternatively for Kerberos, add the following snippet inside <security> :

<kerberoscustom enabled="true">
  <useraccesdao class="Aquima.Studio.Server.UserAccess.Xml.XmlUserAccessDao, UserAccess">
    <parameters>
      <parameter value="../Configuration/Security/UserAccess"/>
    </parameters>
  </useraccesdao>
</kerberoscustom>

See the  User Access Mapping section for more information on how to assign roles to users when using custom authorization.

Studio Web Client

The web client will deduce the StudioService identity from the connection URL as "HTTP/hostname". No additional configuration is required.

Administration Page

The Studio Administration Page uses the Management Service.

The domain, user and password attributes specify the identity of the client (the administration page).

The settings file for the Administration Page can be found on the following location: [BlueriqInstalationDirectory]\Studio\wwwroot\Administration\Web.config.

<managementservice>
    <connection url="http://studio-pc:15093/Services/ManagementService" user="domain\user" password="password"/>
</managementservice>

IIS Configuration

Depending on the version of Windows and IIS, it may be necessary to adjust the configuration of IIS before it's possible to login using NTLM. The Studio Server is responsible for authenticating a request with the Active Directory, so authentication should not be performed from within the IIS reverse proxy.

First, open Internet Information Services (IIS) Manager and expand the Server > Sites > Blueriq_# >Studio > Server item in the left sidebar, then open the Authentication panel:

Once opened, select Windows Authentication and then click Disable in the right sidebar:

Finally, open the server view in the left sidebar and then choose Restart to restart the IIS services. A restart is required to properly apply the authentication changes, as otherwise authentication may fail.

Credentials

To login when NTLM authentication is enabled, users have to include the domain name of the Active Directory as a prefix to their username, separated by a backward slash: <domainname>\<username>.

Studio projects in the Runtime Dashboard

To establish a connection from the Runtime dashboard to the Studio server, authentication needs to be configured here: [BlueriqInstalationDirectory]\Runtime\conf\application-development-tools.properties.

For NTLM authentication you'll need to configure an active directory user. We recommend to use an encrypted password.

Role Mappings

When using a security mode with authorization based on OpenID Connect or Active Directory, the group or role of a user has to be mapped to one of the Blueriq roles. This can be accomplished by using a custom role mapping configuration in [Blueriq Installation directory]\Studio\Configuration\Security\RoleMappings\RoleMappings.xml.

In the group section, you have to add the group name (or role name in Keycloak). For AD groups it should include the domain name: <domainName>\<groupName>

In the user role section, you have to add the Studio role.

Example:

BlueriqUserGroup from domain BlueriqDomain

<RoleMappings>
  <RoleMapping>
    <Group>BlueriqDomain\BlueriqUserGroup</Group>
    <UserRole>Administrator</UserRole>
  </RoleMapping>
</RoleMappings>

Note that each UserRole may only appear once in the RoleMappings.xml. To map multiple groups to a single Studio role, add multiple <Group> elements to the <RoleMapping>.

User Access Mapping

When using a security mode with custom authorization, where the Studio determines which roles a user has, you can either configure this in the Studio or via an XML file.

This section explains how to edit the XML file, for more information on how to manage users and roles from within the Studio, see User access and management.

To map users to Blueriq roles. go to [Blueriq Installation directory]\Studio\Configuration\Security\UserAccess\UserAccess.xml.

<?xml version="1.0"?>
  <Users>
    <User Name="Admin">
    <Role>Administrator</Role>
  </User>
</Users>

By default, this file contains a user Admin. When using an external authentication mode, this user will not exist and should be replaced by a user from the external provider. When using NTLM this should include the domain name, for example DOMAIN\adminuser.

When changing this file, the StudioService must be restarted via the Services panel in Windows.