Active Directory authentication through AD FS

Click this icon on the toolbar to view and download a PDF version of this guide.

This guide describes how to configure Active Directory authentication for SS&C | Blue Prism® Decipher IDP users, by enabling Active Directory Federation Services (AD FS). It assumes that you have Active Directory configured and AD FS installed for your Blue Prism environment.

Active Directory authentication through SAML 2.0 using Microsoft® Active Directory Federation Services (AD FS) is the only identity provider (IdP) verified and supported for this release. However, this functionality is not limited to AD FS and could be applied to other SAML IdP providers.

Please refer to Limitations and known behaviors for details of behaviors that are particular to using this release of Decipher IDP with SAML authentication.

Intended audience

This guide is aimed at IT professionals competent in configuring Active Directory environments, AD FS, and SAML.

Architecture overview

The example in this guide use two machines. One is referred to as the AD FS server, where AD FS is configured and installed, and the second is the Decipher web server, which hosts the Decipher web server.

The architecture is as follows:

SAML authentication using ADFS

The configuration of Blue Prism is not covered in this guide, and is shown in this diagram only for illustrative purposes.

Prerequisites

  • Active Directory configured for Blue Prism.

  • AD FS installed. See Microsoft’s AD FS documentation for installation and configuration details.

  • Decipher IDP version 2.2 is installed.

It is recommended that the steps outlined in this guide are followed in the order described.

Export the token-signing certificate

You need to export the AD FS certificate so it can be imported into the Decipher IDP system. To export the certificate:

  1. On the AD FS server, open Server Manager, and select the relevant server.

  2. On the top navigation bar, select Tools, and then AD FS Management.

    The AD FS dialog displays.

  3. From the left-hand navigation, expand Services, then select Certificates.

  4. Locate the Token-signing section, right-click the certificate, and select View Certificate....

  5. Select the Details tab in the top bar, and then Copy to File....

    The Certificate Export Wizard displays.

  6. Select the DER encoded binary X.509 (.CER) option, and click Next.

  7. Configure the Certificate name as Idp.cer, and choose a file location on the local system to export the file to.

  8. Click OK, then Finish to complete the export.

Import the token-signing certificate

Once exported, the certificate must be imported into the Decipher IDP system. To import the certificate:

  1. On the Decipher web server, open the installation directory of the Decipher Web client. By default, this is C:\Program Files (x86)\Blue Prism\Decipher Web.

  2. Create a new folder called App_Data.

  3. Copy the exported Idp.cer file into the App_Data folder.

  4. Open the Idp.cer file, and click Install Certificate....

    The Certificate Import Wizard displays.

  5. In the Store Location box, select Local Machine, and then Next.

  6. On the Certificate Store page, select Place all certificates in the following store.

    The Select Certificate Store dialog displays.

  7. From the dialog, select Trusted Root Certification Authorities, and then OK.

  8. Click Next to import the certificate.

Edit the Decipher IDP Web.config file

On the Decipher web server, the Decipher web client config file must be updated to configure the SAML parameters.

  1. On the Decipher web server, open the Web.config file using a text editor. By default, the Web.config file is located: C:\Program Files (x86)\Blue Prism\Decipher Web\Web.config.

  2. In the system.webServer node, add the following parameter to the modules element:

    <add name="Saml2AuthenticationModule" type="Sustainsys.Saml2.HttpModule.Saml2AuthenticationModule, Sustainsys.Saml2.HttpModule"/>

  3. In the sustainsys node, populate the following parameters:

    Parameter

    Description

    entityId="Id"

    Your Decipher IDP application URL, and is in the format:
    https://your-application.url.

    For example, https://sso-test.domain.com.

    returnUrl="Url"

    The Decipher IDP application URL appended with /Account/SsoLogin, and is in the format:
    https://your-application.url/Account/SsoLogin.

    For example, https://sso-test.domain.com/Account/SsoLogin.

  4. In the sustainsys node, in the identityProviders element, populate the following parameters:

    Parameter

    Description

    entityID="Id"

    This is in the format: https://your-adfs.url/adfs/services/trust.

    signOnUrl="Url"

    This is in the format: https://your-adfs.url/adfs/ls.

    logoutUrl="Url"

    This is in the format: https://your-adfs.url/adfs/ls/?wa=wsignout1.0.

  5. In the sustainsys node, in the federations element, populate the following parameter:

    Parameter

    Description

    metadataLocation="Url"

    This is in the format: https://your-adfs.url/FederationMetadata/2007-06/FederationMetadata.xml".

  6. In the sustainsys node, in the serviceCertificates element, delete the following parameter:

    <add fileName="~/App_Data/service.pfx" />

  7. Save and close the config file.

Configure relying party trusts

You need to configure a relying party trust on the AD FS server machine using the SAML XML file exported from the Decipher web server.

  1. From the Decipher web server, download the SAML XML file by navigating to: 
    https://your-application.url/Saml2. For example, https://decipher.company-name.net/Saml2.

  2. Copy the SAML XML file to the domain controller machine.

  3. On the AD FS server, open Server Manager, and select the relevant server.

  4. On the top navigation bar, select Tools, and then AD FS Management.

    The AD FS dialog displays.

  5. From the left-hand navigation, right-click Relying Party Trusts, and select Add Relying Party Trust....

    The Add Relying Party Trust Wizard displays.

  6. On the Welcome page, select Claims aware, and then Start.

  7. On the Select Data Source page, select Import data about the relying party from a file.

  8. Use the Browse... button to locate the SAML file exported from the Decipher web server machine, then click Next.

  9. On the Specify Display Name page, define a Display name. For example, Decipher Company SAML Relying Party.

  10. Proceed through the wizard to the Choose Access Control Policy page. Ensure Permit everyone is selected, then click Next.

  11. On the Finish page, enable the Configure claims issuance policy for this application option, and click Close.

    The AD FS dialog displays.

  12. Right-click on the SAML Relying Party you just created, and select Edit Claim Issuance Policy....

  13. On the Issuance Transform Rules tab, select Add Rule....

    The Add Transform Claim Rule Wizard displays.

  14. On the Choose Rule Type page, ensure the Claim rule template option is set to Send LDAP Attributes as Claims.

  15. Click Next.

  16. On the Configure Rule Type page, add the following rules:

    1. For UPN:

      • Claim rule name – Enter a name for the rule.

      • Attribute store – Select Active Directory.

      • Mapping of LDAP attributes to outgoing claim types:

        • LDAP attribute – Select User-Principal-Name.

        • Outgoing Claim Type – Select Name ID.

    2. For groups:

      • Claim rule name – Enter a name for the rule.

      • Attribute store – Select Active Directory.

      • Mapping of LDAP attributes to outgoing claim types:

        • LDAP attribute – Select Token-Groups - Unqualified Names.

        • Outgoing Claim Type – Select Group.

  17. Click Finish.

Create Decipher IDP and Active Directory user groups

This release of Decipher IDP only supports one group per user. Users who are members of more than one Active Directory group can log in to Decipher IDP, but will only be assigned to one group chosen at random. It is therefore recommended that users are only added to one Active Directory group for use with Decipher IDP.

User groups in Decipher IDP are used to assign the same roles and permissions to sets of users. By mapping these to user groups in Active Directory, Decipher IDP users’ roles and permissions can be automatically assigned based on their Active Directory group membership, without an administrator manually assigning them within Decipher IDP.

You must create the same user groups in Decipher IDP and Active Directory. User group names are case‑sensitive, which means the capitalization used for the group names must match exactly.

In Decipher IDP:

  1. Log in as an Admin user and create the required user groups.
  2. Define the required user roles and assign the relevant permissions to the groups.

In Active Directory:

  1. Create identical user groups to those created in Decipher IDP.
  2. Add the required Decipher IDP users to the user groups.

Decipher IDP user creation

Because matching groups have been created in Decipher IDP and Active Directory, when a user successfully logs in to Decipher IDP using their Active Directory credentials, the corresponding user will automatically be created in Decipher IDP.

It is not necessary to manually create users in Decipher IDP. However, if your organization wants to allow users to log into Decipher IDP without using their SSO credentials, or to be familiar with their Decipher-only credentials, you can choose to manually create users in Decipher IDP. Creating matching users in Decipher IDP also means that the Decipher IDP administrator can manage the user's Decipher-only password.

Create a master user

In addition to the Decipher IDP Admin user that was created during installation you must create a master user (also referred to as the SSO master user). The master user is required for SAML authentication to establish a connection between the Decipher Web client and the Decipher Server. Once created, it is recommended that the master user is not changed by the Decipher IDP Administrator, or used to administer Decipher users.

Create the master user in Decipher IDP

  1. Log in to Decipher IDP, and open the Admin Panel.

  2. Select Users from the left-hand navigation menu, then Add User.

    The Add New User window displays.

  3. Configure the master user as required, ensure that: 

    • The Username and Password are configured as master.

    • The User group is set to Administrators.

  4. Click Create User.

  5. Return to the Admin Panel, and select Configuration from the left-hand navigation menu.

  6. In the Single sign-on section, toggle the Enabled option to On.

  7. Configure the options:

    • Master username – The username for the master user that you created in step 3.

    • Master password – The password for the master user that you created in step 3.

    • SAML URL – The expected format is: https://your-application.url/Saml2/SignIn.

      • The Master username and password will be saved in the Web.config file as SsoLoginUsername and SsoLoginPassword and encrypted.

  8. Save your changes.

    Upon saving, master user's credentials are written to the Web client config file and the client restarts. You will be automatically logged out and returned to the Decipher IDP login page.

    When the Web client config file restarts any active users are logged out of Decipher IDP.

The standard Decipher IDP login option is automatically disabled when SSO is activated. It is recommended that the standard behavior is retained. However, if required the standard Decipher login option can be enabled by setting the SsoStandardLoginEnabled attribute to True in the Web.config file. For more information, see Configuration file parameters.