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 SAML default role by setting the SAML_DEFAULT_ROLE environment variable to either admin, annotator or tester, or alternatively to one of your custom roles.

You have the option to pre-define roles for new SAML users with a known Name ID on the command line by running

$ cd ${RASA_HOME}
$ sudo python rasa_x_commands.py create-saml <ROLE> <NAME-ID>

After signing in, new SAML users are prompted to contact the admin if they require extra permissions. An 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.