Skip to main content
NICE CXone Expert

We will be closed on Monday, May 27th in observance of Memorial Day

Expert Success Center

Identity Token Exchange


This specification delineates the requirements for the exchange of a trusted identity token from a third-party system for authentication within the Expert system. In the event that the user is not pre-existing within the Expert system, they will be provisioned on a just-in-time basis. This approach is inspired by established industry practices and standards:  https://www.rfc-editor.org/rfc/rfc8693 and https://www.rfc-editor.org/rfc/rfc86...token-exchange.

Prerequisites

  • An existing identity provider configured with Expert via OpenID Connect.
  • An identity token, often referred to as an ID token, issued by a third-party system, corresponds with the identity provider issuer settings configured within Expert.
  • A valid identity token following https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
    • Must include claims given_name and family_name for name mapping.
    • Must include claim sub for username mapping.
    • Must include claim iss that matches configured identity provider in site.
    • (Optional) Should include email claim.

Identity Token Exchange Request and Response

Expected JSON Web Token aka JWT before encoded.

{
    "iss": "https://auth.example.com",
    "iat": 1713209011,
    "exp": 1744745011,
    "aud": "www.example.com",
    "sub": "cbcda2a5-6fba-462d-a876-7c4fc7c9379b",
    "given_name": "John",
    "family_name": "Doe",
    "name": "john.doe@example.com"
}

application/x-www-form-urlencoded; charset=utf-8

The default content-type of request with most code libraries.

Request

Include the identity token json web token in the body of the request.

POST @app/auth/token/exchange HTTP/1.1
Host: customersite.example.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJpYXQiOjE3MTMyMDkwMTEsImV4cCI6MTc0NDc0NTAxMSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiY2JjZGEyYTUtNmZiYS00NjJkLWE4NzYtN2M0ZmM3YzkzNzliIiwiZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsIm5hbWUiOiJqb2huLmRvZUBleGFtcGxlLmNvbSJ9.tFPI0G8_I7PUV1itMs0dt626gvWtKgFW6abpBVx8VcQ

Response

Upon response, a redirection to the "Special:Preferences" page for the newly created or updated authenticated user. Concurrently, new cookies are established for the domain, completing the exchange of identity tokens. Optionally, a "returnto" parameter may be utilized to redirect users back to a specific page on the site. It is essential that this parameter is URL-encoded for proper functionality. Example: 

POST @app/auth/token/exchange?returnto=%2FGuide HTTP/1.1

application/json; charset=utf-8

Github example https://github.com/MindTouch/CXOneExpertExamples/tree/main/examples/id-token

Request

Note the content type to ask for a JSON response in return.

POST @app/auth/token/exchange HTTP/1.1
Host: customersite.example.com
Content-Type: application/json; charset=utf-8

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJpYXQiOjE3MTMyMDkwMTEsImV4cCI6MTc0NDc0NTAxMSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiY2JjZGEyYTUtNmZiYS00NjJkLWE4NzYtN2M0ZmM3YzkzNzliIiwiZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsIm5hbWUiOiJqb2huLmRvZUBleGFtcGxlLmNvbSJ9.tFPI0G8_I7PUV1itMs0dt626gvWtKgFW6abpBVx8VcQ
Curl example
curl -X POST \
  http://customersite.example.com/auth/token/exchange \
  -H 'Content-Type: application/json' \
  -d 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJpYXQiOjE3MTMyMDkwMTEsImV4cCI6MTc0NDc0NTAxMSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiY2JjZGEyYTUtNmZiYS00NjJkLWE4NzYtN2M0ZmM3YzkzNzliIiwiZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsIm5hbWUiOiJqb2huLmRvZUBleGFtcGxlLmNvbSJ9.tFPI0G8_I7PUV1itMs0dt626gvWtKgFW6abpBVx8VcQ'

Response

 

The standard user response is retrieved from the endpoint via the "@api/deki/users/current" API call. Cookies will also be set if maintained to before additional requests in a session.

{
  "@anonymous": "false",
  "@id": "5",
  "@guid": "cc3ed824826b4f808d378f9570afa250",
  "fullname": "John Doe",
  "service.authentication": {
    "@id": "2",
    "@href": "https://customersite.example.com/@api/deki/site/services/2"
  },
  "status": "active",
  "username": "cbcda2a5-6fba-462d-a876-7c4fc7c9379b"
}

 

  • Was this article helpful?