SSO configuration

Single sign-on (SSO) can also be used to onboard users onto the Service Assist platform. A blank user account is created when the user first accesses the website with a successful authentication confirmation sent by the identity provider (IDP). Active Directory or other Identity Provider integration can be configured for SSO using SAML 2.0.

SAML2 (Security Assertion Markup Language 2.0) is a protocol which allows an application that provides a service (‘service provider’, for example Outlook) to authenticate its end users by referencing another system where end users authenticate directly (‘identity provider’, for example , Microsoft Active Directory). This protocol allows users to only have one single password for all the applications connected through SSO, removing the need to log into multiple applications separately.

The following diagram shows how SAML works:

You can find more information about SAML here.

Prerequisites

The following prerequisites need to be met before configuring SSO for Service Assist:

1. The Identity Provider needs to support the SAML2 protocol.
2. The Identity Provider needs to have a valid certificate that needs to be stored in the Certificates folder of the API server, which is located in /var/local/<INSTANCE_NAME>api.<FQDN>/cert/ by default.
3. The Identity Provider needs to provide the sso_login_url and sso_logout_url parameters.
4. The API must have valid private_keys and certificates that need to be stored in the Certificates folder of the API server. It is recommended to use custom ones that are retained during API updates to avoid being re-consumed by the Identity Provider each time Service Assist is updated.
5. Once these details have been collated, they can be configured in the saml2 section of the config.json file and, after an API restart, Service Assist will be able to provide the metadata.xml to be consumed by the Identity Provider.

Configure SSO in configuration files

The SSO configuration is managed in the config.json and environment.json configuration files located in /var/local/<INSTANCE_NAME>.<FQDN>/config/.

1. Add the following section to the config.json file:

   Copy

   {
       "saml2": {
           "manageKeysWith": "<YOUR_MANAGED_KEYS_SECRET>",
           "sp_options": {
               "entity_id": "https://<YOUR_INSTANCE>/trustportal/saml/metadata.xml",
               "sp_private_key": "cert/<YOUR_CERTIFICATE_KEY_NAME>.key",
               "sp_certificate": "cert/<YOUR_CERTIFICATE_NAME>.crt",
               "assert_endpoint": "https://<YOUR_INSTANCE>/trustportal/saml/callback?saml=true"
           },
           "idp_options": {
               "sso_login_url": "<sso_login_url_provided_by_IdP>",
               "sso_logout_url": "<sso_logout_url_provided_by_IdP>",
               "certificates": [
                   "cert/<IDP_CERTIFICATE_NAME>.crt"
               ]
           }
       }
   }

2. In the environment.json file , change the ‘enabled’ parameter in the saml section to true and add the parameter ‘managedKeysWith’ present and set it to true.

   Copy

   {
     "apiUrl": "https://uat.trustportal.net",
     "autoLogout": {
       "idle": 3600,
       "timeout": 10
     },
     "disableCrypt": false,
     "passwordPolicy": {
       "length": 8,
       "uppercase": 1,
       "lowercase": 2,
       "number": 2
     },
     "saml": {
       "enabled": false,
       "default": true,
       "allowCreateUsers": false,
       "manageKeysWith": true,
       "loginButtonText": "SAML2 Login"
     },
     "assets": {
       "local": false
     }
   }

3. Save your changes and restart the docker API to apply the changes.

Service Assist should now display the metadata.xml that can be consumed by the Identity Provider.

Configure Identity Provider claims

Once Service Assist is running in SAML2 mode, you can configure the claims on the Identity Provider as indicated in the table below.

After this, the first user can be onboarded to Service Assist. This will be an Administrator who will be able to grant Administrator access to subsequent users if required.

It is also possible to save the claims information and retrieve it later from Blue Prism via the users' metadata. This allows administrators to define any virtual roles in Active Directory and store them in Service Assist. TPUM or any other user management process can then retrieve these virtual roles from the Service Assist database and assign the appropriate tiles, without the need to extract the data from Active Directory.

{
  "queueName": "CREATED_SAML_USER",
  "pageName": "ONBOARDING",
  "requestId": 5,
  "protocol": "send_blob",
  "payloadType": "product",
  "payload": {
    "data": {
      "email": "test1@tp",
      "lastname": "1",
      "firstname": "Test",
      "id": 14,
      "username": "test1@tp",
      "shareKeys": false,
      "metadata": {
        "virtualrole": [
          "\"Developer\"" 
        ]
      }
    },
    "logicKeys": {
      "roles": [
      ],
      "status_message": "",
      "user_status": "User Created"
    }
  },
  "sendUser": "test1@tp",
  "receiveUser": "robot_send_user",
  "callbackUri": "http://localhost:31999/robotcallback/"
}

{
  "queueName": "CREATED_SAML_USER",
  "pageName": "ONBOARDING",
  "requestId": 5,
  "protocol": "send_blob",
  "payloadType": "product",
  "payload": {
    "data": {
      "email": "test1@tp",
      "lastname": "1",
      "firstname": "Test",
      "id": 14,
      "username": "test1@tp",
      "shareKeys": false,
      "metadata": {
        "virtualrole": [
          "\"Developer\"" 
        ]
      }
    },
    "logicKeys": {
      "roles": [
      ],
      "status_message": "",
      "user_status": "User Changed" 
    }
  },
  "sendUser": "test1@tp",
  "receiveUser": "robot_send_user",
  "callbackUri": "http://localhost:31999/robotcallback/"
}