1. CORE CONCEPTS & GUIDES
  2. >
  3. GUIDES
  4. >
  5. WS-Trust Integration Guide

Overview

This guide describes the technical requirements necessary to enable Third Party Authentication (3PA) or Automated Provisioning with iQmetrix platform services using an existing WS-Trust Identity provider and SAML token. At this time, the only identity provider supported is Windows Server 2012 R2 AD FS

SAML

SAML (Security Assertion Markup Language) is an XML-based data format for exchanging data between systems.

There are many different versions of SAML, but iQmetrix only supports SAML using WS-Trust, a specification that uses secure messaging to create a trusted relationships between applications. Note that iQmetrix does not currently support SAML 2.0.

Technical Flow

Authentication Flow

  1. A user from your organization enters credentials into an iQmetrix product, such as RQ. The application sends a request to iQmetrix’s Single Sign On (SSO) service
  2. The SSO service sends a POST WS-Security UsernameToken Profile 1.1 request using the #PasswordText extension to the URL you supplied. If auto-provisioning is enabled then claims are also requested.
  3. The Identity Provider responds with a WS-Security SAML Token Profile 1.1 response with a SAML 2.0 token in the RequestedSecurityToken element. Values for the requested claims are also returned if auto-provisioning is enabled.
  4. iQmetrix’s Authentication service accepts the response and generates an Access Token
  5. The user is able to access the iQmetrix product. If auto-provisioning is enabled, user is created or updated according to the claims received.

Requirements

use the identity provider Windows Server 2012 R2 AD FS 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.

Setup and Configuration

Before configuring Hub, you should be able to demonstrate using the Troubleshooting Tool or similar that ADFS is configured as required.

Using ADFS, you may find the following setup guides useful.

In adding a non-claims aware relaying party trust the retailer should use the following values:

Setting Value
Display Name iQmetrix Services
Non-claims-aware relaying party trust identifier https://iqmetrix.net
Multi-factor Authentication I do not want to configure multi-factor authentication settings for this relying party trust at this time

Claims

The table below describes claims that will be requested.

Claim Required/Optional
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn Required
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Optional
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname Optional
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname Optional

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 Expected Format
General > Security > Username Users > General > User Name https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn1* string
General > Details > First Name Users > General > First Name https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname string
General > Details > Last Name Users > General > Last Name https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname string
General > Security > Security Role Users > General > Security Role https://iqmetrix.net/claims/securityGroupName string, as mapped in Authentication Setup
Locations Users > Locations https://iqmetrix.net/claims/assignedEntityClientEntityId string, as mapped in Company Tree to external Node Identifier
General > Email Settings > Email Address Users > General > Email https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress string
General > Details > Home Number, Ext Users > General > Home Phone Number https://iqmetrix.net/claims/telephoneNumbers/home string
General > Details > Cell Number Users > General > Cell Phone Number https://iqmetrix.net/claims/telephoneNumbers/cell string
General > Email Settings > Email Display Does not display in Hub https://iqmetrix.net/claims/attributes/EmailDisplayName string
General > Details > Role Does not display in Hub https://iqmetrix.net/claims/attributes/OrganizationalRoleID RQ ID, supplied by iQmetrix in setup
General > Details > Supervisor Does not display in Hub https://iqmetrix.net/claims/attributes/SupervisorUPN string
Admin > Personal > ID Number Does not display in Hub https://iqmetrix.net/claims/attributes/SpecialIdentifier string
Admin > Compensation > Commission Does not display in Hub https://iqmetrix.net/claims/attributes/CommissionGroupID RQ ID, supplied by iQmetrix in setup
Admin > Compensation > Compensation Type Does not display in Hub https://iqmetrix.net/claims/attributes/CompensationType string, as mapped to values in RQ
Admin > Custom Fields Does not display in Hub https://iqmetrix.net/claims/attributes/rqcustomfield_{name} string, as mapped to values in RQ
Does not display Does not display https://iqmetrix.net/claims/clientUserId string

Notes

Example Request
POST https://adfs.retaillabs.io/adfs/services/trust/13/UsernameMixed HTTP/1.1
Content-Type: application/soap+xml; charset=utf-8
Host: adfs.retaillabs.io
Content-Length: 2255
Expect: 100-continue
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

<s:Envelope xmlns:s="https://www.w3.org/2003/05/soap-envelope" xmlns:a="https://www.w3.org/2005/08/addressing" xmlns:u="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <s:Header>
        <a:Action s:mustUnderstand="1">https://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</a:Action>
        <a:MessageID>urn:uuid:2be726b3-e368-4a10-88f3-fd0312c9edc5</a:MessageID>
        <a:ReplyTo>
            <a:Address>https://www.w3.org/2005/08/addressing/anonymous</a:Address>
        </a:ReplyTo>
        <a:To s:mustUnderstand="1">https://adfs.retaillabs.io/adfs/services/trust/13/UsernameMixed</a:To>
        <o:Security s:mustUnderstand="1" xmlns:o="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <u:Timestamp u:Id="_0">
                <u:Created>2015-06-30T20:16:13.639Z</u:Created>
                <u:Expires>2015-06-30T20:21:13.639Z</u:Expires>
            </u:Timestamp>
            <o:UsernameToken u:Id="uuid-2ed4cc51-2345-446c-be94-9af4ab99d24c-1">
                <o:Username>Nicola.Tesla@retaillabs.local</o:Username>
                <o:Password Type="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">4AlternatingCurrent</o:Password>
            </o:UsernameToken>
        </o:Security>
    </s:Header>
    <s:Body>
        <trust:RequestSecurityToken xmlns:trust="https://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <wsp:AppliesTo xmlns:wsp="https://schemas.xmlsoap.org/ws/2004/09/policy">
                <a:EndpointReference>
                    <a:Address>https://iqmetrix.net/</a:Address>
                </a:EndpointReference>
            </wsp:AppliesTo>
            <trust:Claims Dialect="https://schemas.xmlsoap.org/ws/2005/05/identity" xmlns:i="https://schemas.xmlsoap.org/ws/2005/05/identity">
                <i:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" Optional="false"/>
                <i:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" Optional="true"/>
                <i:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" Optional="true"/>
                <i:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" Optional="true"/>
            </trust:Claims>
            <trust:KeyType>https://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer</trust:KeyType>
            <trust:RequestType>https://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</trust:RequestType>
            <trust:TokenType>urn:oasis:names:tc:SAML:2.0:assertion</trust:TokenType>
        </trust:RequestSecurityToken>
    </s:Body>
</s:Envelope>
Example Response
HTTP 200 Content-Type: application/soap+xml

<s:Envelope xmlns:s="https://www.w3.org/2003/05/soap-envelope" xmlns:a="https://www.w3.org/2005/08/addressing" xmlns:u="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <s:Header>
        <a:Action s:mustUnderstand="1">https://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal</a:Action>
        <a:RelatesTo>urn:uuid:2be726b3-e368-4a10-88f3-fd0312c9edc5</a:RelatesTo>
        <o:Security s:mustUnderstand="1" xmlns:o="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <u:Timestamp u:Id="_0">
                <u:Created>2015-06-30T20:16:15.509Z</u:Created>
                <u:Expires>2015-06-30T20:21:15.509Z</u:Expires>
            </u:Timestamp>
        </o:Security>
    </s:Header>
    <s:Body>
        <trust:RequestSecurityTokenResponseCollection xmlns:trust="https://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <trust:RequestSecurityTokenResponse>
                <trust:Lifetime>
                    <wsu:Created xmlns:wsu="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2015-06-30T20:16:15.505Z</wsu:Created>
                    <wsu:Expires xmlns:wsu="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2015-06-30T21:16:15.505Z</wsu:Expires>
                </trust:Lifetime>
                <wsp:AppliesTo xmlns:wsp="https://schemas.xmlsoap.org/ws/2004/09/policy">
                    <wsa:EndpointReference xmlns:wsa="https://www.w3.org/2005/08/addressing">
                        <wsa:Address>https://iqmetrix.net</wsa:Address>
                    </wsa:EndpointReference>
                </wsp:AppliesTo>
                <trust:RequestedSecurityToken>
                    <Assertion ID="_62c0ac75-0267-46cf-95a6-91b9cdc8ed79" IssueInstant="2015-06-30T20:16:15.509Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
                        <Issuer>https://adfs.retaillabs.io/adfs/services/trust</Issuer>
                        <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
                            <ds:SignedInfo>
                                <ds:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#"/>
                                <ds:SignatureMethod Algorithm="https://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                                <ds:Reference URI="#_62c0ac75-0267-46cf-95a6-91b9cdc8ed79">
                                    <ds:Transforms>
                                        <ds:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                                        <ds:Transform Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#"/>
                                    </ds:Transforms>
                                    <ds:DigestMethod Algorithm="https://www.w3.org/2000/09/xmldsig#sha1"/>
                                    <ds:DigestValue>nWRVS/+EPGC10gyKqvuLcXLhwE8=</ds:DigestValue>
                                </ds:Reference>
                            </ds:SignedInfo>
                            <ds:SignatureValue>lCi93bMFIoSOmf4uBq95OF4LO7c5mARkR4x/1LagKDBS/iKMEi73EmxtZJ5o9L/OAfIueaKrdtiXFJXqB5KysA3WAjuMDVtaDfbJzhMhqZnXB2NrShA0vBM4cfCFj1VJe9ozTQiQUVtL/O0HTM06jCMHwJhbl1DMdTdZt9OejDfBtJDk5wr0TGLBmDYuVjIb2k+nWIWvCCjmOQbHlK65IcFaOQoXYjdwGu4YWttejC4m+sqgnAH926t9eorxpY928EVxN5xoB/UFSQFpnfQvPgfogu1EeByF2mwvbdf/qNIMtejF4AqAq6RUWvdhcFy+VDJqeWYBN2UY9LP4XdIU0g==</ds:SignatureValue>
                            <KeyInfo xmlns="https://www.w3.org/2000/09/xmldsig#">
                                <ds:X509Data>
                                    <ds:X509Certificate>MIIC4DCCAcigAwIBAgIQNGL3q/dLsoFBwDzHqMXstjANBgkqhkiG9w0BAQsFADAsMSowKAYDVQQDEyFBREZTIFNpZ25pbmcgLSBhZGZzLnJldGFpbGxhYnMuaW8wHhcNMTUwMTIxMjEwNTI4WhcNMTYwMTIxMjEwNTI4WjAsMSowKAYDVQQDEyFBREZTIFNpZ25pbmcgLSBhZGZzLnJldGFpbGxhYnMuaW8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCo1zytlu3USZhnj9bVcIVcvhWr5ojuYNzvR8mX/enOcIyoPzlP+0nSaoajTxutLi5uXYE27bRtnVQ6vWwLCMJ5TLxW1LvgcE4yNQg2ns+f0mI27Nvic4xTP4Yhh6CzYdxSbJURGKKSOvTKTmNJttqNGUvpJRakavKC6zF6ZniA+E7AlL6ONQd+E7O80WdybK44vwiDxaPcgHlqIRAn6cHgYL9WgC8NMt8plJFxN4oxnUpIiyS2jyWWs3PfOsgFIWqmx18s6TpH8VEJ7JOJkC5vhHZ6RPXxnS5EkpOd24IzvwSrmMmYRcb3LLQptcGymD4s1YVKkoKp2JAdJIBtTdj3AgMBAAEwDQYJKoZIhvcNAQELBQADggEBAFON9MIWas0ftf+No80T1LIRNh0kbvAFTYTDycLN1XzoIy1mCM0E+iRGe6ZmGNDgc+I11ZFbvvgV2DT/PLXlafRnKLomPWAZfzYHp1doWGFCFjBKQG6W0KjwTBxJTEy0v76I3q/BMBMn3iEr+uJvaDzsM212IImJqPvFsiQR3rEEoSZAWNNe8SVp3WiwoPXIv+hDuo1cRArroXb0rmZff/ubHWMJZz+4/RoLYz/EPCNDoygT7M/cV4mC5RVrvWC8eG8Gw9jBMeFXKQWcrS6PWY9py/f2nCzdmx8OPj9BhLoPc6ieD2ed44tIX58JhFdQxNfo7F4LAa4uZgi73Kzf9Bo=</ds:X509Certificate>
                                </ds:X509Data>
                            </KeyInfo>
                        </ds:Signature>
                        <Subject>
                            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                                <SubjectConfirmationData NotOnOrAfter="2015-06-30T20:21:15.509Z"/>
                            </SubjectConfirmation>
                        </Subject>
                        <Conditions NotBefore="2015-06-30T20:16:15.505Z" NotOnOrAfter="2015-06-30T21:16:15.505Z">
                            <AudienceRestriction>
                                <Audience>https://iqmetrix.net</Audience>
                            </AudienceRestriction>
                        </Conditions>
                        <AttributeStatement>
                            <Attribute Name="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn">
                                <AttributeValue>Nicola.Tesla@retaillabs.local</AttributeValue>
                            </Attribute>
                        </AttributeStatement>
                        <AuthnStatement AuthnInstant="2015-06-30T20:16:15.477Z">
                            <AuthnContext>
                                <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
                            </AuthnContext>
                        </AuthnStatement>
                    </Assertion>
                </trust:RequestedSecurityToken>
                <trust:RequestedAttachedReference>
                    <SecurityTokenReference b:TokenType="https://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" xmlns="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:b="https://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
                        <KeyIdentifier ValueType="https://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">_62c0ac75-0267-46cf-95a6-91b9cdc8ed79</KeyIdentifier>
                    </SecurityTokenReference>
                </trust:RequestedAttachedReference>
                <trust:RequestedUnattachedReference>
                    <SecurityTokenReference b:TokenType="https://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" xmlns="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:b="https://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
                        <KeyIdentifier ValueType="https://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">_62c0ac75-0267-46cf-95a6-91b9cdc8ed79</KeyIdentifier>
                    </SecurityTokenReference>
                </trust:RequestedUnattachedReference>
                <trust:TokenType>urn:oasis:names:tc:SAML:2.0:assertion</trust:TokenType>
                <trust:RequestType>https://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</trust:RequestType>
                <trust:KeyType>https://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer</trust:KeyType>
            </trust:RequestSecurityTokenResponse>
        </trust:RequestSecurityTokenResponseCollection>
    </s:Body>
</s:Envelope>

Adding RQ Employee Custom Fields

You can auto-provision RQ custom fields using the prefix rqCustomField. RQ Employee Custom Fields are defined in the RQ Settings Console and appear on the Admin tab of an employee profile.

Custom Employee Attributes in RQ

Warning: Before adding additional fields, discuss your requirements with your Account Manager to ensure they will appear in RQ.
Claim Value Description
https://iqmetrix.net/claims/attributes/rqCustomField_{AttrName} TheValue Add TheValue to the {AttrName} field for the employee in RQ

Training Databases

We can support integrating your Training Database with your ADFS without additional configuration on your part with the following limitations:

Please contact your Client Manager for more details.

Troubleshooting

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