Single sign-on with SAMLv2¶

Introduction¶

UKG HR Service Delivery supports Secure Assertion Markup Language (SAML) 2.0, which allows you to provide single sign-on (SSO) for your UKG HR Service Delivery instance using enterprise identity providers such as Active Directory and LDAP.

Implementing single sign-on via SAML means that the log in process and user authentication are handled entirely outside of UKG HR Service Delivery. Your users do not log in through the Document Manager or People Assist default login form. Instead users log in to the corporate system (authenticated by Active Directory or LDAP for example) and click a link to access a module of the UKG HR Service Delivery plateform and are automatically logged in.

You can build a SAML server in-house (using OpenAM, for example) or choose an online SAML service. You’ll need to set these up yourself outside of UKG HR Service Delivery.

SAML SSO can be used:

To log in enterprise users to the Document Manager or People Assist modules
To log in employees to their People Assist Web portal

How it works¶

SAML for UKG HR Service Delivery works the way SAML does with all other service providers.

After we’ve enabled SAML, users who visit your UKG HR Service Delivery instance and attempt to log in are redirected to your SAML server for authentication. Your users’ identities can be stored either on the SAML server or can be validated by an identity directory such as Microsoft Active Directory or LDAP. Once authenticated, users are redirected back to your instance and automatically logged in.

SP-Initiated SSO–Redirect-POST¶

We use by default the SP-Initiated SSO: Redirect-POST method (redirects to your SAML Single Sign-on URL are HTTP GET)

In this scenario, the UKG HR Service Delivery module (the Service Provider) sends an HTTP redirect message to the IdP containing an authentication request. Your IdP returns a SAML response with an SAML assertion to the SP via HTTP POST:

../_images/saml_sso_sp_initiated_redirect_post.jpg

A user requests access to a protected resource on UKG HR Service Delivery. The user is not logged on to the site. The request is redirected to the federation server to handle authentication.
UKG HR Service Delivery returns an HTTP redirect (code 302 or 303) containing a SAML request for authentication through the user’s browser to your IdP’s SSO service. If the user is not already logged on your IdP site or if re-authentication is required, your IdP asks for credentials (for example ID and password) and the user logs on.
Your IdP’s SSO service returns an HTML form to the browser with a SAML response containing the authentication assertion and any additional attributes. The browser automatically posts the HTML form back to UKG HR Service Delivery.
Additional information about the user may be retrieved from the user data store for inclusion in the SAML response (optional)
(Not shown) If the signature and assertion are valid, UKG HR Service Delivery establishes a session for the user and redirects the browser to the target resource.

Note

SAML specifications require that POST responses be digitally signed.

Configuring your SAML implementation¶

User provisionning with a SAML Token¶

To enable the connection of UKG HR Service Delivery users though SAML, you need to declare the SAML identifier of each of your user during the provisionning: a additionnal column need to be included at the end of the imported CSV file: saml_token. This token is the user identifier returned during the authentication phase in the SAML assertion.

See User profile synchronization for the complete documentation and examples.

Employee provisionning with a SAML Token¶

If you need to enable SAML login for your employees, you need to declare the SAML identifier or each of your employees during the provisionning: a additionnal column need to be included at the end of CSV file: saml_token. This token is the user identifier returned during the authentication phase in the SAML assertion.

See Employee synchronization for the complete documentation and examples.

Example SAML Assertion (simplified)¶

The SAML assertion returned by your IdP should include the identifier of the user in the saml:Subject > saml:NameID element. This is the identifier that you need to add to the saml_token column in the CSV files.

<saml:Assertion>
        ...
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                ...
        </ds:Signature>
        <saml:Subject>
                <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
                        your-user-id
                </saml:NameID>
        </saml:Subject>
        ...
</saml:Assertion>

Identity Provider setup¶

You have a number of options when considering a SAML service, including building a SAML server in-house (for example, OpenAM) or choosing an online SAML service.

To set up SAML in UKG HR Service Delivery, you need to send your SAML IdP metadata file to your UKG HR Service Delivery Implementation Manager. This XML file contains all the required information to configure our service, including:

The Remote Login URL for your SAML server (sometimes called SAML Single Sign-on URL, the URL that UKG HR Service Delivery invokes to redirect your users to your Identity Provider)
The Remote Logout URL (the URL that UKG HR Service Delivery redirects your users to after they log out)
The SAML certificate used to sign the SAML Response sent to UKG HR Service Delivery

To complete your SAML IdP configuration, your UKG HR Service Delivery Implementation Manager then sends you our own SAML SP metadata file. This XML file includes:

Your Access Consumer Service (ACS) URL: the url used by your IdP to log users into UKG HR Service Delivery.
Our certificate used to sign SAML Requests sent to your IdP

Notes:

We use by default the SP-Initiated SSO: Redirect-POST method (redirects to your SAML Single Sign-on URL are HTTP GET)
We support IdP-Initiated SSO, but it may require additional configuration