Authentication Server configuration

The following is a summary of the steps required to configure Authentication Server:

  1. Create a service account in Hub and grant it permission to the Authentication Server API to issue authentication tokens.
  2. Configure your Blue Prism environment to use Authentication Server.
  3. Configure Blue Prism users to authenticate via Authentication Server.
  4. Enable Authentication Server in your Blue Prism environment.
  5. Configure the messaging function via the Blue Prism application server.

Please ensure you have taken a full and verifiable backup of your Blue Prism database before configuring and enabling Authentication Server for your environment. For more details, see Back up and restore the full system.

Create a service account in Hub

Service accounts provide the ability for applications to obtain access tokens and use them to make authenticated requests to an API. Blue Prism uses a service account to make authenticated requests to the Authentication Server API, and third-party applications can use service accounts to make authenticated requests to the Blue Prism API.

A service account that is used by Blue Prism to communicate with Authentication Server needs to be created and will be used to map users between the Blue Prism environment and Authentication Server.

  1. Log into Blue Prism Hub as an administrator.

  2. Click your profile icon to open the Settings screen, and under User Management click Service accounts.
  3. On the Service Accounts screen, click Add account.

  4. Enter an ID for the client application and a name for the client in the Authentication Server database.

  5. Under Permissions, select Authentication Server API.

  6. Click Create service account.

    The Add a service account screen displays with a generated secret.

    This is used to make authenticated requests to the Authentication Server API and to configure the Authentication Server credential required to enable Authentication Server in the Blue Prism interactive client.

    Service account creation confirmation

  7. Click the Copy to Clipboard icon to copy the generated secret to your clipboard, so you can copy it on the Blue Prism Server Configuration Details screen later on.

For more details on service accounts, see the Hub administrator guide.

Configure Blue Prism to use Authentication Server

The section below describes how to use a Blue Prism interactive client to configure your Blue Prism environment to use Authentication Server by:

  • creating a Blue Prism credential that will be used by Blue Prism to connect to Authentication Server to allow users to be mapped across the two databases. This credential will contain the client ID and secret details of the service account created in Hub.
  • adding the Authentication Server credential and the Authentication Server URL on the System > Security - Sign-on Settings screen.

To carry out this configuration, you need to be granted Hub administrator and Blue Prism interactive client system administrator rights.

Create OAuth 2.0 Client Credential

  1. Log into the Blue Prism interactive client as an administrator.

  2. In the Blue Prism interactive client, navigate to System > Security - Credentials.

  3. In the right-hand side menu, click New to create a new credential.

  4. In the Application Credentials tab, enter a name and a description for the credential, and in the Type drop-down, select OAuth 2.0 (Client Credentials).

  5. In the Client ID field, enter the client ID used for the service account you created in Hub.

  6. In the Client Secret field, paste the secret generated in Hub from your clipboard.

    Create new credential

  7. Click OK to save.

No access rights should be granted to this credential as access is not required by process automations.

Configure sign-on settings

The Enable Authentication Server option should only be selected once Blue Prism users have been configured to authenticate via Authentication Server. Once Authentication Server has been enabled, all direct user access for Blue Prism will be directed via Authentication Server and if it has not been configured correctly, users will not be able to log in. Please ensure a Blue Prism native administrator user still exists in the system who can log into Blue Prism via a direct database connection once Authentication Server has been enabled.

  1. Navigate to System > Security - Sign-on Settings.

  2. In the Authentication Server URL field, enter https:// followed by the host name configured during the Authentication Server installation.

    The Authentication Server URL can be found in the Internet Information Services (IIS) Manager under Sites > Blue Prism – Authentication Server > Site Bindings > Host Name. This is also the URL you use to log into Blue Prism Hub post installation.

  3. In the Authentication Server credential drop-down, select the credential created on the System > Security - Credentials screen.

    Sign-on settings

  4. Ensure that the Enable Authentication Server option is unselected.
  5. Click Apply.

Configure Blue Prism users to authenticate via Authentication Server

Existing Blue Prism native user accounts must be synchronized with the Authentication Server database so that they can continue to log in.To achieve this, a mapping tool must be used to synchronize the existing native users in your Blue Prism and Authentication Server databases with the following scenarios:

  • Create native user accounts in Hub for existing Blue Prism native users who do not have a Hub user account yet so Blue Prism native users can use Authentication Server to authenticate in the Blue Prism interactive client.

  • Create Blue Prism native user accounts in Blue Prism for users who already exist in the Authentication Server database but not in the Blue Prism database to allow Hub users to access the Blue Prism environment.

  • Link accounts for native users who already exist in both systems to ensure these are linked together and can access both databases.

The Authentication Server – Map users permission is required to map users using the mapping tool.

Before starting the mapping, please ensure that a Blue Prism native administrator user exists in the system, and that this user is manually removed from the mapping file before carrying out the mapping process outlined below. This is to ensure that in the event of any issues with the Authentication Server or system configuration, there is always an administrator user available who can log in via a direct database connection.

Create mapping file

  1. Create a CSV file and add the following headings: BluePrismUsername, AuthenticationServerUserID, FirstName, LastName, and Email. A Blue Prism username or an Authentication Server ID are required as a minimum.

    The column order must be preserved as shown in the example below, but the column headings can be customized as required.

  2. In the CSV file, add the available user details from the Blue Prism and/or Authentication Server databases, depending on the applicable scenario:

    • If you want to create accounts in the Authentication Server database for existing Blue Prism native users who are not in the Authentication Server database yet – add their Blue Prism username to the CSV file, along with a First Name, Last Name and Email address.

      The First Name, Last Name, and Email Address fields do not exist in Blue Prism, so they must be added to create the users in Authentication Server.

      You should delete any users from the file who should not log in via Authentication Server. At least one native administrator user should be removed from the file so they can still log in via a direct database connection. If you are using native authentication to authenticate runtime resources, AutomateC commands, or web service requests, you should also remove from the file any native user accounts required to authenticate these.

    • If you want to create Blue Prism native accounts in the Blue Prism database for users who already exist in the Authentication Server database but not in the Blue Prism database – add their Authentication Server ID from the PublicId field in the Users table in the Authentication Server database.

    • If you want to link accounts for users who already exist in both databases – add their Blue Prism username and their Authentication Server ID. The Authentication Server ID can be found in the PublicId field in the Users table in the Authentication Server database. To access this, open SQL Management Studio and navigate to the user list in AuthenticationServerDB - Users or run the following query on the Authentication Server database:

      Copy
      select username, publicid from Users

    CSV file example:

    CSV file example

    In Blue Prism 7.0, the Blue Prism username can only contain a sequence of letters, digits, periods, hyphens, or underscores, and without spaces when it is mapped to the Authentication Server database, otherwise the mapping will fail. Please remove any other characters before attempting the user mapping.

  3. Save the CSV file.

If there are any instances where an Authentication Server username already exists in Blue Prism, then when the mapping takes place, a random 4-digit number is appended to the new username to ensure it is unique and to differentiate between the users in audit logs.

Use AutomateC to process the mapping file

  1. Open Command Prompt as an administrator and navigate to the Blue Prism installation directory containing AutomateC.exe (for example C:\Program Files\Blue Prism Limited\Blue Prism Automate).
  2. Run the following command:

    Copy
    automatec /mapauthenticationserverusers <input CSV> <output CSV for errors> /user <admin username> <admin password> /dbconname <Blue Prism Server connection name>

    Where:

    • <input CSV> – The path to your saved CSV file.
    • <output CSV for errors> – The path for a file automatically created if there are errors in the mapping process.
    • <admin username> and <admin password> – The credentials for a native admin user in Blue Prism.
    • <Blue Prism server connection name> – The name of your Blue Prism server connection as set in the Blue Prism Server settings.

    For example:

    AutomateC mapping command

    Ensure the machine you run the command on is able to access the Authentication Server website. For more details, see Troubleshooting Authentication Server.

Verify users have been mapped correctly

  1. In the Blue Prism interactive client, navigate to System > Security - Users and check the following:

    • The Authentication Server account type displays for native users mapped from the Authentication Server database.
    • The Authentication Server service account account type displays for service accounts mapped from the Authentication Server database.

    Security - Users screen

  2. Assign the appropriate roles and permissions to all users mapped from Hub, as described in Manage roles.
  3. In Hub, navigate to Settings > Users and refresh the users list.

    Users mapped from Blue Prism now display in the list.

You can only perform the mapping once. Once users have been mapped, they cannot be mapped again. Once Authentication Server has been enabled, new users will be created in Hub and synchronized in the Blue Prism interactive client via the messaging server.

Users created via the mapping tool will be sent an email to set their password manually before logging in for the first time. They will not be able to access Blue Prism until this step has been taken. Users will only receive this email if their email settings have been configured in Hub. For more details, see the Hub administrator guide.

Enable Authentication Server in your Blue Prism environment

  1. In the Blue Prism interactive client, navigate to System > Security - Sign-on Settings.

  2. Select Enable Authentication Server and click Apply.

    Enable Authentication Server

  3. Sign out of the Blue Prism interactive client.

    The login screen now only displays a Sign in using Authentication Server option.

    Sign into Blue Prism using Authentication Server

  4. Click Sign in using Authentication Server.

    You will be directed to the Authentication Server login page.

  5. Enter your username and password and click Log in.

    An access token is issued from the Authentication Server in the background which will then be used to automatically log you into the Blue Prism interactive client.

    The date and time you last signed in now displays on the System > Security - Users screen when right-clicking your username.

    Last signed in date and time for a user

Once Authentication Server has been enabled, native accounts and mapped Active Directory accounts can be added, edited, or deleted locally in Blue Prism, however they can no longer be used to log into the interactive client. These accounts can only be used to authenticate runtime resources, AutomateC commands, and when calling web services exposed on runtime resources.

Configure RabbitMQ messaging via Blue Prism server

For new users created in Hub to be able to sign into the Blue Prism environment via Authentication Server, the Blue Prism application server must be configured to handle user events that are published to a message queue by Authentication Server.

This is configured in the Authentication Server Integration tab on the Blue Prism Server Configuration Details screen.

  1. Launch the Blue Prism application server (BPServer.exe from C:\Program Files\Blue Prism Limited\Blue Prism Automate).
  2. To open the server configuration, select the relevant environment from the Current configuration drop-down and click Edit.
  3. In the Authentication Server Integration tab:

    1. Enter the broker settings as configured in the Blue Prism Hub installation:

      • Address – RabbitMQ address in format rabbitmq://<host>:<port>/
      • Username – RabbitMQ username
      • Password – RabbitMQ password
      • Environment Identifier – Used to distinguish between different configured Blue Prism environments if applicable. This value can only contain a sequence of the following characters: letters, digits, hyphens, underscores, periods, and colons.

        Authentication Server Integration tab

    2. Click Save to apply the settings.

  4. Return to the Server configuration screen and click Start to start the BPServer.

    To confirm that the message bus has been configured correctly, you should see the following lines:

    [date stamp]: Starting message bus

    [date stamp]: Message bus started

    If the Blue Prism server is up and running, any users or service accounts created, edited, or deleted in Hub will also be updated in Blue Prism. Should the Blue Prism server go offline or come online later, the synchronization will complete once the connection has been restored.

  5. To verify that the message queue has been created, launch the RabbitMQ URL in a browser as configured in the Blue Prism Hub installation, for example, rabbitmq://localhost:15672/.

  6. In the Queues tab, locate the queue just created via the Authentication Server Integration settings above, for example blue-prism-app-server.user-synchronization.fresh-install.