Troubleshooting Authentication Server

The following sections provide guidance for specific issues that may be experienced while configuring Authentication Server.

Logging into Blue Prism after enabling Authentication Server

Where a Blue Prism deployment has been configured to require all user authentication to be routed via Authentication Server but where Authentication Server is not available,  please contact Blue Prism Support for guidance.

Once Authentication Server has been enabled, you must ensure that a Blue Prism native administrator user remains in the system. Please ensure you have taken a full and verifiable backup of your Blue Prism database before contacting Blue Prism Support.

Error message displays when attempting to sign in using Authentication Server

If the message Unexpected browser error. You will now be returned to the sign-in screen. displays when a user attempts to sign in using Authentication Server, the following should be checked:

  • Is the Authentication Server URL accessible from the user's device, and has the the correct Authentication Server URL been entered on the Security - Sign-on Settings screen?

    • Validate that the correct Authentication Server URL has been configured in Blue Prism under System > Security - Sign-on Settings. If no users can currently log in to view the URL on this page, you can view the URL by running the following query against your Blue Prism database:

      Copy
      SELECT authenticationserverurl FROM BPASysConfig

    • Validate that Authentication Server is running and reachable from the user’s machine by entering the URL for the Discovery document in a browser: <authentication server URL>/.well-known/openid-configuration

      If successful the page will load containing some JSON with details of the Authentication Server as shown below:

      If the page cannot be reached you may need to restart the site from the application pool in IIS. For more details, click here.

    • Validate that you can browse to the correct Authentication Server URL by opening IIS Manager (inetmgr.exe) and locating the Blue Prism - Authentication Server website. Right‑click the website and click Manage Website > Browse. The Authentication Server website will open in your default browser. For more details on troubleshooting Hub sites such as Authentication Server, click here.

  • Is there a network problem?

    • Check that the SSL certificate is valid. For more details, click here.

    • Check that a proxy is not preventing Blue Prism from connecting to Authentication Server.

      If you need to disable it, you can do so under Internet Properties > Local Area Network (LAN) Settings by deselecting the option Use a proxy server for your LAN. For more details on configuring proxy settings, click here.

Error message displays in the output CSV file when running the mapping function for the first time

The message An error occurred when creating the Authentication Server user record could display in the output CSV file when running the mapping function for the first time in the following scenarios:

  • If the service account you created in Hub for communication between Blue Prism and Authentication Server has not been granted the Authentication Server API permission.

  • If the client ID and client secret key of the service account have not been correctly added to a Blue Prism OAuth2.0 (Client Credential) and configured on the Security - Sign-on Settings page in Blue Prism.

    To verify this:

    1. Log into the Blue Prism interactive client and navigate to System > Security - Sign-on Settings, and check the name of the credential selected in the Authentication Server credential drop-down.

    2. Navigate to System > Security – Credentials, select the credential you have created for Authentication Server and click Edit.
    3. Check that the client ID entered matches the client ID from the service account in Hub.
  • When mapping users from Blue Prism to Authentication Server, if the user you are trying to map already exists in the Authentication Server database, the mapping function will check for the FirstName, LastName and Email details. If one of these already exists in Authentication Server, the user record will not be mapped.
  • If the machine you run the command on is not able to access the Authentication Server website.

Authentication Server users only have access to the Home and Digital Exchange tabs when they sign into the Blue Prism interactive client

Authentication Server manages users' access to Blue Prism and Hub, however, roles and permissions are managed locally in each application. Users that are mapped from Hub to Blue Prism will not have any roles and permissions assigned to them, and a Blue Prism system administrator will need to manually assign the roles and permission for each user after they have been mapped. For more details, see Manage Blue Prism user roles.

Authentication Server settings do not display in your Blue Prism environment

If your Blue Prism environment has been configured to use Authentication Server, the configuration settings should display under System > Security > Sign-on Settings. If they don't, a few reasons could be:

  • You haven't upgraded to Blue Prism 7.0, which is the first version in which Authentication Server is available.

  • Your Blue Prism environment is a single-authentication (Active Directory SSO) environment, which cannot be configured to use Authentication Server.

For more details, please refer to this Knowledge Base article.

The RabbitMQ message bus does not start when starting the Blue Prism application server

If the RabbitMQ message bus does not start when starting the Blue Prism application server (a warning will display in the server output window or the server logs), check the following:

  • Is RabbitMQ running?
    • Check that the RabbitMQ service is running by locating RabbitMQ in the list of services available on the operating system where RabbitMQ has been installed.
  • Are the RabbitMQ address, virtual host and port details correct? 
    • The format should be {protocol}://{host}:{port}/{virtual host}, for example, rabbitmq://<rabbitmqserver>:5672/.
  • Are the RabbitMQ username and password correct?
    • The guest user only works over a localhost connection. Ensure a new user has been created with the correct virtual host permissions.

The details above can be checked by accessing the RabbitMQ Management Portal from within a browser via https://<rabbitmqserver>:15672/ and logging in with the configured user's credentials.

Users created in Authentication Server do not appear in the Blue Prism interactive client

If users created in Authentication Server do not appear in the Blue Prism interactive client after you have configured the message broker settings and started BPServer, check the following:

  • Is RabbitMQ running?
    • Check that the RabbitMQ service is running by entering Services into your search bar and and ensuring RabbitMQ displays in the list.
  • Check the RabbitMQ Management Portal for the following:
    • Are there any messages on the user synchronization queue?
      • If yes, is BPServer running? BPServer is the only consumer of the user synchronization queue, therefore messages on the queue (indicated by a positive integer in the Ready column) mean that BPServer is not running or that the BPServer Authentication Server Integration settings are incorrect.

        • If that is the case, check that the Authentication Server Integration settings in BPServer match the correct queue. Using the example below, the environment identifier should be bp.

        • Ensure BPServer is started.

      • If there are no messages on the user synchronization queue currently, have there been any messages on the queue? This can be checked by inspecting the message rates for each queue, for example, a queue with activity will have a 0.00/s value, whereas a queue with no messages will be empty.

    • Have any messages been consumed on the user synchronization queue?

      • If visible in the RabbitMQ Management Portal, this indicates that the user synchronization function is working end to end and there has been an issue when processing the event.

    • If a user or service account has failed to be created or updated, there will be another queue that will be created which contains application errors (this is known as the error queue). The queue name will be identical, with an additional suffix of _error.

  • Errors (and any messages) can be inspected to diagnose problems within the application. To do this, first select the queue, and then select the Get Messages option. You can specify how many messages to get. As this is a queue, if we get 1 message then the message at the front of the queue is returned. The message at the front of the queue is the oldest message. Once selected, you can see the contents of the message. In the event of an error message, you can see details such as exception type, message type, and a more detailed stack trace.

  • Do your RabbitMQ username and password contain any of the following special characters ? #/:?@\"$’
    • If yes, please change your username or password in the RabbitMQ Management Portal as these characters are not accepted.
    • If these are the user credentials that were specified when installing Hub, then you will need to create a new RabbitMQ connection string and encrypt the value using the Blue Prism Data Protector Tool. Once encrypted, this new value will need to be added to the relevant appsettings files for Hub, and Authentication Server. For more details, see Blue Prism Data Protector Tool.

Using Authentication Server with an existing RabbitMQ instance that uses external certificate-based authentication

If you are using Authentication Server with an existing RabbitMQ instance that uses external certificate‑based authentication, credential (PLAIN) authentication will need to be enabled into their instance. More details are available here.

If you have never configured the RabbitMQ function via the Authentication Server Integration tab in the Blue Prism application server, the RabbitMQ Management UI would not have a queue created for that environment, meaning any changes made in Hub would not be queued. However, once that configuration has been set and verified it works successfully, any future updates made in Hub will be queued, whether the Blue Prism application server is running or not.