Troubleshooting – Single sign-on

This page describes some common issues and suggested resolutions for system administrators using and managing Single Sign-on in Blue Prism.

Users can't sign in or performance issues occur during login

If login failures or performance issues are encountered during the login process via Active Directory, system administrators can check whether any of the scenarios below apply and perform the appropriate action.

Some additional database scripts may be required for troubleshooting. These can be downloaded from the Blue Prism Portal as required. Where required, the appropriate database script is named in the scenarios below.

  • Log out and back again – If all user settings, including security groups are correct, try logging out and logging on again to the user's machine. When a user is added to an Active Directory group, the change takes effect the next time they log on.

  • Check the user's Blue Prism roles and their Active Directory security group membership – If the user is a member of the Blue Prism Administrators group , they should be able to sign in.

    If a user is attempting to sign in following a product upgrade and they receive the error message "Login failed. This user has no roles assigned in Blue Prism", download the database script BP‑9497‑ConfigureTrustedDomain.sql from the Blue Prism Portal and follow the steps outlined in this Knowledge Base article.

    Check that the user account has been created and has been assigned at least one Blue Prism role, either directly or via security group membership.

    You should first synchronize users with Active Directory on the Security - Users screen. If the user account does not display in the user list, this means it has not been created yet:

    • If user roles are managed in Blue Prism, you should create the user account and assign the required roles to it.
    • If user roles are managed in Active Directory, you should check which Active Directory groups are mapped to the Blue Prism roles under System > Security > User Roles. The user should be a member of at least one of these groups. If not, your network administrator should add the account to the appropriate security group before you synchronize the user list with Active Directory again to check that the account displays in the user list.
    • If roles are managed both in Blue Prism and Active Directory, you should create the user account and assign the required roles to it directly and/or via security group membership, as required.
  • Check the Blue Prism application server connection – Make sure the user is connected to a Blue Prism application server with a valid and secure connection mode and that an Active Directory user record exists for the currently logged-in Windows user.
  • Check if you need to configure the Active Directory timeout limit – If a user either cannot sign in using Active Directory or is experiencing performance issues during the login process, and the logs show several instances of System.TimeoutException: Timeout after 5 seconds, you can set an Active Directory timeout limit in the database. The database script BP‑9268‑SetActiveDirectoryQueryTimeout.sql is available for download from the Blue Prism Portal for this purpose. This will alter the timeout settings for the application server(s) and all API instances pointing to the Blue Prism database. Back up your database before running this script against your Blue Prism database.

  • Check if you need to manually configure the Active Directory domains that will be queried during the login process – To reduce the time taken for the Active Directory cache to populate, system administrators can manually configure the 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. The database script BP‑9497‑ConfigureTrustedDomain.sql is available for download from the Blue Prism Portal for this purpose.

    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.

    Before running the script, please ensure that:

    • You have backed up your Blue Prism database.
    •  Any Active Directory domains that meet one or more of the following criteria are manually configured (if using Blue Prism versions 7.1.0 or 7.1.1):
      • Contain users that must be able to log in.
      • Contain security groups that are assigned directly to Blue Prism roles.
      • Contain parent security groups which include security groups that are directly assigned to Blue Prism roles.
    •  Any Active Directory domains that meet one or more of the following criteria are manually configured (if using Blue Prism version 7.1.2 or later):
      • Contain users that need to log in using telnet commands or processes exposed as web services using a User Logon Name (Pre-Windows 2000) username format. For example, john as opposed to DOMAIN\john or [email protected].
      • Contain users that have an alias 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. An optional database script to configure alias suffixes (BP-10681-ConfigureUpnSuffixes.sql) is available for download from the Blue Prism Portal.
    • The domain host name, security identifier (SID), and the name of the forest in which the domain resides has been provided for each domain that needs to be queried.

  • Check if you need to configure domain cache settings – To further improve performance during login, the behavior of the cache that stores the discovered domains can be configured by setting a refresh interval and a maximum cache duration. The database script BP‑9654‑SetCacheDurationAndRefreshInterval.sql is available for download from the Blue Prism Portal for this purpose. Back up your database before running this script against your Blue Prism database.

    • 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 set to 30 if using Blue Prism versions 7.1.0 or 7.1.1, and to 1440 if using Blue Prism version 7.1.2 or later.

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

  • Check if you need to configure Domain Controller name mappings – You might need to configure Domain Controller name mappings in the database if the following error message and log displays when searching for Active Directory users or security groups, and when adding or editing Active Directory domains:

    • Error message: The domain record could not be saved: Invalid credentials. Please check your credentials.

    • Error log: The user name or password is incorrect. If the domain credentials for dc=example,dc=com are valid, please provide a domain controller mapping record.

      This could occur if the domain of interest is on a different network from the network on which the Blue Prism application server is running. If you are certain that the provided credentials are correct, you need to add domainName and domainControllerName parameters to the database so Active Directory queries for the domain specified in domainName are directed to the endpoint defined in domainControllerName.

      To do this:

      1. Back up your Blue Prism database.
      2. Download the BP-9420-AddDomainNamePreferences.sql script from the Blue Prism Portal and open it in a suitable editor.

      3. Update the placeholder values for the domainName and domainControllerName parameters for each required domain with your own values, for example:

        • domainName – The name of your Active Directory domain or the DNS name of the domain, for example, company.com.
        • domainControllerName – The DNS name of the domain, for example, company.com or the FQDN of a Domain Controller in the domain, for example, server-id.company.com.

      4. Execute the script against your Blue Prism database.

Windows credentials are required

If after signing in via Active Directory, you are prompted to enter Windows credentials, please check that you have configured a Service Principal Name (SPN) against the Active Directory account under which each Blue Prism Server service instance is running and a Kerberos realm for each BP Server connection in the Blue Prism interactive client. For more details, see SPN configuration.

Error messages display

The trust relationship between this workstation and the primary domain failed.

This error indicates a problem with your network configuration. It can sometimes be a symptom of a disjointed namespace (a scenario in which a computer's primary domain name system (DNS) suffix doesn't match the DNS domain name where that computer resides).

The specified domain does not exist or cannot be contacted.

Sometimes a machine can appear to be a member of a domain, but badly configured. If this only happens from a specific machine, whereas other machines work without problems then this may be the problem. In this case, remove the machine from the domain and reattach it (a Domain administrator will need to carry out this action).

The local machine is not a member of an Active Directory domain, or the domain cannot be contacted.

If you receive this message, this means that you need to request your Active Directory domain administrator to add you to an Active Directory domain before you can configure Active Directory authentication.

Unable to retrieve the members of Security Group {Security Group Name} because it contains members which are either Foreign Security Principals or have unresolved SIDs.

Some Active Directory security groups (for example, some built-in groups) present querying difficulties and therefore such configurations are not recommended. Whilst users from these groups will be able to sign in with the correct permissions, some Blue Prism screens may not be able to accurately display membership information.