SSO API for UKG HR Service Delivery modules

Warning

If possible, you should now consider using the SAMLv2 SSO method. See Single sign-on with SAMLv2

General Description

This API provides a means of logging onto Document Manager modules (not People Assist modules) without needing to enter login information (e-mail / password). It allows for two types of access:

  1. Manager access : HR managers who possess a user account on UKG HR Service Delivery may automatically logon without entering their login e-mail and password.

  2. Restricted employee access: employees may logon to a restricted area in UKG HR Service Delivery to view the content of their employee folder (without being able to access other employee folders)

Warning

The employee space accessed by the employee to visualise his employee folder is different than his private safe

Whatever the access type, the authentication is performed thanks to a specific URL generated by the main information system (HRIS). In simplified terms, this URL, which is valid for a limited time, contains:

  • an account identifier (the account for which the connection is made)

  • redirection URL once the connection is made

  • a hash generated from a secret key shared between the main IS and UKG HR Service Delivery

Constructing the SSO URL

This URL must be constructed by the main application (the HRIS).

Note

This URL is only valid for a limmited amount of time, we do not advise to display the link from the server to the client web page, as it could expire. Instead you should do the following:

  • Show an internal URL in your application targeting a dedicated proxy method

  • When the user clicks on this internal url, and only then, your application generates and sign the SSO URL

  • and do an HTTP redirect (302 REDIRECT) to the generated URL

URL

GET /remote/access/

GET parameters

  • external_id:

    “External” user identifier (employee or manager according to the SSO access type). In this parameter, fill in the technical_id of the user to logon. The update files state:

  • timestamp:

    Message generation date, in unix timestamp format (valid for 5 minutes)

  • hash:

    Signature of the parameters [external_id, timestamp] using the secret key shared between UKG HR Service Delivery and the main IS. This security parameter is therefore used to ensure that the request originates from an authorized application (since it possesses the secret key). When UKG HR Service Delivery receives the request, this hash is recalculated locally and compared against that received. See the following paragraph for the generation of this parameter.

  • next:

    The user is redirected to this URL after authentication is performed. The next parameter must be encoded in HTML (urlencode). Note: this field is not taken into consideration in the signature.

Note

It is possible to indicate a “shortened” URL in the next parameter. The “shortened” URL is used simply to redirect the user to internal UKG HR Service Delivery pages. To see the list of existing shortcuts, see Document Manager API shortcuts

Signature of the request: the hash parameter

The application must sign each SSO URL using a shared secret key. This key is generated during setup of UKG HR Service Delivery and must be stored by the main application. The signature is included in each call in the hash parameter.

The format of this signature is as follows:

HMAC->SHA1(secret_key, external_id+secret_key+timestamp)

Example in Python:

import hmac
import hashlib
import time

SECRET_KEY = 'mysecretkey'
# techid
tech_id = request.GET['techid']

timestamp = time.time()
data = u'%s%s%s' % (tech_id, SECRET_KEY, timestamp)
built_hash = hmac.new(secret.encode('ascii'), msg=data.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()

Example in PHP:

<?php
define('SECRET_KEY', 'mysecretkey');
$techid = $_GET["techid"]
$timestamp = time();
$data = $techid.SECRET_KEY.$timestamp;
$hmac = hash_hmac('sha1', "$data", SECRET_KEY);
?>

Response

Success:

  • 302: Redirection to the employee or HR manager homepage if the next point is not filled in

Errors:

  • 400 Bad Request: Invalid parameters (missing or malformed parameter)

  • 403 Forbidden: Access denied (incorrect hash, expired timestamp)

Samples of generated URL

https://{domain}.safe-access.com/remote/v1/access/?next={url}&external_id={external_id}&timestamp={timestamp}&hash={hash}

With:

https://example.safe-access.com/remote/v1/access/?next=https%3A%2F%2Fexample.safe-access.com%2Fapi%2Fv1%2Furl%2Fmanager%2Femployee%2Ffolder%2F%3Fexternal_id%3D234&external_id=123&timestamp=1172960204.226908&hash=xxxxxxxxxxx

Example

The scripts below are developed in Python. First they generate the URL with its signature (hash), then sends the call towards UKG HR Service Delivery (this returns a 302 REDIRECT type HTTP response).

SSO call for a manager

import hmac
import hashlib
import httplib
import time
import urllib

# General parameters
DOMAIN = "client-xxx-demo.novapost.net"
SSO_BASE_URL = "/remote/v1/access/"
SECRET_KEY = 'R5678GT6FG5R665678990BVBFG' # Secret key shared by UKG HR Service Delivery and api consumer

# Next api URL
# Redirects to the employee folder of {employee_id} if logged as a manager
# (employee_id = technical_id of the employee)
# NEXT = "/api/v1/url/manager/employee/upload/?employee_id=21"

# Or: redirects to the dashboard of UKG HR Service Delivery
NEXT = "/company/config/"

# User technical_id of the manager to be logged in whith the sso call
EXTERNAL_ID = '1'

# Build hash
timestamp = time.time()
data = u'%s%s%s' % (EXTERNAL_ID, SECRET_KEY, timestamp)
built_hash = hmac.new(
        SECRET_KEY.encode('ascii'),
        msg=data.encode('utf-8'),
        digestmod=hashlib.sha256).hexdigest()


conn = httplib.HTTPSConnection(DOMAIN)
sso_url = "%s?external_id=%s&timestamp=%s&hash=%s&next=%s" % (
            SSO_BASE_URL,
            EXTERNAL_ID,
            str(timestamp),
            str(built_hash),
            urllib.quote_plus(NEXT))

print("SSO URL: https://%s/%s " % (DOMAIN, sso_url))

conn.request("GET", sso_url)
r1 = conn.getresponse()
headers = r1.getheaders()
if r1.status == 302:
    print("\nSSO SUCCEEDED!")
    print("REDIRECT TO ", r1.getheader('LOCATION'))
else:
    print("\nERROR")
    print("\n", r1.status, r1.reason)
    print(r1.read())

SSO for an employee

import hmac
import hashlib
import httplib
import time
import urllib

# General parameters
DOMAIN = "client-xxx-demo.novapost.net"
SSO_BASE_URL = "/remote/access"
SECRET_KEY = 'R5678GT6FG5R665678990BVBFG' # Secret key shared by UKG HR Service Delivery and api consumer

# Next api URL
# Redirects to the employee folder of the logged employee
NEXT = "/api/v1/url/employee/folder"
# NEXT = "/api/v1/url/employee/documents?doc_type=xxxxxx"
# NEXT = "/api/v1/url/employee/documents/upload/"
# NEXT = "/api/v1/url/employee/documents/upload/?doc_type=xxxxxx"

# technical_id of the employee to be logged in whith the sso call
EXTERNAL_ID = '21'

# Build hash
timestamp = time.time()
data = u'%s%s%s' % (EXTERNAL_ID, SECRET_KEY, timestamp)
built_hash = hmac.new(
        SECRET_KEY.encode('ascii'),
        msg=data.encode('utf-8'),
        digestmod=hashlib.sha256).hexdigest()


conn = httplib.HTTPSConnection(DOMAIN)
sso_url = "%s?external_id=%s&timestamp=%s&hash=%s&next=%s" % (
            SSO_BASE_URL,
            EXTERNAL_ID,
            str(timestamp),
            str(built_hash),
            urllib.quote_plus(NEXT))

print("SSO URL: https://%s/%s " % (DOMAIN, sso_url))

conn.request("GET", sso_url)
r1 = conn.getresponse()
headers = r1.getheaders()
if r1.status == 302:
    print("\nSSO SUCCEEDED!")
    print("REDIRECT TO ", r1.getheader('LOCATION'))
else:
    print("\nERROR")
    print("\n", r1.status, r1.reason)
    print(r1.read())