You are viewing documentation for a legacy Rasa product. If you want to get started building assistants with Rasa please check out our latest [documentation here](/content/docs/index.html).

You can configure Rasa Enterprise 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 marking one of your roles to be the default role ("Admin" -> "Manage Roles" -> \[Role\] -> "Edit" -> "Set as default roles").

##### warning

The usage of the environment variable `SAML_DEFAULT_ROLE` is deprecated and should be avoided. Please use the UI to configure the default role instead of using the variable.

If set, the environment variable `SAML_DEFAULT_ROLE`, will overwrite any default role set in the UI.

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 Enterprise

Rasa Enterprise 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 Enterprise SAML SP to work with your enterprise IdP.

1. Rasa Enterprise 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
```

2. The Rasa Enterprise 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
```

3. 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://<RASA_ENT_HOST>/api/auth/saml/metadata",
"assertionConsumerService": {
"url": "http://<RASA_ENT_HOST>/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`:

- `RASA_ENT_HOST`: The host endpoint that the IdP (provider) will use to connect to Rasa Enterprise. This is configured in Okta in the `Single sign on URL` and `Audience URI` values.
- `ENTITY_ID`: Identifier of the IdP identity. Okta provides this endpoint as the `Identity Provider Issuer`.
- `SSO_URL`: Target URL to which the SSO requests are sent. Okta provides this endpoint as the `Identify Provider Single Sign-On URL`
- `X509_CERT`: Public X.509 certificate of the IdP. This value should be provided as a string. This [SAMLTool page](https://www.samltool.com/format_x509cert.php) can be used to convert the X.509 certificate to string format.

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

4. Re-start Rasa Enterprise so that it will read the updated `settings.json`.
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 Enterprise 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](https://github.com/onelogin/python3-saml#how-it-works) on `python3-saml` for more details.

##### note

First-time SSO users are invited to choose their own username in Rasa Enterprise. 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](https://www.oasis-open.org/committees/download.php/4587#page=14).