SAML-based Authentication

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

Identity provider (on the customer side)
Authentication backend in xorlab Security Platform
Certificate in a trust store

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.

SAML app from Azure Active DirectoryFor SAML authentication using Azure Active Directory services, please refer to SAML Authentication Using AAD Services.

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

Authentication request signing is now supportedIf your IdP requires authentication request signing, this optional feature is supported in xorlab Security Platform. For more information, please refer to Authentication request signing.

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.

Before you start configuring this backend in XSP, please read the Authentication article, if you haven’t already.

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:

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 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:

    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 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), 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).

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.

A sample role mapping configuration is shown below:

    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:

    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 configuration and that its value is a one-on-one match with the authTenantId property specified in the Multi-Tenancy Configuration. For roleMapping, make sure to map to a tenant-restricted user roles.

    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:

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

Shared mailboxes and aliasesThe configuration from the above example will not support shared mailboxes or aliases obtained with the proxyAddresses attribute.

​Identity provider configuration

​xorlab Security Platform configuration

​Basic configuration

​Attribute mapping

​Role mapping

​Multi-Tenant Configuration

​Example configuration

Identity provider configuration

xorlab Security Platform configuration

Basic configuration

Attribute mapping

Role mapping

Multi-Tenant Configuration

Example configuration