Configure SAML authentication

The SAML protocol is widely supported by SSO identity providers, including PingFederate, AD FS, Okta, Microsoft Entra ID (formerly known as Azure Active Directory), or Active Directory.

Semarchy xDM supports authentication with SAML v2 providers using SAML identity providers.

Supported capabilities

With a SAML IDP, the authenticating user is redirected to the SAML identity provider for SSO.

During the authentication, the list of roles is returned in a Role Attribute (Assertion Attribute or Claim).

The profile properties are synchronized from assertion attributes, which are mapped by their name.

Configuration

In the SAML configuration definitions, the Identity Provider refers to the remote IDP Service, and the Service Provider refers to the Semarchy xDM server.
SAML is a complex protocol, which configuration may be simplified by using the Identity Provider Metadata URL. Via this URL, the identity provider exposes its configuration parameters which can be leveraged to automatically configure Semarchy xDM. Before configuring the SAML application in the Identity Provider you need to save the editor and start a test (or enable the identity provider) to make the Service Provider Metadata URL accessible.

To configure SAML authentication, follow the steps to configure an identity provider with the SAML type, using the properties listed in the following table for reference.

Property Definition

Connectivity
The following properties configure the connection and exchanges for SAML authentication.

Service Provider Metadata URL

This URL contains the service provider SAML metadata. This property is read-only. It is used to configure the corresponding application in the identity provider. The default generated value is <host-base-url>/saml2/service-provider-metadata/<idp-name>, where <host-base-url> is the base URL by which you access Semarchy xDM.

Make sure to save the identity provider configuration editor in Semarchy xDM before configuring the SAML application in our identity provider. Saving the editor makes the Service Provider Metadata URL visible to the identity provider.

In high-availability architectures, you can access Semarchy xDM via two URLs:

  • One for the Active Node, using the host and port of the active node.

  • One for Load Balancer routing the traffic on the passive nodes, using the host and port of the load balancer.

Make sure to configure in the SAML IDP different client applications for each URL, for the authentication to work for both the active node and load-balanced passive nodes. Each application will use different values for the Service Provider Metadata URL, Assertion Consumer Service URL, and Service Provider Entity ID properties.

Assertion Consumer Service URL

The identity provider will use this URL to service the SAML messages to the service provider. This property is read-only. It is used to configure the identity provider. The default generated value is <host-base-url>/login/saml2/sso/<idp-name>, where <host-base-url> is the base URL by which you access Semarchy xDM. See the note above for high-availability architectures.

Service Provider Entity ID

The application or service provider identifier that must be configured in the identity provider. This property is read-only. By convention it is set to <host-base-url>, that is the base URL by which you access Semarchy xDM. See the note above for high-availability architectures.

Identity Provider Metadata URL

If the identity provider supports it, this URL provides an automated configuration.

Connect using Metadata URL

This boolean defines whether to use the Identity Provider Metadata URL to automatically configure the IDP. Using the metadata URL simplifies the configuration and automatically sets the following properties: Identity Provider Entity ID, Web SSO Endpoint, Logout URL, and Identity Provider Public Key.

Identity Provider Entity ID

Entity ID of the remote identity provider. It is typically a string or a URI This property is hidden if Connect using Metadata URL is selected.

Web SSO endpoint

URL to which the authentication request is sent to. This property is hidden if Connect using Metadata URL is selected.

Logout URL

Identity provider URL to perform the SSO logout. If the unspecified, only a local logout is performed. This property is hidden if Connect using Metadata URL is selected.

Identity Provider Public Key

Public key of the identity provider and used by the service provider to validate the signed responses. This key is required if Connect using Metadata URL is set to false. This key should be in PEM-encoded x.509 format. This property is hidden if Connect using Metadata URL is selected.

Sign Authentication Request

This boolean value indicates whether to sign the authentication request. The SHA-256 algorithm is used by default. The default value is true. When this option is selected, the Signature Private Key and Signature Public Key must be provided.

Signature Private Key

Private key used to sign the requests sent by the service provider. If this key is empty requests are not signed. This key is the private key corresponding to the Signature Public Key. This property is mandatory if Sign Authentication Request is selected. This key should be in PEM-encoded PKCS#8 format.

Signature Public Key

Public key provided to the identity provider to validate the signed requests. This key is the public key corresponding to the Signature Private Key. This property is mandatory if Sign Authentication Request is selected. This key should be in PEM-encoded x.509 format.

Encryption Private Key

Private key used to decrypt the responses sent by the identity provider. This key is the private key corresponding to the Encryption Public Key. If this key is empty, responses are considered not encrypted. This key should be in PEM-encoded PKCS#8 format.

Encryption Public Key

Public key provided to the identity provider to encrypt the responses. This key is the public key corresponding to the Encryption Private Key and is required if the Encryption Private Key is set. This key should be in PEM-encoded x.509 format.

Roles
The following properties how the roles are transmitted in the SAML token.

Roles Attribute

Assertion attribute containing the list of roles. Note that roles may be issued as an XML array, a list, or a list in a string. If this attribute is a list in a string, the Roles Attribute Separator defines the list separator.

Roles Attribute Separator

Character separating roles in the role attribute, if the role attribute is a delimited string. The default value is ,.

Advanced
The following properties cover specific configuration situations.

Name ID Format

Format requested by the service provider for the Name ID attribute and returned in the authentication response. The service provider requests this format as the NameIDPolicy in the request, and the identity provider will indicate in the metadata a preferred format. This property represents the structured user identifier returned in the SAML response. For example urn:oasis:names:tc:SAML:2.0:nameid-format:persistent or urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Authentication Request Signature Algorithm

Algorithm used to sign the authentication request. The most frequent values are:

  • RSA-SHA1

  • RSA-SHA256 (default)

Protocol Binding

Protocol bindings used to return the authentication response. This is a service provider configuration, but the identity provider may only support a given protocol. Possible values are:

  • Post: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

  • Redirect: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

Authentication Context Class Reference

Identifier for an authentication context class to permit augmentation of assertions with additional information about the authentication of the principal by the identity provider. This property may be provided by the metadata URL when Connect using Metadata URL is selected. For example: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

Maximum Clock Skew

Time difference (seconds) accepted between the service provider and identity provider servers. The default value is 10.

Profile synchronization

With SAML, each profile attribute may be mapped to an assertion attribute by its name. The identity provider must be configured accordingly to enrich the SAML token with these attributes.