Single Sign-on

You can configure your Rasa X EE installation to use single sign-on (SSO). When a user first signs in, they will be prompted to create a username. New users will be assigned the default role. You can customize the default role by marking a role as “default” in the Manage Roles view. After signing in, new users are prompted to contact the admin if they require extra permissions. The admin can then assign them to a specific role.

Rasa X EE supports SSO using the Security Assertion Markup Language (SAML) 2.0 protocol.

Configuring SAML SSO for Rasa X

Rasa X acts as a service provider (SP) which initiates the SSO request to an external SAML authority, called the identity provider (IdP). This section describes how to configure the Rasa X SAML SP to work with your enterprise IdP.

1. Rasa X mounts SAML certificates, keys and a settings file from your project directory. Create a directory for the authentication information with

$ cd /etc/rasa && mkdir -pv auth/certs

2. The Rasa X SAML SP requires a X.509 certificate to sign the authentication request. You’ll need to create a certificate and the corresponding private key in auth/certs. To do this, run:

$ cd /etc/rasa/auth/certs
$ openssl req -new -x509 -days 3652 -nodes -out sp.crt -keyout saml.key

3. The SAML SP has to be configured using a json file. Create a file called settings.json in your auth directory with the following content:

{
  "strict": true,
  "debug": true,
  "sp": {
    "entityId": "http://localhost/api/auth/saml/metadata",
    "assertionConsumerService": {
      "url": "http://localhost/api/auth/saml/acs",
      "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
    },
    "NameIDFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  },
  "idp": {
    "entityId": "<ENTITY_ID>",
    "singleSignOnService": {
      "url": "<SSO_URL>",
      "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    },
    "x509cert": "<X509_CERT>"
  }
}

Replace the following placeholder variables with values specific to your SAML IdP:

  • ENTITY_ID: Identifier of the IdP identity
  • SSO_URL: Target URL to which SSO requests are sent
  • X509_CERT: Public X.509 certificate of the IdP

You can specify additional details about your IdP in settings.json. Have a look at onelogin’s documentation on python3-saml for more details.

Note

First-time SSO users are invited to choose their own username in Rasa X. This feature relies on a permanent NameID (i.e. the nameid-format cannot be of type transient). For available nameid-format types, please have a look at the section on format identifiers in the SAML 2.0 Name ID specification document.