SAML Admin Adapter

Using Security Assertion Markup Language (SAML), an administrator can use their managed account credentials to sign into the Jadu Central Control Center 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

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 Admin Adapter Integration area

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

Configuration

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`

Navigate to the SAML Admin Adapter Integration area.
Click the Identity Provider tab, and the Identity Provider form will open.
Enter the "Entity ID" value into the Entity ID field.
Enter the "Single sign on URL" value into the Single Sign-On URL field. Note: only the HTTP-Redirect binding type is currently supported.
Enter the "X509 Cert" value into the X509 Cert field.
Click the Matching Attribute tab, and enter the SAML attribute that holds the email address for the admin in the User Email Attribute field.
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.
Click the Save button to save your configuration.
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 Admin Adapter Integration area. See Sharing Service Provider Metadata for further details.
Navigate back to Jadu Central and toggle Enable SAML Authentication 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 admin 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 admin session	Uncheck the Single Logout field and add the URL endpoint to Single Logout URL. This will configure the admin 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.

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.

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 Admin Adapter	Enable or disable the integration. 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 admin 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 admin 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 admin 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 admin adapter will check that all message tags in the SAML response are signed. If they are not, the admin 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 admin adapter will check that all assertions are encrypted. If they are not, the admin 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 admin adapter will check that all assertion tags are signed. If they are not, the admin 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 admin adapter will check that the `NameId` value is encrypted in the SAML Response. If the value is not encrypted, the admin 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 admin 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 admin 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 admin.	✅
Use email address as user identifier	If enabled, the same attribute will be used to supply the value for the JaduAdministrators `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 admin. 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.
External ID prefix	Prefix external user ID with this value. 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.
User attributes	Mapped attributes to apply to the administrator's record from the SAML identity provider.

Creating a SAML authenticated admin

Once the SAML integration has been enabled, you can add SAML accounts as admins for Jadu Central. To do this, try the following:

Click the Utilities icon in the left navigation bar. The Utilities menu will open.
Click the Admin Privileges link in the third group of links. A list of admins will now be shown, with links to create new admins if your account has the appropriate access permissions.
Click the New Admin button. The admin entry form will open. Complete the form to create a profile for your administrator and save the record.
Locate the new admin in the adminstrators list and open the record. Click the Link External Account button. The Link to External Account window will open.
Select SAML as the identity provider to link to. Enter the SAML ID in the field and click the Mark as SAML Account button.
Click the Save button to save the changes.

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.

Navigating to the SAML Admin Adapter Integration area​

Configuration​

Configuration of single logout​

Example IdP metadata​

Debug mode​

Sharing Service Provider Metadata​

General fields​

Service Provider fields​

Identity Provider fields​

Security fields​

Matching Attributes fields​

Creating a SAML authenticated admin​

Troubleshooting​