Restricted employee access SSO¶

General Description¶

This API provides a means of opening a special session on UKG HR Service Delivery, giving the user a restricted and temporary access to a specific employee file, regarless of his currently defined perimeter.

Access Rights & security¶

In this special session, the user is only able to navigate in the employee file specified in the request API.

This API method can only be used by an authorized client application, thanks to a URL signing mechanism described below. The signed URL should be generated by the main information system (HRIS) and contain:

• a user account identifier (the user whose access is delegated)

• an employee identifier (the employee whose file is accessed)

• a role identifier (the role that is used to restrict access to documents). The user must already have this role defined on their profile.

• a timestamp

• a “signing hash” generated from: * a secret key shared between the HRIS and UKG HR Service Delivery * the other GET parameters of the URL (including the timestamp)

The “signing hash” 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 by our server (using the shared secret key) and compared against the one received. The timestamp is used to limit the validity of the URL (1 minute).

This mechanism ensures:

• That each URL generated is unique (thanks to the timestamp)

• That each URL is only valid for a very limited time (so sharing this url is useless…)

• That only the authorized client application can generate those URLs

URL¶

/restricted_employee_access/

GET parameters¶

• manager_technical_id:

  technical id of the user that is logged

• employee_technical_id:

  technical_id of the employee file that is accessed

• external_role_id:

  identifier of the role that is used to restrict access to documents

• timestamp:

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

• hash:

  signature of the parameters [manager_technical_id, employee_technical_id, external_role_id, timestamp] using the secret key shared between UKG HR Service Delivery and the HRIS.

Example URL¶

/restricted_employee_access/?manager_technical_id=XXXXXXX&employee_technical_id=YYYYYYY&external_role_id=base-hr&timestamp=1409928275.0&hash=d3e79aabdc794130beeb5d739d0c6456f16fbc5db727615edd1504ea0924122b

Building the hash parameter¶

The format of this signature is as follows:

HMAC->SHA1(secret_key, manager_technical_id+employee_technical_id+external_role_id+secret_key+timestamp)

Example in Python:

import hmac
import hashlib
import time

# Secret Key shared between the HRIS and HR Service Delivery
secret_key = "mysecretkey"

# Request parameters
manager_technical_id = "XXXXXXXXXXX"
employee_technical_id = "YYYYYYYYYYY"
external_role_id = "base-hr"

# Timestamp
# timestamp = time.time()
timestamp = "1409928275.0"

# Preparation of the message string to sign
data = u'%s%s%s%s%s' % (manager_technical_id, employee_technical_id, external_role_id, secret_key, timestamp)

# Hash calculation
built_hash = hmac.new(secret_key.encode('ascii'), msg=data.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()

# with thoses parameters, built_hash should be:
# d3e79aabdc794130beeb5d739d0c6456f16fbc5db727615edd1504ea0924122b