> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# SAML-based Authentication

In order to get a working SAML2 authentication setup, you have to configure three elements:

1. Identity provider (on the customer side)
2. Authentication backend in xorlab Security Platform
3. [Certificate in a trust store](/9.0/authentication#certificate-configuration)

Because multiple SAML2 identity providers can be active simultaneously in xorlab Security Platform, they have to be distinguished by their names in the XSP configuration. Here, this name will be referred to as `saml2BackendName`.

<Note>
  **SAML app from Azure Active Directory**

  For SAML authentication using Azure Active Directory services, please refer to *[SAML Authentication Using AAD Services](/9.0/saml-aad-authentication)*.
</Note>

## Identity provider configuration

There are many different identity providers and we are only going to point out the cornerstones of the required configuration.

On the identity provider side, you have to set up a new application for xorlab Security Platform with the following properties:

* SSO URL: `https://<XSPDomain>/auth/saml2/sso/<saml2BackendName>`
* Audience URI (SP Entity ID): `https://<XSPDomain>/auth/saml2/service-provider-metadata/<saml2BackendName>`
* The SAML2 response needs to be signed
* The SAML2 assertion needs to be signed

<Tip>
  **Authentication request signing is now supported**

  If your IdP requires authentication request signing, this optional feature is supported in xorlab Security Platform. For more information, please refer to *[Authentication request signing](/9.0/authentication#authentication-request-signing)*.
</Tip>

In addition, the SAML2 assertion must have attributes to transport the:

* username (required; a list of one element)
* roles (required; a list of many elements)
* display name (optional; a list of one element)
* emails (optional; a list of many elements)
* `nameID` claim (required)

Mapping these assertion attributes to xorlab Security Platform user attributes can be specified in the configuration.

<Note>
  Before you start configuring this backend in XSP, please read the *[Authentication](/9.0/authentication)* article, if you haven’t already.
</Note>

## xorlab Security Platform configuration

The configuration on the xorlab Security Platform side is in the `auth.yml` file under the `saml2AuthBackends:` section. It is important that you use the same name for the SAML2 backend within XSP as it is named on the identity provider side.

Also, the identity provider needs to provide the metadata for the application configuration either via an URL or in a file.

### Basic configuration

All basic settings are configured under the `idp:` subsection of the SAML backend section—in the example below we used `mySamlProvider` as the backend name:

```yaml theme={null}
saml2AuthBackends:
  mySamlProvider:
    idp:
      metadataFile: example-saml-provider-metadata.xml
      # metadataUrl: https://example-idp.com/metadata
```

If the IdP (Relying Party) metadata is stored in a file, specify its location and name as a value for the `metadataFile` attribute. Otherwise, point to this metadata available over a HTTP(S) endpoint by providing its URL address as a value for the `metadataUrl` attribute. Note that only one metadata location can be specified so, in the above example, the `metadataUrl` key is commented out and XSP will use the metadata file.

### Attribute mapping

In the next step, you have to map (assign) attributes from the SAML assertion to the user model in xorlab Security Platform. The mapping is described using [Spring expression language](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html) and is configured under the `attributeMapping:` subsection.

You can use these methods:

* `attr('<name>')`: retrieve the attribute with the `'<name>'` name from attributes in the source authorization system.
* `replace(<string or list of strings>, '<pattern>', 'replace')`: replace every occurrence of `'<pattern>'` with `'replace'` in an input string or a list of input strings.
* `azureAdEmails()`: read all email addresses from the Azure Active Directory `proxyAddresses` attribute.

Literal values have to be quoted, e.g., `key: 'literal value'`.

A sample configuration for attribute mapping which simply retrieves attributes from the auth system (MS AAD in this case) would look like this:

```yaml theme={null}
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
```

Available attributes are explained in the table below:

| Attribute     | Description                                                                                                                                                                                                                                                                                                                                                           |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userName`    | An attribute mapping for the username. The result of this mapping will be put into the `subject` attribute of the token issued to the consuming services<br />**Note:** The default is to use the assertion subject as a username. If you want to change this behavior, then specify a mapping for the username. However, in most setups, this should not be the case |
| `displayName` | An attribute mapping for the display name of the user. It is optional and could be used by consuming services in places where a more descriptive name of the user is appreciated                                                                                                                                                                                      |
| `emails`      | Mapping for the list of emails associated with the user. Consuming services might use this list to associate the user with a certain pool of email messages                                                                                                                                                                                                           |
| `roles`       | Mapping for the list of roles assigned to the user. This mapping can only be set for authentication backends which do not do their own authorization                                                                                                                                                                                                                  |
| `tenant`      | **Only required for multi-tenancy deployments**: Make sure the value of the `tenant` attribute correspond to the `authTenantId` defined in the `guarded_tenants.yml`.                                                                                                                                                                                                 |

### Role mapping

The last step is to configure role mapping. You must map all roles served by the SAML identity provider to the corresponding XSP roles under the `roleMapping:` subsection. Roles that are not mapped are ignored by default. Multiple XSP roles can be mapped to the same identity provider role, e.g., `xcc_login` → `company1-group1`, `xcc_admin` → `company1-group1`.

If the SAML identity provider already serves roles compatible with xorlab Security Platform (see *[Users, Roles, and Permissions](/9.0/users-roles-and-permissions)*), you can also specify a “pass-through” role-mapping mode using `roleMappingMode: PASS_THROUGH` (note that this was the default behavior before XSP 7.0).

<Note>
  Please be aware that in the pass-through role-mapping mode, all roles served by the SAML identity provider are added to the XSP authorization context. If this context is becoming too large, i.e., too many irrelevant roles are added, then it might lead to errors and users being unable to access XCC. Therefore, it is advisable to only map the roles that are relevant to XSP.
</Note>

A sample role mapping configuration is shown below:

```yaml theme={null}
    roleMapping:
      xcc_admin:
      - xcc_admin
      xcc_monitor:
      - xcc_monitor
      xcc_insights:
      - xcc_insights
      xcc_quarantine_user:
      - xcc_quarantine_user
```

A sample role mapping configuration using the pass-through mode:

```yaml theme={null}
    roleMappingMode: PASS_THROUGH
    roleMapping:
      # You can still define a role mapping in pass-through mode
      xcc_monitor: [ xcc_admin ]
```

### Multi-Tenant Configuration

Please follow the instructions on this page to setup SAML-based Authentication in a multi-tenancy deployment. Make to include the `tenant` property in the [Attribute Mapping](#attribute-mapping) configuration and that its value is a one-on-one match with the `authTenantId` property specified in the [Multi-Tenancy Configuration](/9.0/multi-tenancy-configuration). For `roleMapping`, make sure to map to a [tenant-restricted user roles](users-roles-and-permissions.md/#roles).

```yaml theme={null}
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
      tenant: tenantA # should correspond to authTenantId in guarded_tenants.yml
```

### Example configuration

The final configuration for a SAML backend—Azure in this example—should look like this:

```yaml theme={null}
tokenSigningKey: "xyz"

enabledAuthBackends:
  - azureSaml

saml2AuthBackends:
  azureSaml:
    idp:
      metadataUrl: https://login.microsoftonline.com/<tenant_id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app_id>
    attributeMapping:
      displayName: attr('http://schemas.microsoft.com/identity/claims/displayname')
      emails: attr('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name')
      roles: attr('http://schemas.microsoft.com/ws/2008/06/identity/claims/role')
    roleMapping:
      xcc_admin:
      - xcc_admin
      xcc_monitor:
      - xcc_monitor
      xcc_insights:
      - xcc_insights
      xcc_quarantine_user:
      - xcc_quarantine_user
```

<Note>
  **Shared mailboxes and aliases**

  The configuration from the above example will not support shared mailboxes or aliases obtained with the `proxyAddresses` attribute.
</Note>