SAML User Adapter

Using Security Assertion Markup Language (SAML), a user can use their managed account credentials to sign into Jadu websites via Single Sign-On (SSO). An Identity Provider (IdP) service provides administrators with a single place to manage all users and cloud applications.

Jadu support a number of popular IdPs such as:

• Azure AD
• OneLogin
• Shibboleth

You don't have to manage individual user IDs and passwords tied to individual websites for each of your users. An IdP service provides your users with a unified sign-on across all their interfaces. Users log in once and get one-click access to all the private resources.

note

To use SAML authentication successfully, your site must use HTTPS protocol, and the PHP extension openssl must be enabled on your webserver.

Navigating to the SAML User Adapter Integration area

1. Click the Settings icon in the left navigation bar. The Settings menu will open.
2. Click the Integrations link in the first group of links. A list of integrations will now be shown.
3. Click the SAML User Adapter Integration option in the list of integrations. The SAML User Adapter Integration integration form will open.

Configuration

1. Before you start, find the URL or a copy of the identity provider metadata XML file, and note the following values you will need to complete the configuration of the adapter. An example metadata extract is shown below for context.

Value	Element	Attribute
Entity ID	EntityDescriptor	entityID
Single sign on URL	SingleSignOnService	Location
X509 Cert	X509Certificate

2. Navigate to the SAML User Adapter Integration area.
3. Click the Identity Provider tab, and the Identity Provider form will open.
4. Enter the "Entity ID" value into the Entity ID field.
5. Enter the "Single sign on URL" value into the Single Sign-On URL field. Note: only the HTTP-Redirect binding type is currently supported.
6. Enter the "X509 Cert" value into the X509 Cert field.
7. Click the Matching Attribute tab, and enter the SAML attribute that holds the email address for the user in the User Email Attribute field.
8. These are the minimum fields required to enable the adapter, but you should review the Security and Matching Attributes tabs before proceeding. You may also want to configure single log out functionality at this point.
9. Click the Save button to save your configuration.
10. Generate the Jadu Central metadata and share this with your identity provider. The metadata is available at https://{{ domain }}/saml/metadata, and can be shared via URL or by downloading and sharing the XML. A link to the metadata appears at the top of the SAML User Adapter Integration area. See Sharing Service Provider Metadata for further details.
11. Navigate back to Jadu Central and toggle Enable SAML User Adapter in the General tab.

note

We recommend enabling the Debug option and disabling the Strict option when first enabling the integration, and then checking for any logged errors after checking the integration is functional.

Once your initial checks have pass, we recommend enabling the Strict option and performing further testing.

The Debug option should be disabled once everything is confirmed to be working.

Configuration of single logout

Single Logout configuration depends on the configuration of your Identity provider.

Supported functionality	Configuration instructions
Single logout flow is supported	Enable Single Logout and enter the logout url in the Single Logout URL field. The URL for Logout endpoint is usually found in the SingleLogoutService tag. Note: Only the HTTP-Redirect binding type is currently supported. You can set a second page for the user to be redirect to after successfully logging out by setting the value of After Logout Redirect.
Single logout flow is not supported but the Identity provider does support a URL entry point that disconnects the user session	Uncheck the Single Logout field and add the URL endpoint to Single Logout URL. This will configure the user adapter to delete the local session first, then redirect to the URL endpoint.
Single logout flow is not supported and logout URL is not supported	Leave the Single Logout fields empty. The session will only be ended on the Service Provider side.

Configuration of user attributes

The integration provides functionality so that you can map the available attributes sent by the Identity provider to the properties on the application user.

1. Navigate to the SAML User Adapter Integration area.
2. Click the Matching Attributes tab, and the Matching Attribute form will open.
3. Enter the SAML attribute that holds the email address for the user in the User Email Attribute field.
4. If your identity provider sets a transient NameId then you should enter a persistant user identifier attribute in the User Identifier Attribute field.
5. You can map SAML attributes to the local user record so that personal detail fields are prefilled when the user completes a form on the website. For each field to be mapped, select the Jadu field using the select box, and enter the associated SAML attribute in the SAML Identifier Attribute Name field. Click the Add another field button to add another mapping to the list.
6. Click the Save button to save your changes.

Available user attributes

The following additional fields are available to map to SAML attributes:

• email
• salutation
• forename
• surname
• birthday
• age
• sex
• occupation
• company
• address
• city
• county
• postcode
• country
• telephone
• mobile
• fax
• website

If you want to map fields that aren’t standard JaduUsers fields (like for example College Id, Class Id, etc) we recommend mapping them to existing but unused fields, like for example ‘website’.

Finding SAML user attributes

The attributes used are different for every provider and your Identity Provider administrator should be able to provide those relevant to your implementation.

If these are unavailable, another option is to:

1. Navigate to the SAML User Adapter Integration area.
2. On the General tab, enable Enable SAML User Adapter and Debug fields.
3. Attempt to login to your site using your SAML user credentials.
4. Login to your server, and view the log files. The log files should contain a login failure entry which will detail all received attributes.
5. Return to the SAML User Adapter Integration area, open the Matching attributes section, and configure the user attributes based on the log file data.

Example IdP metadata

<md:EntityDescriptor entityID="https://idp.example.com/idp/shibboleth"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:shibmd="urn:mace:shibboleth:metadata:1.0"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
    <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:SingleSignOnService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
            Location="https://idp.example.com/idp/profile/SAML2/Redirect/SSO"/>
    </md:IDPSSODescriptor>
    <md:ContactPerson contactType="technical">
        <md:EmailAddress>mailto:technical.contact@example.com</md:EmailAddress>
    </md:ContactPerson>
</md:EntityDescriptor>

Debug mode

When the debug option is enabled, all actions, errors, and available user attributes will be logged.

This option is very useful for diagnosing issues when initially setting up the adapter, however should be disabled on production environments due to the possibility of sensitive data being recorded.

The log files are available at:

<JADU_PATH>/logs/samlAuthenticationAdapter/YYYY/MM/DD.log

Example of logs received for an authentication request:

[2019-07-03 15:00:40] samlAuthenticationAdapter.DEBUG: Received auth attributes 
{"attributes":{"urn:oid:0.9.2342.19200300.100.1.1":["johnd"],"urn:oid:0.9.2342.19200300.
100.1.3":["johnd@local.box"],"urn:oid:1.3.6.1.4.1.5923.1.1.1.9":["member"],"urn:oid:2.5.
4.42":["John"],"urn:oid:2.5.4.4":["Doe"]}} []

Example of an invalid mapping for email attribute:

[2019-07-03 15:00:40] samlAuthenticationAdapter.ERROR: Could not get value from user 
email attribute {"attributes":{"urn:oid:0.9.2342.19200300.100.1.1":["johnd"],"urn:oid:0.
9.2342.19200300.100.1.3":["johnd@local.box"],"urn:oid:1.3.6.1.4.1.5923.1.1.1.9":
["member"],"urn:oid:2.5.4.42":["John"],"urn:oid:2.5.4.4":["Doe"]}} []

From these log messages, we can see the names and values of the available SAML attributes, and therefore use these to correctly configure the settings on the Matching Attributes tab.

Sharing Service Provider Metadata

After the integration was successfully configured, the Service Provider metadata will usually need to be shared with the Identity Provider.

The metadata is available at https://{{ domain }}/saml/metadata (linked to at the top of the Integrations Hub page), and can be shared via URL or by downloading and sharing the XML.

If the Identity Provider doesn’t have direct access to metadata url (for example, if you are using an internal development server) we recommend downloading and modifying the XML metadata, removing the validUntil and cacheDuration from the EntityDescription attribute (see example below).

Before:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2019-08-03T14:08:42Z" cacheDuration="PT604800S" entityID="https://<url>/saml/metadata">

After:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://<url>/saml/metadata">

General fields

Field	Notes	Required?
Enable SAML User Adapter	Enable or disable the integration. If disabled, the system will use the default Jadu authentication. If enabled this will override the application's USER_ADAPTER configuration value. If disabled again, the constant will revert to the default Jadu authentication rather than any previous setting. Note: it will only be possible to enable the adapter once valid settings have been entered.
Strict	When this is enabled, more extensive validation will be performed on the responses received from the Identity Provider. This is recommended for production environments as it offers a higher level of security. We recommend first configuring the adapter without it enabled, and testing the sign in process (and sign out where supported), as this will narrow down the possible settings which may need to be corrected in the case of any issues. It should then be enabled, and further testing carried out. When this setting is enabled, settings within the Security tab can be used to control some of the additional checks that are carried out.
Debug	Enable debug mode to print errors out to a file system based log file. The log file(s) are located within the Jadu install directory, at logs/samlAuthenticationAdapter/YYYY/MM/DD.log where YYYY/MM/DD is the date the log was written to

Service Provider fields

Field	Notes	Required?
NameID Format	The constraint used to represent the name identifier. The suggested default value is unspecified which acts as a wildcard, and the NameId can be set based on the received assertions list. This can be changed if the Identity Provider expects a specific format and the value will be shown in the IDP metadata file under * `md:NameIDFormat*
X509Cert	X509Cert used by the Service Provider. Used for signing and encrypting the SAML Assertions, this requires a 2048 bit unencrypted RSA private key and the corresponding x509 certificate to be provided.
Private key	The private key used by the Service Provider. Used for signing and encrypting the SAML Assertions, this requires a 2048 bit unencrypted RSA private key and the corresponding x509 certificate to be provided.
Entity Id	Optionally specify a custom value for EntityId. By default this will be set to the metadata URL. Some IDPs require this to be overridden with a specific value, which can be entered here.

Identity Provider fields

Field	Notes	Required?
Entity ID	The Entity ID field is a mandatory field and is the URL that will be the unique identifier for the Identity Provider application and is information that is provided by your IDP. This is usually found in the EntityDescriptor tag of the metadata.	✅
Single Sign-On URL	The Single SignOn URL is a mandatory field that represents the URL to send the initial authentication request to. This is usually found in the SingleSignOnService tag, only the HTTP-Redirect binding tag is currently supported.	✅
Single Logout	If enabled, the system will follow the Identity Provider SLS flow for logout and then delete the local session. Not all Identity Providers support this endpoint and therefore is an optional setting. If disabled, upon log out, the user will be disconnected from the local session but will still remain logged in on the Identity Provider side.
Single Logout URL	The target of the Identity Provider where the SLO request will be sent. If the Identity Provider SLS flow is disabled and you add a logout URL then the system will delete the local session and redirect to the target URL.
After Logout Redirect	If a URL is provided the system will redirect to this URL after successful logout. This can be used to redirect the user to a homepage with a custom message.
Update Password URL	Update Password URL is an optional field. If set, any “change password” links within the application will direct the user to the provided URL.
Account URL	Account URL is an optional field. If set, any “change details” links within the application will direct the user to the provided URL.
Register URL	Register URL is an optional field. If set any “register” links within the application will direct the user to the provided URL.
X509 Cert	X509 Cert is a mandatory field which holds the Identity Provider’s X509Cert. It is usually found in X509Certificate tag.	✅

Security fields

Security configuration is split into two sections: Outgoing signatures and encryption, which configures how the user adapter sends requests to the Identity Provider, Incoming signatures and encryption, which configures what the user adapter expects from the Identity Provider, and Authentication, which allows configuration of allowed authentication methods.

Field	Notes	Required?
Name Id Encrypted	Indicates if the IDP expects the name id in the logout request to be encrypted. We recommend this feature to be disabled under testing, and enabling it after successful login/logout flow in order to eliminate any misconfiguration by this field.
Authn Requests Signed	Indicates whether the samlp:AuthnRequest messages sent by this Service Provider should be signed. We recommend this field to be enabled, however some Identity Providers do not support this feature.
Logout Response Signed	Indicates whether the samlp:logoutResponse message sent by this Service Provider should be signed. We recommend this feature to be disabled under testing, and then enabled after successful login/logout flow in order to eliminate any misconfiguration by this field.
Logout Requests Signed	Indicates whether the samlp:logoutRequest message sent by this Service Provider should be signed. We recommend this feature to be disabled under testing, and then enabled after successful login/logout flow in order to eliminate any misconfiguration by this field.
Require Password based Auth	Enabling this will tell the IDP that the user must be authenticated via a password, rather than another method that the IDP supports (e.g one time code, etc). Disabling this will send the required authentication method as “unspecified”, meaning that the IdP is free to use any method for authentication.
Require Signed Messages	If enabled, the user adapter will check that all message tags in the SAML response are signed. If they are not, the user will not be signed in. If Debug is enabled, an error will be logged. This setting only has an effect when the Strict option is enabled in the General tab.
Require Encrypted Assertions	If enabled, the user adapter will check that all assertions are encrypted. If they are not, the user will not be signed in. If debug is enabled, an error will be logged. When this setting is enabled, the SP metadata file will contain the X509Cert used for the encryption process.
Require Signed Assertions	If enabled, the user adapter will check that all assertion tags are signed. If they are not, the user will not be signed in. If Debug is enabled, an error will be logged. When this setting is enabled, the SP metadata file will include the property WantAssertionsSigned="true" for the md:SPSSODescriptor tag.
Require encrypted nameid	If enabled, the user adapter will check that the NameId value is encrypted in the SAML Response. If the value is not encrypted, the user will not be signed in. If Debug is enabled, an error will be logged. This setting only has an effect when the Strict option is enabled in the General tab, if Strict mode is disabled the destination will never be validated.
XML Validation	If enabled, the user adapter will validate the XML sent by the IDP. This setting only has an effect when the Strict option is enabled in the General tab.
Relaxed Destination Validation	If enabled, the user adapter will not validate the destination attribute in the Response sent by the Identity Provider. This setting only has an effect when the Strict option is enabled in the General tab, if Strict mode is disabled the destination will never be validated.
Sign Service Provider Metadata	Indicates whether the Service Provider should sign the metadata (ds:SignedInfo).
Lowecase Url Encoding	ADFS URL-Encodes SAML data as lowercase. By default the integration uses uppercase. Enable this setting for ADFS compatibillity on signature verification.
Signature Algorithm	The signature algorithm that is used for the signing process. Defaults to rsa-sha256, but can be changed if the Identity Provider expects a different algorithm. Note: rsa-sha1 should be avoided as it is no longer considered secure
Digest Algorithm	Digest Algorithm algorithm used for the digest process. Defaults to sha256, but can be changed if the Identity Provider expects a different algorithm Note: sha1 should be avoided as it is no longer considered secure.

Matching Attributes fields

Field	Notes	Required?
User Email Attribute	The SAML attribute which holds the email address for the user. A mandatory field for mapping to a Jadu User record.	✅
Use email address as user identifier	If enabled, the same attribute will be used to supply the value for the JaduUser externalID value, as the email address. In new implementations, it is unlikely that this will be desirable, however the setting was added for backwards compatibility with existing implementations.
User Identifier Attribute	The SAML attribute which holds the unique user identifier for the user. If left empty, the value of the NameId element in the SAML response will be used. If your IdP sets a transient NameId then a specific attribute should be specified otherwise users will lose access to their data on subsequent logins.
External ID prefix	Prefix external user ID with this value
User attributes	This field is used for better integration when replacing previous custom user adapters. If a previous custom adapter used a customized external id prefix, then use this field to match the prefix. If left empty, no prefix will be used.

Troubleshooting

Setting up single sign on can sometimes require troubleshooting to match service provider and identity provider configuration. In our troubleshooting guide we document common errors returned by the SAML integration, and how to go about resolving them.

See our troubleshooting guide.