Troubleshooting Authentication Server

Logging into Authentication Server using Active Directory authentication

If login failures or performance issues are encountered during the login process via Active Directory, system administrators can check if further Active Directory settings need to be added to the Authentication Server appsettings.json file. To edit the appsettings.json file:

1. Open Windows Explorer and navigate to the Authentication Server install location.

   To check the install location, open Internet Information Services (IIS) Manager, select the Authentication Server site and click Explore.

2. Back up the appsettings.json file.

3. Open the appsettings.json file in a text editor.
4. Locate the Ims section of the file.

5. If not already present, add an ActiveDirectory section.

   If the ActiveDirectory section is already present, you might see other settings in that section based on your Active Directory configuration, so the examples in the sections below are only illustrative.

6. Save the file if you have made any changes.

Authentication Server must be restarted after any changes have been made to the appsettings.json file.

To restart Authentication Server:

1. Open Internet Information Services (IIS) Manager.

2. In the list of connections, select Blue Prism - Authentication Server.

   This is the default site name – if you have used a custom site name, select the appropriate connection.

3. Click Restart from the Manage Website controls.

Check if the Active Directory timeout limit needs to be configured

When Authentication Server attempts to query a Domain Controller, by default it will wait five seconds for a response before triggering a System.TimeoutException error. However, this value can be configured if required in the following scenarios:

• If users are experiencing performance issues when logging in via Active Directory and the logs show several instances of System.TimeoutException: Timeout after 5 seconds, the value may need to be decreased. The range is between 1 and 60 seconds.
• If users are being prevented from logging in via Active Directory and the logs show several instances of System.TimeoutException: Timeout after 5 seconds, the value may need to be increased. The range is between 1 and 60 seconds.

To configure the Active Directory timeout limit:

1. In the ActiveDirectory section of the appsettings.json file, add a QueryTimeoutSeconds setting and a value depending on your scenario, see example below for a decreased value.

   Copy

   {
       "Ims" : {
           "ActiveDirectory": {
                   "QueryTimeoutSeconds": 3
           }
       }
   }

2. Save the file.
3. Restart Authentication Server.

Check if the Active Directory domains used during login need to be manually configured

To reduce the time taken for the Active Directory cache to be populated during user login, system administrators can manually configure trusted Active Directory domains that will be queried during the login process.If at least one Active Directory domain is manually configured, these settings will be used during the login process to query only the configured domain(s), rather than programmatically identifying which domains can be queried.

When a new domain is added to Active Directory, it must also be added to the configuration. Otherwise it will be ignored and users belonging to this domain will not be able to log in until the configuration has been updated.

Any Active Directory domains that meet one or more of the following criteria can be manually configured if using Authentication Server 4.6:

• Contain users that must be able to log in.
• Contain security groups that are assigned directly to Hub or Interact roles in Authentication Server.
• Contain parent security groups which include security groups that are directly assigned to Hub or Interact roles in Authentication Server.

If using Authentication Server 4.7, only Active Directory domains which meet the following criteria should be manually configured:

• Contain users that have an alternative User Principal Name (UPN) suffix that is different to the Domain Name System (DNS) name of the Active Directory domain. For example, corp.dir.company.com (DNS name) and company.com (alias suffix), where [email protected] is the UPN.

The manual configuration requires adding the Active Directory domain name, forest name, and security identifier in the Authentication Server appsettings.json file for each required domain. To do this:

1. In the ActiveDirectory section of the appsettings.json file, add a TrustedDomains section.

2. Add the required information for each domain, for example:

   • DomainName – The name of the Active Directory domain(s) that will be manually configured.

   • ForestName – The name of the forest in which the Active Directory domain resides.

   • Sid – The security identifier for the Active Directory domain.

   Copy

   {
     "Ims": {
       "ActiveDirectory": {
               "TrustedDomains": [
               {
                "DomainName": "domain.com",
                "ForestName": "my.domain.com",
                "Sid": "S-1-27-1-3452"
               },
              {
                "DomainName": "company.com",
                "ForestName": "my.company.com",
                "Sid": "S-2-23-1-3458"
              },
              {
                "DomainName": "enterprise.com",
                "ForestName": "enterprise.com",
                "Sid": "S-3-23-1-3459"
              }
           ]
       },

3. Save the file.
4. Restart Authentication Server.

Check if cache settings for stored Active Directory domains need to be configured

To further improve performance during the login process, the behavior of the cache that stores the discovered domains can be configured by setting a refresh interval and a maximum cache duration in the Authentication Server appsettings.json file.

• The refresh interval is the interval in minutes at which the cached data will be updated from Active Directory. The value can be set between 5 and 1440 minutes. The default value is 5.

• The maximum cache duration is the amount of time in minutes that the data will be held in the cache before it is invalidated. The value can be set between 5 and 1440 minutes. The default value is 30 if using Authentication Server 4.6. If using Authentication Server 4.7, the default value is 1440.

  These two settings must be configured as a pair, and the maximum cache duration should be set higher than the refresh interval. If one or both settings are not configured, the default values will be used.

The cache is populated in Authentication Server when:

• Starting or restarting the Authentication Server site.

• Enabling Active Directory authentication in Blue Prism Hub > Authentication settings.

  The cache is not populated in Authentication Server unless Active Directory authentication has been enabled.

To add the cache settings to the Authentication Server appsettings.json file:

1. In the ActiveDirectory section, add the MaxCacheDurationMinutes and CacheRefreshIntervalMinutes settings and their values, for example:

   Copy

   {
       "Ims" : {
           "ActiveDirectory": {
                   "MaxCacheDurationMinutes": 60,
                   "CacheRefreshIntervalMinutes": 10
           }

2. Save the file.
3. Restart Authentication Server.

Check if Domain Controller name mappings need to be configured

The following error message may display when searching for Active Directory users or security groups, and when adding or editing Active Directory domains: Invalid credentials. Please check your credentials. This could occur if the domain of interest is on a different network from the network on which Authentication Server is running.

If you are certain that you have provided the correct credentials when you created an Active Directory domain record, you can configure Domain Controller name mappings in the appsettings.json file so Active Directory queries for the domain specified in DomainName are directed to the endpoint defined in DomainControllerName.

To do this:

1. In the ActiveDirectory section of the appsettings.json file, add a DomainControllerNameMappings section.

2. Add the required information for each domain and Domain Controller, for example:

   • DomainName – The name of your Active Directory domain or the DNS name of the domain.

   • DomainControllerName – The DNS name of the domain or the FQDN of a Domain Controller in the domain.

   Copy

   {
     "Ims": {
       "ActiveDirectory": {
                       "DomainControllerNameMappings": [
                       { 
                           "DomainName": "company.com",
                           "DomainControllerName": "server-id.company.com"
                       },     
                       { 
                           "DomainName": "my.company.com",
                           "DomainControllerName": "server-id.my.company.com"
                       }
                   ],

3. Save the file.

4. Restart Authentication Server.

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.
• Do the client ID and client secret key match the values entered for the service account created in Hub?
• Have you clicked Test connection to check whether the connection is valid?

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.

Updates to users and service accounts in Authentication Server do not appear in the Blue Prism interactive client

If service accounts created in Authentication Server do not appear in Blue Prism, or deleted or restored users or service accounts are not updated in Blue Prism, 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.

  

  

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.

Embedded Authentication Server login page loads indefinitely

When logging into the Blue Prism interactive client using Authentication Server, the Authentication Server login dialog embedded via the Microsoft Edge WebView2 browser might not render completely and load indefinitely – without any errors displaying in the logs.

This seems to be caused by the user data folder (UDF) created by the WebView2 browser in C:\Users\<username>\AppData\Roaming\Blue Prism Limited\Automate V3 when you first attempt to log in using Authentication Server. This folder contains browser data such as, cookies, permissions, and cached resources. For more information, see Manage user data folders in Microsoft Edge.

To fix this issue, you need to delete the user data folder from C:\Users\<username>\AppData\Roaming\Blue Prism Limited\Automate V3, restart Blue Prism, and log in again using Authentication Server.