End User OAuth

Overview

With messaging being used by your customers on a regular basis for every different type of interaction it is important for you to be able to verify their identity as needed. The Quiq platform supports pushing an Authentication message out that allows your customers to log into your site securely. This message can be set up as a snippet that your agents can use when needed and can also be sent out by bots and other interactions through the Quiq API’s.

Minimal Setup

Quiq follows the industry standard OAuth 2.0 Authorization Code Grant Flow. This is a simple API protocol that allows your site to authenticate an end user without Quiq needing to hold any of the end users secrets. To set up this flow the following information is needed from you.

Information	Description	Example
Client	A public identifier we should use when calling your OAuth provide	Quiq Client
Scope (Optional)	The scope to request access to	read
Secret	A private shared secret that we will pass server to server only when asking for the access token	23b21bc8-a76b-41da-be6a-c8087b8dca2a
Authorization URL	The URL that kicks off the oauth flow. This will ultimately show the login screen/authorization area for your site. We will include the response_type of code, the client_id, and the scope you specify	https://yoursite.com/auth
Token URL	The URL we will post the code to that will return an Access Token (last leg of the OAuth Flow)	https://yoursite.com/auth/token

With this information set up we are able to do a basic OAuth handshake and securely authenticate your end users using their preferred messaging platform.

Redirect URLs to Whitelist

Many OAuth providers require you to white list the redirect URLs that are sent as a query arg to the Authorization URL and that the OAuth provider ultimately redirects back to. This provides an added layer of security. If the OAuth provider you use requires this please add all 3 of the following redirect urls:

https://[tenant].goquiq.com/idp/eu/oauth/callback
https://[tenant].goquiq.com/web/inbound/abc/oauth/redirect
https://[tenant].goquiq.com/web/inbound/abc/oauth/abcAuth2Redirect

Advanced Setup

Quiq supports an additional step to allow you to securely pass back user information once they have authenticated. This includes things like Name, Email, UserId, etc. In order to make use of this you will provide an additional “WhoAmI URL”. After the end user has authenticated we will call this WhoAmI URL with their access token and you can return this information back in the following format (all fields are optional):

{
  "email" : "[email protected]",
  "userName" : "billy.bob",
  "fullName" : "Billy Bob",
  "firstName" : "Billy",
  "lastName" : "Bob",
  ...
}

Quiq will make use of the email, first, and last name to populate your contact record automatically if appropriate. Our platform will also optionally parse fullName into first and last if you only have that field defined. Lastly if you (or your OAuth provider) already has a WhoAmI API that returns a payload in a different format you can provide a JMESPath adaption configuration. For instance if your whoAmI endpoint returns some data like this:

{
  "user": {
    "id": "billy.bob",
    "name": "Billy Bob",
    "email": "[email protected]",
    "other": "stuff"
  },
  "roles": ["SomeRole", "OtherRole"],
  "other": "stuff"
}

You can then provide the following JMESPath configuration and email, firstName, lastName, userName, will all be parsed correctly and can be used for setting fields, routing, rules, etc. with in the Quiq platform.

{"userName\": user.id, \"fullName\": user.name, \"email\": user.email}"