notice

This is documentation for Rasa X Documentation v0.34.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (1.1.x).

Version: 0.34.x

Single Sign-on

You can configure your Rasa Enterprise 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 Enterprise 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 and a directory for storing the configuration file with
cd ${RASA_HOME}
mkdir -pv auth/certs
mkdir -pv auth/saml
  1. 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 ${RASA_HOME}/auth/certs. To do this, run:
cd ${RASA_HOME}/auth/certs
openssl req -new -x509 -days 3652 -nodes -out sp.crt -keyout saml.key
  1. The SAML SP has to be configured using a json file. Create a file called settings.json in ${RASA_HOME}/auth/saml 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 the SSO requests are sent

  • X509_CERT: Public X.509 certificate of the IdP

If you want to activate the SAML endpoint before you have your actual SAML IdP for example for a metadata-based configuration of your IdP, you need to make sure that you use these values with:

  • ENTITY_ID: is not empty

  • SSO_URL: has the format of a URL, for example https://example.com

  • X509_CERT: is not empty

Once the Rasa X service has been (re-)started after modifying the SAML settings, you can retrieve the SAML endpoint metadata by issuing this GET command:

curl http://<Rasa X server host>/api/auth/saml/metadata

You can specify additional details about your IdP in settings.json, as well as in an additional file called advanced_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.