Identity Token Exchange

Last updated
Save as PDF

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

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

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

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

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"
}