This SAML HowTo can serve as a good example of how Unity works in general. That said, reading it will help when integrating other protocols (as an external LDAP authentication) too.
This HowTo provides a step-by-step guide on configuring SAML 2 based authentication in Unity. A basic familiarity with SAML is needed to understand this document. The Wikipedia article on SAML 2 and the official SAML overview provide more then enough of information.
SAML can be used in two ways:
By Unity clients to get information from Unity, e.g. a web application may request to authenticate its web browser user in Unity. In this case Unity acts as an Identity Provider (IdP) in the SAML terminology. This functionality is enabled by a SAML endpoint, which must be configured in Unity.
By Unity itself to delegate authentication to a 3rd party SAML Identity Provider (IdP). In this case Unity acts as Service Provider in the SAML terminology (from the perspective of the 3rd party IdP). This functionality is enabled by configuring a SAML authenticator in Unity and attaching it to one or more of Unity endpoints.
Both scenarios are presented in a slightly simplified form in the diagrams:
Of course it is possible to deploy both scenarios together, to use Unity as a service which either enrich/transform information about users from upstream IdPs or which provides a common gateway to multiple SAML federations, typically unifying their contents.
Unity was successfully tested against:
Shibboleth IdP 2.4 using Unity as SP
Shibboleth SP 2.5 using Unity as IdP
SimpleSAMLPhp 0.11 using Unity as IdP and as SP
Unity - you can use another Unity instance (or even the same instance - for testing) both as an IdP or as an SP.
Of course any other SAML 2 compliant service should be also able to work with Unity.
1.2. Limitations aka what is not supported in Unity YET
As of version 1.6.0 of Unity there are some minor restrictions related to SAML integration. The most important one is:
Discovery Service functionality is not supported in Unity yet. This will be improved in upcoming versions. However Unity comes with a decent Discovery Service functionality embedded, so there is no real need to use external service and therefore we treat this missing functionality with low priority.
2. Using Unity as SAML IdP: configuring SAML endpoints
To enable SAML IdP functionality, one of Unity SAML endpoints must be configured: either the SAML Web endpoint or the SAML SAOP (Web Service) endpoint. The first one is the typical choice, for authentication of Web browser users of Web applications. The latter is used by command line programs, agents or desktop applications, which support SAML directly, without having to use a standard Web browser as intermediary. In the following text the SAML Web endpoint will be configured.
2.1. Step 1: Prepare SAML endpoint configuration
There is a couple of SAML specific options that need to be set.
SAML issuer (
unity.saml.issuerURI) is a unique name of your IdP in SAML domain (often called as a federation). You can choose any URI as a value, but it is suggested to use a URI of your endpoint SAML metadata.
unity.saml.credential) is used to sign SAML assertions and responses (if configured). Typically the credential is the same credential which is used by the Unity HTTPS server, but you can configure a separate one. The credentials are configured in
pki.propertiesfile, in SAML endpoint only a name of credential configured there is used.
Base group: (
unity.saml.groupMapping.*) SAML, by default does not support group scoped attributes and the majority of SAML consumers won’t understand the Unity concept of an attribute being defined in a particular group. Therefore Unity group must be selected and only the attributes defined in this group will be exposed to the clients. For this purpose a single group can be used or different groups can be configured on a per-SP basis.
SP acceptance settings control who is authorized to act as an SP, i.e. to query the endpoint and receive SAML assertions. Typically the SAML endpoint trust is configured using SAML metadata, what is by far the simplest and suggested choice. Unity also allows admins to control the trusted SPs manually, either not to use metadata or to enrich federation metadata with custom SPs. Unity supports several trust models: from fully open to models where each SP needs to be enumerated. Choice of the trust model is controlled with the
unity.saml.spAcceptPolicyproperty. The most popular way to control this trust in the SAML world is to use one type of such enumeration (
validRequester): each SP name must be provided along with an URL where responses for this SP should be sent. Note that this is somehow implicit authorization: actually everybody can pretend to be the trusted SP, but the response is always sent to a fixed address of a genuine trusted SP. If a better protection is required, then the
strictpolicy can be used: then all requests must be signed, and the trusted certificates are enumerated in configuration.
Reference documentation on all the options can be found in the Unity documentation.
The following is a recommended example of configuration from federation’s metadata:
unity.saml.issuerURI=https://unity.example.com/saml-idp/metadata unity.saml.credential=MAIN unity.saml.defaultGroup=/A unity.saml.acceptedSPMetadataSource.SOMEFEDERATION.url=https://federation.example.com/somefed/metadata
There is a couple of additional options for usage of a federation metadata (e.g. how often to refresh the metadata or what truststore should be used during retrieval of metadata). Nevertheless the above example is pretty often enough.
If a manual configuration of IdPs is needed the following example shows how to configure three trusted SPs:
unity.saml.issuerURI=https://unity.example.com/saml-idp/metadata unity.saml.credential=MAIN unity.saml.defaultGroup=/A unity.saml.spAcceptPolicy=validRequester unity.saml.acceptedSP.1.entity=https://shibboleth-sp.example.com/shibboleth unity.saml.acceptedSP.1.returnURL=https://shibboleth-sp.example.com/Shibboleth.sso/SAML2/POST unity.saml.acceptedSP.2.entity=https://simplesamlphp-sp.example.com:8080/\ simplesaml/module.php/saml/sp/metadata.php/default-sp unity.saml.acceptedSP.2.returnURL=https://simplesamlphp-sp.example.com:8080/\ simplesaml/module.php/saml/sp/saml2-acs.php/default-sp unity.saml.acceptedSP.3.entity=https://unity.example.com/unitygw/saml-sp-metadata/metadata1 unity.saml.acceptedSP.3.returnURL=https://unity.example.com/unitygw/spSAMLResponseConsumer
2.2. Step 2: Expose the SAML endpoint
To enable the endpoint its unique base path must be established. In the following example the
will be used for this purpose. What is more a Unity authentication realm must be chosen (or created), to which
the SAML endpoint will belong to. The authentication realm defines general security settings as
login session duration. As this is rather advanced topic we will use the default
authentication of the endpoint needs to be defined, by selecting authenticators which should be enabled.
The example configuration of an endpoint in the
unityServer.core.endpoints.2.endpointType=SAMLWebIdP unityServer.core.endpoints.2.endpointConfigurationFile=conf/endpoints/saml-webidp.properties unityServer.core.endpoints.2.contextPath=/saml-idp unityServer.core.endpoints.2.endpointName=UNITY SAML web authentication unityServer.core.endpoints.2.endpointRealm=defaultRealm unityServer.core.endpoints.2.endpointAuthenticators=pwdWeb1
We have assumed that the endpoint’s configuration created in the previous step is available in the
endpoints/saml-webidp.properties. The endpoint’s name is a simple string used in the UI presented to the
users being authenticated. Finally the endpoint will allow for authenticating with a single authenticator
The endpoint configured in such a way will be accessible with two URLs:
https://unity-server-public-address/saml-idp/metadata → Metadata of the SAML IdP
https://unity-server-public-address/saml-idp/saml2idp-web → URL which should be used by the SAML SPs to redirect the clients for authentication to.
2.3. Step 3: Configure a remote SAML SP to use Unity as IdP
To configure the Unity as IdP for a SP typically SAML metadata is needed or a list of parameters, including in the first place the IdP endpoint URL (see above) and its certificate (the one configured in the endpoint’s configuration).
Here we provide shortened information on Shibboleth SP and SimpleSAMLPhp settings.
2.3.1. Shibboleth SP
Shibboleth SP is configured using SAML metadata. You can configure Unity IdP in several ways: via the Shibboleth Discovery Service (together with many others IdPs), configure automatic Metadata download from Unity’s metadata URL or to download the Unity’s metadata manually and configure Shibboleth to use it.
For the last, simplest option store the metadata in a file (e.g.
/etc/shibboleth/metadata/unity-idp.xml) and inform Shibboleth about it by adding the following entry to the
<MetadataProvider type="XML" file="/etc/shibboleth/metadata/unity-idp.xml"/>
After enabling the SP functionality, add the following to the
$metadata['https://unity.example.com/saml-idp/metadata'] = array ( 'entityid' => 'https://unity.example.com/saml-idp/metadata', 'SingleSignOnService' => array ( 0 => array ( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 'Location' => 'https://unity.example.com/saml-idp/saml2idp-web', ), 1 => array ( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'Location' => 'https://unity.example.com/saml-idp/saml2idp-web', ), ), 'ArtifactResolutionService' => array ( ), 'keys' => array ( 0 => array ( 'encryption' => false, 'signing' => true, 'type' => 'X509Certificate', 'X509Certificate' => 'MIICizCCAfS ...the Base 64 encoded certificate of Unity IdP endpoint...', ), ), );
2.4. Who can authenticate with SAML?
The SAML requesters (SPs) who can query the SAML IdP endpoint in Unity are configured with the
unity.saml.spAcceptPolicy what was described above or are loaded from the federation’s metadata.
Also the user who is actually authenticating her- or himself must fulfill the following conditions:
Must be a member of a group configured for a SP. For instance a user who is not a member of the
/Agroup won’t be able to authenticate with SAML when using the example configuration above. Note that this is also true for users authenticating with remote IdP to Unity: then the translation profile must add the remotely authenticated user to the group used by SAML IdP endpoint.
Must have a sufficient Unity authorization role, i.e. at least the Regular User role. Users who have no Unity role defined or an Anonymous User role, won’t be able to be authenticated in the most of cases.
Must have a Unity identity which is being requested by the client. The most popular transient and persistent identity types are generated on the fly, but in case when a specific identity type is requested (e.g. X500 name) such identity must be defined for the user.
2.5. Advanced options
2.5.1. Filtering attributes
By default all attributes of an authenticated user, which:
are not marked as local in their attribute type definition (see Schema management→Attribute types) and
are defined in the group configured for the endpoint
The user is able to hide some of the attributes (for privacy reasons) when authenticating with SAML.
What is more it is possible to filter attributes on the endpoint level. It is done with ouput translation profiles. See their documentation for details. It is also possible to modify or even create attributes with them.
2.5.2. Custom SAML metadata
By default Unity endpoint will publish an automatically generated SAML metadata. It is possible to publish a custom
metadata document instead (use the
unity.saml.metadataSource property). What is more Unity can automatically sign
the Metadata, also the custom one (
2.5.3. Targeted identities and authentication realms
The most popular identity formats (i.e. the format in which authenticated principal name or pseudonym is provided to the SP) in SAML are:
transient format which should be different for each login session of a user
persistent formats which should be the same for each login session of a user
Both formats are targeted, i.e. each SP should get different values of identities in such formats, for privacy reasons. Also should not allow for being associated with the actual person.
Unity automatically generates and supports both formats. There is one fact to note about the relation of those identities to authentication realms: all endpoints in a single authentication realm will share the targets (i.e. the SPs). That is if we have two SAML endpoints E1 and E2 defined (even of different types: web and soap) in a single authentication realm and a SAML SP A will query the E1 first and then the E2, then the same identity will be returned by both endpoints. Contrary if E2 will be in another realm, then even the persistent identity for the same SP will be different then the one generated by the E1.
3. Using remote SAML IdPs for authentication
3.1. Step 1: Create a translation profile
Translation profile is used to convert and unify the information retrieved from the remote service (SAML IdP in our case) to a Unity representation. The profile should at least establish a Unity identity of the remotely authenticated principal and optionally can assign some attributes or groups. Translation profiles are configured in the Admin UI (Server management→Translation profiles) and are documented here.
If the mapped user is already present in the Unity database, then the authentication is successful. If the mapped user is not present:
It can be added automatically (using the mapped information), what is configured in the translation profile itself.
It can have a registration form presented to provide additional data about itself. The registration form can be prefilled with the information retrieved from the remote IdP.
It can be denied, what is the default behavior.
Creation of a translation profile is a complex task as is fully dependent on precise data provided by the remote IdP.
It is a good practice to create a simple (even empty) translation profile, perform all the subsequent SAML
integration tasks and then experiment. By setting the following logging level in the
<Logger name="unity.server.externaltranslation" level="DEBUG"/>
Unity will present a detailed information on what was received from the remote IdP and on all operations performed by the translation profile.
In the SAML case the identity is typically provided in one of 3 ways:
as a transient identifier: then some of the attributes (e.g. email) profile must be mapped to Unity identity, as the transient identifier is volatile and therefore not suitable as an identity
as a persistent identifier: it can be directly mapped to Unity identity, preferably it should be of
as an e-mail, X.500 DN or custom identifier: those can be mapped to Unity identity directly using any of the preferred identity types.
Below we present an example of translation profile, that maps
uid attribute to unity identity, maps one
cn as Unity’s
cn attribute (i.e. there is no attribute name change) in the / group
and finally the mapped user is create if doesn’t exist yet.
|Rule no||Condition||Action||Action arguments|
3.2. Step 2: Create SAML authenticator
The SAML authenticator configuration must be provided in a separate properties file. The configuration consists of two parts: common settings and definitions of all enabled SAML IdPs.
The common part should define at least:
SAML identity of the requester (
unity.saml.requester.requesterEntityId) is a unique name of Unity authenticator acting as SP in SAML domain (often called as a federation). You can choose any URI as a value, but it is suggested to use some URL related to Unity, preferably the URL of SAML metadata of the authenticator.
Metadata publication path (
unity.saml.requester.metadataPath) is a path under which metadata is published for the authenticator. As in Unity authenticators have no address, there is a special shared pseudo-endpoint available at the fixed location
/unitygwwhere cross-cutting functionality is exposed. The metadata will be published under the path
/unitygw/ saml-sp-metadata/NAME, where the NAME must be defined.
Displayed name (
unity.saml.requester.displayName) is used to distinguish the authenticator from others in the UI.
The rest of configuration is a list of the settings of the trusted IdPs. This can be performed in two ways: either a SAML metadata can be set or all the settings can be given manually. The configuration from metadata should be preferred as it is much simpler and allows for automatic updates whenever your federation changes. Manual configuration allows for a greater flexibility. Additionally you can mix both approaches: configure from metadata and override some selected settings with manual entries. In this case the entries are matched by the SAML id of the IdP (so called entity id in SAML slang).
When SAML authenticator’s configuration is ready (using one of the methods described in the following subsections),
the authenticator must be defined in the
unityServer.core.authenticators.7.authenticatorName=samlWeb unityServer.core.authenticators.7.authenticatorType=saml2 with web-saml2 unityServer.core.authenticators.7.verificatorConfigurationFile=conf/authenticators/remoteSamlAuth.properties
To enable it the server must be restarted, or authenticators must be reloaded in the Server management → Authenticators panel of the Admin UI.
3.3. The metadata way
Configure the metadata settings. Many metadata sources can be configured.
URL of metadata is the base option. Local or remote URL can be set. It can be a URL to metadata of a federation or a single IdP.
Validation settings can be used to turn on additional signature verification of the metadata. This is useful when metadata is downloaded over the network.
Refresh interval can be used to control how often the metadata should be reloaded.
Unity specific settings translation profile and optionally the registration form for unknown users are never provided in SAML metadata. If a common registration form/translation profile is valid for all IdPs from the metadata then it should be also set. Otherwise at least the translation profile should be set manually per each trusted IdP.
The following example configures all the IdPs from a remote location with standard settings:
3.4. The manual way
Configure the following settings per trusted IdP:
Displayed name of a SP (
unity.saml.requester.remoteIdp.X.name) is used in the authentication UI.
Address of a SP (
unity.saml.requester.remoteIdp.X.address) the remote IdP endpoint’s URL
SAML Identifier of the IdP (
Certificate of the IdP (
unity.saml.requester.remoteIdp.X.certificate) is used to verify the signature of the response. Only the name is configured, the actual certificate must be defined in the
Requested identity format (
unity.saml.requester.remoteIdp.X.requestedNameFormat) if the format which should be requested for the IdP. It is especially important when SAML identity is mapped to Unity identity directly.
Translation profile (
unity.saml.requester.remoteIdp.X.translationProfile), which is used to translate received information to Unity’s representation, as described in the preceding section.
The following example defines three remote IdPs:
unity.saml.requester.requesterEntityId=https://unity.example.com/unitygw/saml-sp-metadata/metadata1 unity.saml.requester.metadataPath=metadata1 unity.saml.requester.displayName=Remote SAML authentication unity.saml.requester.remoteIdp.1.name=Simple SAMLPHP based IdP unity.saml.requester.remoteIdp.1.address=https://simplesamlphp-idp.example.com:8080/\ simplesaml/saml2/idp/SSOService.php unity.saml.requester.remoteIdp.1.samlId=https://simplesamlphp-idp.example.com:8080/\ simplesaml/saml2/idp/metadata.php unity.saml.requester.remoteIdp.1.certificate=SIMPLESAMLPHP1 unity.saml.requester.remoteIdp.1.groupMembershipAttribute=urn:oid:18.104.22.168.4.1.5922.214.171.124.1 unity.saml.requester.remoteIdp.1.requestedNameFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient unity.saml.requester.remoteIdp.1.translationProfile=samlProfile unity.saml.requester.remoteIdp.2.name=Shibboleth IdP unity.saml.requester.remoteIdp.2.address=https://shibboleth-idp.example.com:8080/\ idp/profile/SAML2/Redirect/SSO unity.saml.requester.remoteIdp.2.samlId=https://shibboleth-idp.example.com:8080/idp/shibboleth unity.saml.requester.remoteIdp.2.certificate=SHIB_IDP unity.saml.requester.remoteIdp.2.requestedNameFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient unity.saml.requester.remoteIdp.2.translationProfile=samlProfile unity.saml.requester.remoteIdp.3.name=Unity IdP unity.saml.requester.remoteIdp.3.address=https://unity.example.com/saml-idp/saml2idp-web unity.saml.requester.remoteIdp.3.samlId=https://unity.example.com/saml-idp/metadata unity.saml.requester.remoteIdp.3.certificate=MAIN unity.saml.requester.remoteIdp.3.requestedNameFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient unity.saml.requester.remoteIdp.3.translationProfile=samlProfile
The detailed reference of all possible options is given in the Unity documentation.
3.5. Step 3: Bind SAML authenticator to an endpoint
To bind the SAML authenticator to an endpoint, its name must be added to its authenticators list. For instance
the following configuration will allow for authenticating to the endpoint either with the above defined SAML
authenticator or with
The same authenticator can be added to several endpoints.
To apply the authenticators change, the server must be restarted, or the changed endpoint must be reloaded in the Server management → Endpoints panel of the Admin UI.
3.6. Step 4: Configure a remote SAML IdP to accept Unity acting as SP
This part is highly IdP specific. Some of the IdPs require to have the SAML metadata of the Unity SP provided. Other will require to provide its SAML name and response return URL, which is https://unity.example.com/unitygw/spSAMLResponseConsumer (for all SAML authenticators).
As an example configuration of Shibboleth IdP and SimpleSAMLPhp is presented below.
3.6.1. Shibboleth IdP
Shibboleth IdP is configured using SAML metadata. You can authorize Unity SP by configuring automatic Metadata download from Unity’s metadata URL or by downloading the Unity’s metadata manually and configuring Shibboleth to use it.
For the latter, simplest option store the metadata in a file (e.g.
SHIB_INSTALL/metadata/unity-sp.xml) and inform Shibboleth about it by adding the following entry to the
<MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" id="UnityMetadata" metadataFile="SHIB_INSTALL/metadata/unity-sp.xml" />
<metadata:MetadataProvider id="ShibbolethMetadata" xsi:type="metadata:ChainingMetadataProvider"> element.
The simplest way to allow Unity to query SimpleSAMLPhp is to add the following snippet to the
$metadata['https://unity.example.com/unitygw/saml-sp-metadata/metadata1'] = array ( 'AssertionConsumerService' => array ( 0 => array ( 'index' => 0, 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 'Location' => 'https://unity.example.com/unitygw/spSAMLResponseConsumer', ), ), );
Of course IdP functionality must be enabled in SimpleSAMLPhp.
4. Using Single Logout (SLO)
Since version 1.4.0 Unity does support SAML Single Logout protocol. The protocol implementation is mostly complete. That is Unity is able to:
Log out all SAML session participants supporting SLO, regardless whether they are SPs or upstream IdPs, using any of the SOAP, HTTP Redirect and HTTP POST bindings.
Initiate the logout process by receiving a logout request for the SP address (i.e. for Unity’s remote SAML authenticator), IdP address and directly by logging out in any of the Unity’s own UI.
Note however, that SLO is a terribly complicated and problematic protocol. Be aware about some of the most important issues:
When logging out session participants with asynchronous bindings (i.e. with web browser redirects) it may happen that one peer is misbehaving, what will break the logout process, probably leaving user’s browser in a strange state.
Many SAML implementations either do not support SLO fully (if at all) - Shibboleth IdP being a notable example - or their installations are not configured to support SLO.
Unity is not presenting an information whether the logout process was performed partially or fully. As a rule of thumb it can be assumed that logout was partial only. Therefore the feature should be considered as the best effort only.
Some SAML implementations implement logout over SOAP in simplified way, so that the SOAP logout is not fully functional. Unity fully supports SOAP logout, and from Unity perspective this is by far the safest bet, however sadly not fully interoperable with 3rd party implementations.
The fundamental option related to SLO is located in the main config file
It can take three values:
internalAndAsyncPeers. The first one turns off
logout of external peers. That is, remote peers still can request logout from Unity, but Unity won’t
propagate it to further session participants. The second one performs a safe, synchronous logout of those session peers
which support SOAP logout binding. The final one offers the largest interoperability at the same time being the most
risky as during the logout the user’s browser can be even multiple times redirected to other session participants,
with assumption that those participants will redirect the browser back.
To configure Single Logout and to discover all the settings of Unity SLO endpoints the easiest method is to use SAML metadata. Unity’s metadata of both IdP and SP provide all necessary information. The manual configuration of trusted peers addresses is also possible, see the reference documentation table of respective SAML configuration file.
In the case of authenticator (SAML SP) the will be enabled only if two simple properties are defined:
Those settings define the key part of all the SLO endpoints for the authenticator (to distinguish them from SLO endpoints of other possible authenticators configured) and binds the authenticator to a concrete realm. This last settings is necessary as logout is destroying a session which is realm scoped.
Example manual (i.e. not taken from federation metadata) configuration of SLO paths for trusted SP (in IdP endpoint configuration):
unity.saml.acceptedSP.4.redirectLogoutEndpoint=https://example.com/Shibboleth.sso/SLO/Redirect unity.saml.acceptedSP.4.postLogoutEndpoint=https://example.com/Shibboleth.sso/SLO/POST unity.saml.acceptedSP.4.soapLogoutEndpoint=https://example.com/Shibboleth.sso/SLO/SOAP
The same for a trusted IdP (in authenticator configuration):
unity.saml.requester.remoteIdp.EX.redirectLogoutEndpoint=https://example.com/idp/profile/SAML2/Redirect/SLO unity.saml.requester.remoteIdp.EX.postLogoutEndpoint=https://example.com/idp/profile/SAML2/POST/SLO unity.saml.requester.remoteIdp.EX.soapLogoutEndpoint=https://example.com/idp/profile/SAML2/SOAP/SLO