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 platform 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 it’s enabled, users who visit your UKG HR Service Delivery instance and attempt to log in are redirected to your SAML server for authentication. Users’ identities can be stored either on the SAML server or 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

By default, the SP-Initiated SSO: Redirect-POST method is used (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 containing an authentication request to the Identity Provider (IdP). The IdP returns a SAML response with a SAML assertion to the SP via HTTP POST:

1. 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.
2. UKG HR Service Delivery returns an HTTP redirect (code 302 or 303) containing a SAML request for authentication via the user's browser to your IdP’s SSO service. If the user isn’t already logged in at the IdP site—or re-authentication is required—the IdP asks for credentials (e.g., ID and password) and the user logs on.
3. The 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 form back to UKG HR Service Delivery.
4. Additional user information may be retrieved from the user data store for inclusion in the SAML response (optional).
5. 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 provisioning with a SAML Token

To enable SAML connection for UKG HR Service Delivery users, you need to declare the SAML identifier of each user during provisioning: include an additional saml_token column at the end of the imported CSV file. This token is the user identifier returned during the authentication phase in the SAML assertion. Refer to User profile synchronization for complete documentation and examples.

Employee provisioning with a SAML Token

Similarly, to enable SAML login for employees, include the saml_token column at the end of the employee CSV file. This token must match the user identifier returned during authentication in the SAML assertion. See Employee synchronization for full details and examples.

Example SAML Assertion (simplified)

The SAML assertion returned by your IdP should include the user's identifier in the saml:Subject > saml:NameID element—this is what you add to the saml_token column in your 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 can either build a SAML server in-house (e.g., OpenAM) or choose an online SAML service. To configure SAML in UKG HR Service Delivery:

1. Send your SAML IdP metadata file to your UKG HR Service Delivery Implementation Manager. This XML file should include:

• The Remote Login URL (sometimes called the SAML Single Sign-On URL) to redirect users to the IdP.
• The Remote Logout URL, where UKG HR Service Delivery directs users upon logout.
• The SAML certificate used to sign the SAML Response sent to UKG HR Service Delivery.

2. Your Implementation Manager will return UKG’s SAML SP metadata file, including:

• Your Access Consumer Service (ACS) URL (where the IdP logs users into UKG HR Service Delivery).
• The certificate used by UKG to sign SAML Requests sent to your IdP.

Notes:

• The default method is SP-Initiated SSO: Redirect-POST with HTTP GET redirects to the SAML URL.
• IdP-Initiated SSO is supported but may require additional configuration.