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 the Blue Prism application server.
  4. Configure Blue Prism users to authenticate via Authentication Server.
  5. Enable the connection to the messaging server.
  6. Enable Authentication Server login in your Blue Prism environment.

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 and synchronize 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 required when configuring the client details within the Blue Prism application server, to allow this service account to make authenticated requests to the Authentication Server API.

    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:

The User login via 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. Log into the Blue Prism interactive client as an administrator.

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

  3. 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.

  4. Ensure that the User login via Authentication Server option is unselected.

  5. Click Apply.

Configure the Blue Prism application server

To add users from Authentication Server into Blue Prism and to synchronize the user data, the details of the service account created to make authenticated requests to the Authentication Server API must be configured on the Blue Prism application server. Additionally, the Blue Prism application server can be configured to handle user and service account events that are published to a message queue by Authentication Server, so updates to Authentication Server users and service accounts are applied to the mapped Blue Prism user or service accounts.

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.

    2. Enter the client details. These are used for user and service account synchronization and when making calls directly to the Authentication Server API, for example, when adding Authentication Server users to Blue Prism roles, as configured in Create a service account in Hub .

      • Client ID – The client ID of the service account used by Blue Prism to communicate with Authentication Server.
      • Client Secret – The client secret key generated by the service account used by Blue Prism to communicate with Authentication Server.

      In Hub 4.7 and later, the client ID is case sensitive. You must ensure you enter the client ID in the same case as defined in the service account.

    3. Click Test connection to ensure the details entered are valid.

      Do not select Enable connection until you have completed the user mapping. You can save your changes and return to enable the connection once you have completed the user mapping.

    4. Click Save to apply the settings.

Configure Blue Prism users to authenticate via Authentication Server

New Blue Prism environments

If you are configuring a new Blue Prism environment to use Authentication Server, Authentication Server users must be created in Blue Prism Hub first (see the Hub administrator guide for more details) and then added to Blue Prism by assigning them to a Blue Prism role.

To add one or more Authentication Server users to a Blue Prism role:

  1. In the Blue Prism interactive client, navigate to System > Security - User Roles.
  2. Select a role from the list and edit the associated permissions if required.

  3. Click Manage role membership.

    The Role Membership screen displays.

  4. Click Add.

    The Add users dialog displays.

  5. Select the Authentication Server user(s) you want to add to the selected role, or search for them using the search box, and click OK.

    The added Authentication Server user(s) now display on the Role Membership dialog.

  6. Click OK to save your changes.

Authentication Server users configured to use Active Directory authentication in Hub can also be added to Blue Prism based on their Active Directory security group membership. For more details, see Add Active Directory users to Blue Prism based on their security group membership.

Existing Blue Prism environments

If you are updating a Blue Prism environment, 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.

  • 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.

The mapping tool cannot be used in the following scenarios:

  • To add Authentication Server users automatically to Blue Prism – Authentication Server users are only added to Blue Prism at the time when they are assigned to a Blue Prism role. For more details, see New Blue Prism environments.
  • To synchronize Blue Prism Active Directory users with Authentication Server – Once Active Directory authentication has been configured in Hub, a Blue Prism user signing in using Active Directory authentication via Authentication Server for the first time will have an account created automatically in Hub, and will be able to continue using Blue Prism with their existing roles. For details on how to manage Active Directory users in Hub, see the Hub administrator guide.

Add users via 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 accounts in the Authentication Server database for existing Blue Prism native users who do not have corresponding Hub user accounts yet
  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 to get a CSV template file containing a list of all the Blue Prism native users in the database who are available for mapping:

    Copy
    automatec /getblueprismtemplateforusermapping <pathtooutputfile> /user <adminuser> <adminpwd> 
  3. From Windows Explorer, open the output file and add the first name, last name, and email address for each Blue Prism user you want to add.

    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.

  4. 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 also authenticate runtime resources, AutomateC commands, or web service requests, you should also remove from the file any native user accounts required to authenticate these.

  5. Save the CSV file.

  6. Open Command Prompt as an administrator and navigate to the Blue Prism installation directory containing AutomateC.exe.

  7. Run the following command to complete the user mapping:

    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.

Map existing Blue Prism users to existing Authentication Server users
  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 to get a CSV template file containing a list of all users available for mapping in the Blue Prism database:

    Copy
    automatec /getblueprismtemplateforusermapping <pathtooutputfile> /user <adminuser> <adminpwd> 
  3. Run the following command to get a CSV template file containing a list of all users who are available for mapping in the Authentication Server database:

    Copy
    automatec /getauthenticationservertemplateforusermapping {outputpath} /dbconname <Blue Prism Server connection name>
  4. From Windows Explorer, open both output files, and for each Blue Prism user you wish to map, find the corresponding Authentication Server user and copy the Blue Prism username into the Authentication Server output file.

    A Blue Prism username and an Authentication Server User ID are required as a minimum. The additional First Name, Last Name, and Email Address fields required in the Authentication Server database should already be present for the Authentication Server users.

  5. Delete any users who should not be mapped from the Authentication Server output file. At least one native administrator user should be removed from the file so they can still log in via a direct database connection. You may also want to remove from the file any native user accounts which will be required to authenticate runtime resources, AutomateC commands, or web service requests.
  6. Save the Authentication Server output file.
  7. Open Command Prompt as an administrator and navigate to the Blue Prism installation directory containing AutomateC.exe.
  8. Run the following command to complete the user mapping:

    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.

Authentication Server users cannot be mapped to Blue Prism users that do not exist. If an administrator does not enter a Blue Prism username in the CSV file, but enters an Authentication Server User ID, an error message displays.

For example:

CSV file example

Verify that 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.

  2. 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.

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 the connection to the messaging server

  1. Launch the Blue Prism application server (BPServer.exe from C:\Program Files\Blue Prism Limited\Blue Prism Automate).
  2. On the Server configuration screen, click Stop to stop the BPServer.

  3. In the Authentication Server Integration tab on the Server Configuration Details screen, select Enable connection and click Save.
  4. Return to the Server configuration screen and click Start to start the BPServer.
  5. Check that the message bus is running. You should see the following lines:

    [date stamp]: Starting message bus

    [date stamp]: Message bus started

    If the Blue Prism server is succesfully running and the connection is enabled, any users edited or deleted in Hub, 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.

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

  7. 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.

Manual synchronization of user and service accounts

User and service account updates can be manually synchronized between the Blue Prism and Authentication Server databases outside of the RabbitMQ update schedule in the event of any service disruption by using the Synchronize users with Authentication Server option, available from the menu button on the Security - Users screen in the Blue Prism interactive client.

To use this option, the interactive client must be connected via a Blue Prism application server which has been configured with the client details of the service account used to make authenticated requests to the Authentication Server API.

When selected, the following updates will occur:

  • Any new Authentication Server service accounts will be added to the Blue Prism database.

    Only service accounts set with the Blue Prism API permission in Hub will display on the Security - Users screen once synchronized with Authentication Server.

    Authentication Server users are not added to the Blue Prism environment when using this option, they must be manually assigned to a Blue Prism role on the Role Membership screen, see New Blue Prism environments. This is to prevent large numbers of Authentication Server users who do need access to Blue Prism, for example, Interact users, from being added into the Blue Prism database.

  • Any user and service accounts that have been retired in the Authentication Server database will be retired in the Blue Prism database as well.
  • Any user and service accounts that have been unretired in the Authentication Server database will be unretired in the Blue Prism database as well.

If opting to only use manual synchronization and not enable a connection to the messaging server, when a user account has been deleted in Blue Prism but unretired in Hub, a manual synchronization will be required to reactivate the user account, before they can log into Blue Prism via Authentication Server.

Enable Authentication Server login in your Blue Prism environment

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

  2. Select User login via Authentication Server and click Apply.

  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

  6. Sign out of Blue Prism and restart the Blue Prism Application Server to ensure the changes are fully applied.

Once Authentication Server has been enabled, native 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.