Overview

This guide describes the technical requirements necessary to enable Third Party Authentication (3PA) or Automated Provisioning with iQmetrix platform services using using OAuth 2.0 protocol for authorization and OpenId Connect protocol for authentication and asserting identity.

Technical Flow

Authentication Flow

  1. A User from your organization supplies credentials to an iQmetrix application and the application forwards the requests to iQmetrix’s SSO implementation
  2. iQmetrix’s SSO server POSTs an OAuth 2.0 authorization code grant request to the supplied URL
  3. The Identity Provider returns an Access Token
  4. For Auto-Provisioning only: iQmetrix SSO server will make a request to OpenID Connect UserInfo Endpoint using Access Token
  5. For Auto-Provisioning only: Your UserInfo endpoint returns the requested information as claims
  6. iQmetrix’s SSO server accepts the authentication result and generates a OAuth 2.0 token for the user
  7. User is able to use the iQmetrix application

Requirements

Your organization must provide access to an Identity Provider supporting…

Your Account Manager will need the following information to configure Third Party Authentication:

SSL Protection

Secure Socket Layer (SSL) is technology that establishes a secure channel of communication and makes all eCommerce and web security possible.

SSL works by requiring a server to install a SSL Certificate, which acts as a key to access the server. For iQmetrix to communicate with your SSL encrypted server, this certificate must be publicly available.

Your organization is responsible for providing an Identity Provider that is protected by SSL and has a publicly-available SSL certificate.

Acceptable User Names

We strongly recommend you create publicly-accessible domains and map your users to them, rather than using your internal domains. This will ensure that your user names are unique within our system.

Email addresses are an excellent alternative to domain user names.

Example

A user “john.smith@yvr.kentel.local” could be mapped to “john.smith@kentel.com”.

High Availability

High availability means a system is capable of maintaining a high level of operational performance for a period of time.

It is your organization’s responsibility to ensure your Identity Provider is highly available. If you are unsure what that requires or if you anticipate problems, please let contact Support and we can discuss ways to mitigate these.

Setup and Configuration

It is your responsibility to setup and configure your Identity Provider.

Scopes

The table below describes the scopes that will be requested.

Note that these scopes are only required for integrations involving Automated Provisioning.

Scope Notes
openid Required for OpenID Connect OAuth 2.0 request.
email Standard Open ID Connect Claim
profile Standard Open ID Connect Claim
phone Standard Open ID Connect Claim
iqmetrix Custom claim

Auto-Provisioned Fields

iQmetrix is able to automatically provision fields when a user logs in. For a complete list, see the table below.

RQ Field (Employee Profile) Equivalent Hub Field Claim Type  
General > Security > Username Users > General > User Name userName (OpenID Connect standard claim)  
General > Details > First Name Users > General > First Name name (OpenID Connect standard claim)  
General > Details > Last Name Users > General > Last Name family_name (OpenID Connect standard claim)  
General > Security > Security Role Users > General > Security Role security_group_name (custom claim)  
Locations Users > Locations assigned_entity_client_entity_ids (custom claim)  
General > Email Settings > Email Address Users > General > Email email (OpenID Connect standard claim)  
General > Email Settings > Email Display Does not display in Hub attribute_EmailDisplayName (custom claim)  
General > Details > Home Number, Ext Users > General > Home Phone Number phone_number (OpenID Connect standard claim)  
General > Details > Cell Number Users > General > Cell Phone Number mobile_number (custom claim)  
General > Details > Role Does not display in Hub attribute_OrganizationalRoleID (custom claim)  
General > Details > Supervisor Does not display in Hub attribute_SupervisorUPN (custom claim)  
Admin Personal > ID Number Does not display in Hub attribute_SpecialIdentifier (custom claim)
Admin > Compensation > Commission Does not display in Hub attribute_CommissionGroupID (custom claim)  
Admin > Compensation > CompensationType Does not display in Hub attribute_CommissionType (custom claim)  
Admin > Custom Fields Do not display in Hub attribute_rqCustomField_{name} (custom claim)  

Notes

Example Request
POST /oauth2/ausahmkfuuR7FgsLi0h7/v1/token HTTP/1.1
Host: dev-179913.oktapreview.com
Accept: application/json
Authorization: Basic bTA3QUxzbEZNSk1HY0lTR2Ixc2Y6cjdPanFjeE5WVE1PeDZ2Y1YySmdsOVRsNkQyUHNBYVowTXpMRDJ2Tw==
Content-Type: application/x-www-form-urlencoded
 
grant_type=password&redirect_uri=https%3A%2F%2Fhttpbin.org%2Fget&username=daniel%40gerlag.ca&password=P%40ssw0rd&scope=openid+profile+email+phone+iqmetrix
Example Response
HTTP 200 Content-Type: application/soap+xml
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtWM243QWlXSDRtNkJnenkyRDU3ODl4YVI5cERUQm5jMGY0M0NPVkFTdlUifQ.eyJ2ZXIiOjEsImp0aSI6IkFULl80RlNzUV9YQ0pveUtKb0ptdnFfQklRbEgtUDMxaEFpSHRfMmpLYldvZkkiLCJpc3MiOiJodHRwczovL2Rldi0xNzk5MTMub2t0YXByZXZpZXcuY29tL29hdXRoMi9hdXNhaG1rZnV1UjdGZ3NMaTBoNyIsImF1ZCI6Imh0dHBzOi8vaHR0cGJpbi5vcmcvIiwiaWF0IjoxNDk3MzA0MzUzLCJleHAiOjE0OTczMDc5NTMsImNpZCI6Im0wN0FMc2xGTUpNR2NJU0diMXNmIiwidWlkIjoiMDB1YWExajY1MENGVXB3bDkwaDciLCJzY3AiOlsiaXFtZXRyaXgiLCJvcGVuaWQiLCJlbWFpbCIsInByb2ZpbGUiLCJwaG9uZSJdLCJzdWIiOiJkYW5pZWxAZ2VybGFnLmNhIn0.NjI89IW9XP68h79TQj5foUl-LYTyqTCFECP5zitjM7vXKwvedeNnpIvGwS-4PXwfFOjdpoJ5S6o_iTLjJB8d923Vs5IDLV8LcSmWwf09_qH_L6Cbd1TPNSV5_U7ji0RNDTYi_vX9rlMev8ThN6i6tuplqDNfJ5AQ9pktySJg4ZNgK-Hmn7bEGq8ney8zE-uNTBUNYGYYM9H3cBL7SV3Cj2d0v5-wa3hyLd1H1Ol5kDSu9JECu8x0HRQTlXLDOLZPm9fGmzQgBq0e_9qsHCZ5IjVWNXX1ftLrOfGhCu-3wQZSuglLEnt3nsolz-F_9u7oQL4Yo8dBLM71D3dDb3SD8A",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "iqmetrix openid email profile phone",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtWM243QWlXSDRtNkJnenkyRDU3ODl4YVI5cERUQm5jMGY0M0NPVkFTdlUifQ.eyJzdWIiOiIwMHVhYTFqNjUwQ0ZVcHdsOTBoNyIsIm5hbWUiOiJTdXBlcm1hbiIsImVtYWlsIjoiZGFuaWVsQGdlcmxhZy5jYSIsInZlciI6MSwiaXNzIjoiaHR0cHM6Ly9kZXYtMTc5OTEzLm9rdGFwcmV2aWV3LmNvbS9vYXV0aDIvYXVzYWhta2Z1dVI3RmdzTGkwaDciLCJhdWQiOiJtMDdBTHNsRk1KTUdjSVNHYjFzZiIsImlhdCI6MTQ5NzMwNDM1MywiZXhwIjoxNDk3MzA3OTUzLCJqdGkiOiJJRC5Eb0dBOUp3bEc5R0U0RHJodUNOTXdna2FlaTlDWTM0NEI4QzNtR203aExrIiwiYW1yIjpbInB3ZCJdLCJpZHAiOiIwMG85czRvc2dsR0hxUHJvdDBoNyIsInByZWZlcnJlZF91c2VybmFtZSI6ImRhbmllbEBnZXJsYWcuY2EiLCJhdXRoX3RpbWUiOjE0OTczMDQzNTMsImF0X2hhc2giOiJLa25CVUJubkNVYlptdEtRZVJCTTZBIn0.VG9VNtD0VAMMrj6YProjetOIqdbJ05vYYkK0dph-iTxel_IT8smp5TF3IyqjTAdd4KFopgKP13cKDDnKBo-bhkV6QL-tooYKbs_WLgSzbZkI3Rarip8WJNhuqvGVTNNDKp4OcEHAt768uyyTZAGeXL5L47PSINi2zXYywjmmwUfPb9_Lx71J3ADfbggH61KHlbzkngtkdyajkA_w3MkWYT1d7lmhEixtf0CZHuXjszesDqcl6dllwfs9TKwTSwApMfvD_Y48KcBPv2uEvYojgMKQs6bXOJ6XEccjcSOfNaQduUOskRcA8zdBc7JkKr-IW2InQLXWplx2TwByv33ZBg"
}

Troubleshooting

If you encounter issues while testing the integration, see the 3PA FAQ and Troubleshooting Guide.

Was this page helpful?