Overview

This document will cover some of the common questions and problems around Automated Provisioning.

Troubleshooting Tool

To assist with troubleshooting, the iQmetrix 3PA Troubleshooting Tool allows you to see the data the WSTrust (ADFS) or OAuth2 (Okta) endpoint is returning.

  1. Download the zipped folder
  2. Extract the folder
  3. Double click on iQmetrixThirdPartyAuthenticationTest.exe to run the tool
  4. Modify values in the form
  5. Click Submit
  6. Interpret the response

ADFS Configuration

WSTrust Configuration

Value Required? Description Example
Type Required The type of authentication WSTrust
Authentication URL Required Endpoint for your provider https://adfs.retaillabs.io/adfs/services/trust/13/UsernameMixed
Username Required Username testuser1@retaillabs.io
Password Required Password Password1

Okta Configuration

OAuth2 Configuration

Value Required? Description Example
Type Required The type of authentication Oauth 2
Authentication URL Required OAuth2 endpoint for your Okta identity provider https://dev-127466.oktapreview.com/oauth2/ausaoaasbu3aA0nqu0h7/v1
Username Required Username qatester02@luketester.com
Password Required Password Password1
ClientId Required Client Id, assigned in Okta when iQmetrix is registerred as an application 9kYE48IocKMMi6pdnUe
ClientSecret Required Client Secret, assigned in Okta when iQmetrix is registerred as an application y8gXmhNBrztBtul7h53Zg8NT7L3MEl8ZWcY1Io14

Response

The tool will display all data returned from the provided WSTrust or OAuth2 endpoint.

The fields in the response depend on which claims you have configured, as shown in the following table.

UserName: '{Username}'
EmailAddress: '{Email}'
FirstName: '{FirstName}'
LastName: '{LastName}'
AssignedEntityClientEntityId: '{AssignedEntityClientEntityId}'
AssignedEntityClientEntityIds: '{AssignedEntityClientEntityIds}'
SecurityGroupName: '{SecurityGroupName}'
HomePhoneNumber: {HomePhoneNumber}
WorkPhoneNumber: {WorkPhoneNumber}
CellPhoneNumber: {CellPhoneNumber}
ClientUserId: '{ClientUserId}'
Attribute {AttributeName}: '{AttributeValue}'
Attribute {CustomAttributeName}: '{CustomAttributeValue}'
Value RQ Usage Source Example
Username Employee username https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn testuser9a@retaillabs.io
Email Employee email https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress testuser9a@retaillabs.io
FirstName Employee first name https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname Test
LastName Employee last name https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname User 9aa
AssignedEntityClientEntityId Identifier for a node in the company tree this employee should be assigned to. Either this or AssignedEntityClientEntityIds is required https://iqmetrix.net/claims/assignedEntityClientEntityId KY
AssignedEntityClientEntityIds Identifiers for nodes in the company tree this employee should be assigned to. Either this or AssignedEntityClientEntityId is required https://iqmetrix.net/claims/assignedEntityClientEntityIds KY,MK,FW
SecurityGroupName Name of the security group in your system this employee belongs to https://iqmetrix.net/claims/securityGroupName Dealer
HomePhoneNumber Employee home number https://iqmetrix.net/claims/telephoneNumbers/home 8888888888
WorkPhoneNumber Employee work number https://iqmetrix.net/claims/telephoneNumbers/work 6666666666
CellPhoneNumber Employee cell number https://iqmetrix.net/claims/telephoneNumbers/cell 5555555555
ClientUserId Identifier for the employee in your system https://iqmetrix.net/claims/clientUserId 123123
AttributeName Name of an RQ field Defined in RQ CompensationType
AttributeValue Value for a RQ field https://iqmetrix.net/claims/attributes/(AttrName) Salaried
CustomAttributeName Name of a custom field in RQ Custom field defined in RQ YourCustomField
CustomAttributeValue Value of a custom field in RQ https://iqmetrix.net/claims/attributes/rqCustomField_(AttrName) TheValue
Example
UserName: 'testuser9a@retaillabs.io'
EmailAddress: 'testuser9a@retaillabs.io'
FirstName: 'Test'
LastName: 'User 9aa'
AssignedEntityClientEntityId: 'KY'
SecurityGroupName: 'Dealer'
HomePhoneNumber: [not set]
WorkPhoneNumber: [not set]
CellPhoneNumber: [not set]
ClientUserId: '123123'
Attribute CompensationType: 'Salaried'
Attribute YourCustomField: 'TheValue'

Things to Check

If… Try…
A user can not login Checking Claims
The security role for a user is not updated Mapping your Security Roles
The user is not assigned a security role for a location Mapping your Company Tree
Users are being duplicated in RQ Checking User Ids

Checking Claims

One of the claims: AssignedEntityClientEntityId or AssignedEntityClientEntityIds must be provided so RQ knows at which level to assign the security role for the employee.

For more information, see Claims.

In addition, ensure the ADFS server time is correct. If the ADFS server is off by even a few minutes, logins will fail. WCF, by default, allows a five-minute gap, beyond this is throws an error. The solution is to sync machines. For more information, see Microsoft’s Blog Post.

Mapping your Security Roles

Every value that may be returned from your system using the securityGroupName claim must be mapped to a SecurityRoleName in Hub using the following steps:

  1. Log into Hub
  2. Click on Settings in sidebar
  3. Click on Authentication Setup from the options on the page
    • If you do not see Authentication Setup, ensure your security roles are mapped correctly
  4. Scroll down to Hub Security Roles Mapping
  5. Ensure each role in your system is mapped to a Hub Security Role
  6. Ensure the values in Identity Provider Role match the names of the roles in your system exactly

Screen shot of security role mapping

Mapping your Company Tree

Every value that may be returned from your system using the assignedEntityClientEntityId or assignedEntityClientEntityIds claim must be mapped as a External Node Identifier in Hub using the following steps:

  1. Log into Hub
  2. Click on Settings in sidebar
  3. Click on Companies from the options on the page
  4. Ensure each value from your system is mapped to a Company Tree Node in the form of an External Node Identifier

Screen shot showing company tree mapping in Hub

Checking User Ids

Every user in your system must have a unique identifier that will be set as a ClientUserId on the appropriate RQ user.

This is necessary for RQ to know which employee is logging in. Non-unique values may result in duplicate employees in RQ.