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