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.

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

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

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
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn Required
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Optional
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname Optional
http://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
General > Security > Username Users > General > User Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn1
General > Details > First Name Users > General > First Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
General > Details > Last Name Users > General > Last Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
General > Security > Security Role Users > General > Security Role http://iqmetrix.net/claims/securityGroupName
Locations > Users > Locations http://iqmetrix.net/claims/assignedEntityClientEntityId  
General > Email Settings > Email Address Users > General > Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
General > Details > Home Number, Ext Users > General > Home Phone Number http://iqmetrix.net/claims/telephoneNumbers/home
General > Details > Cell Number Users > General > Cell Phone Number http://iqmetrix.net/claims/telephoneNumbers/cell
General > Email Settings > Email Display Does not display in Hub http://iqmetrix.net/claims/attributes/EmailDisplayName
General > Details > Role Does not display in Hub http://iqmetrix.net/claims/attributes/OrganizationalRoleID
General > Details > Supervisor Does not display in Hub http://iqmetrix.net/claims/attributes/SupervisorUPN
Admin > Personal > ID Number Does not display in Hub http://iqmetrix.net/claims/attributes/SpecialIdentifier
Admin > Compensation > Commission Does not display in Hub http://iqmetrix.net/claims/attributes/CommissionGroupID
Admin > Compensation > Compensation Type Does not display in Hub http://iqmetrix.net/claims/attributes/CompensationType
Admin > Custom Fields Does not display in Hub http://iqmetrix.net/claims/attributes/rqcustomfield_{name}
Does not display Does not display http://iqmetrix.net/claims/clientUserId*

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="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <s:Header>
        <a:Action s:mustUnderstand="1">http://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>http://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="http://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="http://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="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
                <a:EndpointReference>
                    <a:Address>https://iqmetrix.net/</a:Address>
                </a:EndpointReference>
            </wsp:AppliesTo>
            <trust:Claims Dialect="http://schemas.xmlsoap.org/ws/2005/05/identity" xmlns:i="http://schemas.xmlsoap.org/ws/2005/05/identity">
                <i:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" Optional="false"/>
                <i:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" Optional="true"/>
                <i:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" Optional="true"/>
                <i:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" Optional="true"/>
            </trust:Claims>
            <trust:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer</trust:KeyType>
            <trust:RequestType>http://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="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <s:Header>
        <a:Action s:mustUnderstand="1">http://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="http://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="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <trust:RequestSecurityTokenResponse>
                <trust:Lifetime>
                    <wsu:Created xmlns:wsu="http://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="http://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="http://schemas.xmlsoap.org/ws/2004/09/policy">
                    <wsa:EndpointReference xmlns:wsa="http://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>http://adfs.retaillabs.io/adfs/services/trust</Issuer>
                        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                            <ds:SignedInfo>
                                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                                <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                                <ds:Reference URI="#_62c0ac75-0267-46cf-95a6-91b9cdc8ed79">
                                    <ds:Transforms>
                                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                                    </ds:Transforms>
                                    <ds:DigestMethod Algorithm="http://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="http://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="http://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="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:b="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
                        <KeyIdentifier ValueType="http://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="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0" xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:b="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
                        <KeyIdentifier ValueType="http://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>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</trust:RequestType>
                <trust:KeyType>http://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 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
http://iqmetrix.net/claims/attributes/rqCustomField_{AttrName} TheValue Add TheValue to the {AttrName} field for the employee in RQ

Troubleshooting

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

Was this page helpful?