Skip to main content

Integrating a Client with the Authorization Server

The Client (also known as the consumer or service provider) wants to provide services to end-users. To this end, they often require attributes and access to APIs from third parties. For example, in order to create a new trusted "doctor" account, the Client may need a doctor's provincial/state license number from an FHIR Repository hosted by a trusted provincial/state hospital. The FPX (Federated Privacy Exchange) network allows a Client to ask for vetted, trustworthy sources for the resources they need, along with the authorization to retrieve them. Rather than set up many connections with many resource servers, a Client only needs to connect to a single entity, the FPX Authorization Server (AS). The interface exposed to the Client supports OAuth 2.0 protocol as well as OAuth extensions such as User-Managed Access (UMA) 2.0 and OpenID Connect (OIDC).

Abstract Flow​

The Client follows an OAuth 2.0 Authorization pattern (see Figure 1). First, it requests access to resources specified in one of their capability tickets (set of resources) from the Authorization Server (1). After the end-user interacts with the Authorization Server to fulfill the ticket, the Client receives a callback with an authorization grant (2). The Client can redeem the ticket for a set of access tokens, and then use those access tokens directly with the resource server (3) to receive the protected resource owned by the end-user (4). This chapter will cover all of these steps from the perspective of an FPX UMA flow using a Capability Ticket, a standard OAuth 2.0 or an OIDC flow using the Authorization Code grant type.

Abstract Client Seeks Authorization of Protected Resources at Many RSs

Steps involved in a typical end-to-end execution of an FPX UMA, OAuth or OIDC flow are:

1. Register and Configure Client​

Before the Client can issue a capability ticket request to the Authorization Server, there are two prerequisite steps:

  • Client Registration and
  • Capability Ticket Registration

Client Registration​

The Client must be registered as an OAuth 2.0 Client with the Authorization Server which includes a client identifier and the location of the client's publicly exposed JSON Web Key Set. It is possible to provide a shared secret to the client. However, this is strongly discouraged in production environments. Additionally, the client will need to provide the list of redirect URLs that are allowed to receive the callback from the Authorization Server. For more details on how to register a new Client, refer to Configuring a Client via API

Capability Ticket Registration​

A capability ticket represents a set of resource types and scopes that the Client can request from an end-user, along with a public name and purpose for the resources within the request. When the Client makes an authorization request, it includes one of its registered tickets.

For example, a digital prescribing app may request a capability ticket to be created that allows them to request access to both the FHIR repository type, and the FHIR Practitioner resource type, both with the scope "read". These resource types are required to verify that the end-user is a valid physician in the region, and grant access to pull clinical data. The network operator would review and register a unique capability ticket ID for the Client to request that specific set of resource types and scopes from the user.

IMPORTANT

If the client chooses to integrate with the Authorization Server using OAuth, the ticket must still be registered and the 'id' of the ticket will be used as the value for the scope parameter for any OAuth calls made to the AS.



2. Authorize Client​

During an authorization transaction, the Client uses two endpoints at the Authorization Server:

  1. An end-user-facing endpoint that users will be redirected to complete an authorization request, and
  2. A back-channel request to receive access tokens after the request is completed.

The client may also use the well-known (i.e. metadata) endpoints at the Authorization Server to determine the public configuration of the Authorization Server. Depending on the flow selected (FPX UMA, OAuth, or OIDC), the calls made for the Authorize Client step will differ slightly.

Execute the following call for the FPX UMA flow:

GET /transaction/authorize

The Client directs a user to complete an authorization request at the Authorization Server through their web browser, typically via a hyperlink or directly redirecting the user to it. The request includes a UMA 2.0 ticket and required OAuth 2.0 parameters. Once the request is processed and verified by the Authorization Server (an instantaneous process), the user will be redirected to the Wallet configured at the server to authorize the disclosure of the requested resources. 

https://{AuthorizationServer_base_url}/transaction/authorize?&ticket=read-ticket&client_id=fp_client_id&state=1654184497&claims_redirect_uri={Client_redirect_url}
ParameterRequiredDescription
ticketYESIdentifier of registered capability ticket.
claims_redirect_uriYESOne of the registered redirect URIs.
client_idYESOAuth 2.0 Client ID.
stateYESOpaque string to associate the authentication request during the callback.
login_hintNOOptional Wallet ID to pre-select a specific Wallet where multiple may be configured at the Authorization Server.


Optionally, the Client may use Proof Key for Code Exchange also as known as PKCE. PKCE is an OAuth 2.0 security extension for public clients intended to avoid a malicious program from intercepting the authorization code.

Important

PKCE is mandatory for all Public clients (using the code_challenge and code_challenge_method parameters) for an added layer of security.
For confidential clients who are able to perform private key authentication, PKCE is optional but recommended. It can be enforced for confidential clients by setting the fpx.oidc.provider.pkce.enforced value to 'true' when configuring the Authorization Server.

ParameterRequiredDescription
code_challengeYESThe code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier
code_challenge_methodYESThe hash function used to generate code challenge from the code verifier. Must be S256.

Sample Request using PKCE

https://{AuthorizationServer_base_url}/transaction/authorize?&ticket=exampleticket&client_id=exampleclient&state=randomvalue&claims_redirect_uri={Client_redirect_url}&code_challenge_method=S256&code_challenge=nxAvddK_1ECz_2oDLMevOnJbjPEBeNSEbdx96iuqVJg

3. Client Callback and Authorization Code from the Authorization Server​

When the Authorization Server processes the authorization request and it's been approved or denied by the user, the Authorization Server redirects the user agent to the client redirect URI.

When the user approves the authorization request, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with a Permission ticket value.

A typical response would be as below based on the redirect URI passed in the authorize step above:

https://{Client_redirect_url}?ticket=361e4986-56b2-446f-9718-b3794305f388&state=1654029277

4. Access Token Request​

The client application requests an access token from the API by passing either the ticket or the authorization code that was returned during the callback along with the authentication details.

For the FPX UMA flow, the POST /transaction/token call is used.
For the OAuth flow or the OIDC flow the POST /oauth2/token call is used.

The client uses the FPX UMA ticket to make a back-channel request for the access tokens at the token endpoint that it can then use to request resources.

This endpoint requires authentication and two methods are supported by the Authorization Server.

It is strongly suggested for security reasons to use JWT authentication as no credentials need to be exchanged between parties. Verification is achieved through the verification of cryptographic signatures.

JWT Authentication​

It is strongly suggested to make use of a library to handle the signing and verification of JWTs. See JWT Libraries for packages available in different languages.

To use JWT authentication, the Client must build a JWT containing a specific set of claims and signed with the private key that can be verified by the Authorization Server using the public key set provided during registration.

{
  "iss": "exampleclient",
  "sub": "exampleclient",
  "aud": "https://{AuthorizationServer_base_url}/transaction/token",
  "exp": 1619831987,    // JWT expiry - should be a future timestamp
  "iat": 1619826987,    // JWT valid from - should be in the past
  "jti": "abcdef123456" // must be unique per request
}

The Access Token Request and Refresh Token Request calls under the JWT Authentication method differ slightly for the FPX UMA flow and the OAuth 2.0 flow. Select the appropriate tab for more information.

For the FPX UMA flow, the POST /transaction/token call is used.

Access Token Request​


Request Parameters (JSON Data)

ParameterRequiredDescription
grant_typeYESmust be 'urn:ietf:params:oauth:grant-type:uma-ticket'
ticketYESThe OAuth 2.0 ticket received by the client's callback URI. Note: This not the same as the capability ticket originally sent by the client to the Authorization Server.
client_assertion_typeYESMust be set to 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'.
client_assertionYESJWT signed with private key containing required claims.

Sample Request

curl -X POST https://{AuthorizationServer_base_url}/transaction/token -H "Content-Type: application/json" --data '{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket": "226A2331-73FC-4087-9B07-56E41E49DA02",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRGf"
}'

If the initial request was made using PKCE, the token endpoint must also include the code verifier.

KeyRequiredDescription
code_verifierYESThe code challenge in the initial authorized request is the BASE64-URL-encoded string of the SHA256 hash of the code verifier.

Sample Request

curl -X POST https://{AuthorizationServer_base_url}/transaction/token -H "Content-Type: application/json" --data '{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket": "226A2331-73FC-4087-9B07-56E41E49DA02",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRGf",
  "code_verifier":"C4ZrQS1sfnvUsJrrWhWLE3RukRwLcnfINKrLfyXqIBz"
}'
NOTE

The client assertion JWT shown here is for demonstration purposes only and is not valid.

Refresh Token Request​

The access tokens provided by the token endpoint will expire quickly. In order to receive new access tokens, a subsequent request to this endpoint should be made using the refresh token.


Request Parameters (JSON Data)

KeyRequiredDescription
grant_typeYESMust be 'refresh_token'
refresh_tokenYESThe refresh token received from a previous call to the token endpoint.
client_assertion_typeYESMust be set to 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'.
client_assertionYESJWT signed with private key containing required claims.

Sample Request

curl -X POST https://{AuthorizationServer_base_url}/transaction/token -H "Content-Type: application/json" --data '{
  "grant_type": "refresh_token",
  "refresh_token": "226A2331-73FC-4087-9B07-56E41E49DA02",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRGf"
}'

Shared Secret Authentication​

While supported, OAuth Shared Secret is not recommended for production workloads. It can be useful for proof of concept or other internal purposes.

The Access Token Request and Refresh Token Request calls under the Shared Secret Authentication method differ slightly for the FPX UMA flow and the OAuth 2.0/OIDC flows. Select the appropriate tab for more information.

Access Token Request​

Request Headers

KeyRequiredDescription
AuthorizationYESBase64 encoded string containing client id and secret separated by a colon as HTTP Basic Authorization token.

Request Body

KeyRequiredDescription
grant_typeYESMust be 'urn:ietf:params:oauth:grant-type:uma-ticket'
ticketYESThe ticket (OAuth 2.0 auth_code) received by the client's callback URI. Note: This is not the same as the capability ticket originally sent by the client to the Authorization Server
code_verifierNORequired if the request was initiated using PKCE. The code challenge in the initial authorized request is the BASE64-URL-encoded string of the SHA256 hash of the code verifier.

Sample Request

curl -X POST https://{AuthorizationServer_base_url}/transaction/token -H "Content-Type: application/json" -H "Authorization: Basic dGVzdC1pZGVudG9zLWNsaWVudDp0asicZXN0LWlkZW50b3Mtc2VjcmV0" --data '{
  "grant_type":"urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket":"43fd5565-c722-4b89-983a-f05f10df1742"
}'

Sample Request with PKCE code Verifier

curl -X POST https://{AuthorizationServer_base_url}/transaction/token -H "Content-Type: application/json" -H "Authorization: Basic dGVzdC1pZGVudG9zLWNsaWVudDp0asicZXN0LWlkZW50b3Mtc2VjcmV0" --data '{
  "grant_type":"urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket":"43fd5565-c722-4b89-983a-f05f10df1742",
  "code_verifier":"7uciLUrALDEyeKgMzyfK7kzMkBpJPsw1CLXxoUtJtb9"
}'

Refresh Token Request​

The access tokens provided at this endpoint will expire quickly. In order to receive new access tokens, a subsequent request to this endpoint should be made using the refresh token.

Request Headers

KeyRequiredDescription
AuthorizationYESBase64 encoded string containing client id and secret separated by a colon as HTTP Basic Authorization token.

Request Parameters (JSON Data)

KeyRequiredDescription
grant_typeYESMust be 'refresh_token'.
refresh_tokenYESThe refresh token received from a previous call to the token endpoint.

Sample Request

curl -X POST https://{AuthorizationServer_base_url}/transaction/token -H "Content-Type: application/json" -H "Authorization: Basic dGVzdC1pZGVudG9zLWNsaWVudDp0asicZXN0LWlkZW50b3Mtc2VjcmV0" -H "Content-Type: application/json" --data '{
  "grant_type": "refresh_token",
  "refresh_token": "226A2331-73FC-4087-9B07-56E41E49DA02",
}'

Response​

On successful authorization, the Authorization Server returns an access_token as a signed JWT. The client should verify the signature using the Authorization Server's key set before processing the payload. The access token requires further processing before it can be used to request the resources granted by the user to the client.

KeyDescription
access_tokenThe JWT from the Authorization Server. The client must process the JWT to uncover the authorized Resource Servers for each required resource.
expires_inSeconds before the token will expire.
token_typeThe access token type. Will be 'fpx:rpt.rs.location.token'.

Sample Response

{
    "access_token": "eyJraWQiOiJyc2ExIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI0MzNjZjY1Zi03MDJiLTQ1MGEtYmRhYi03MDJkMGZkYTNiNDQiLCJhdWQiOiJmcHhzcF9jbGllbnRfaWQiLCJpc3MiOiJodHRwczpcL1wvYXV0aHNlcnZlci5hcy0xNjUzLmRldi5pZGVudG9zLmNhIiwiZXhwIjoxNjYxMDg3MzMxLCJpYXQiOjE2NjA4MjgxMzEsImFjY2Vzc190b2tlbnMiOlt7ImFjY2Vzc190b2tlbiI6ImV5SnJhV1FpT2lKeWMyRXhJaXdpZEhsd0lqb2lTbGRVSWl3aVlXeG5Jam9pVWxNeU5UWWlmUS5leUp6ZFdJaU9pSmxlVW93WlZoQmFVOXBTa3RXTVZGcFRFTkthR0pIWTJsUGFVcEpWWHBKTVU1cFNqa3VaWGxLYUdSWFVXbFBhVXB2WkVoU2QyTjZjR05NTVhkMll6SXhjR0pIVm1wYVNFbDFXVmhOZEUxVVdURk5lVFZyV2xoWmRXRlhVbXhpYmxKMlkzazFhbGxUU1hOSmJrNHhXV2xKTmtscll6SmplbFo1VXpBMWRWTnNUbEpWTWxaSVZVaFdWR0ZVYkdsaGVrSk5WRWhLYms5VVJuZFNNMmhJVG1wc2FGcFVRbmxOUm5CVlZVWnNlV0l6Y0doamJrWkRUak5LV2xVd1VYaFVhemxEVGpBNWQyVlZUV2xNUTBwNVdsaE9kbVJZU21wYVZqbDJaREkxYkdOcFNUWkpha0pvVGtSb2JVNVVRVFZNVjFrd1RXcG5kRTVFV21wT2FUQTBXbGRKTlV4VVVtdFBWRmwzVDFkTmQwMVVXbTFaYVVselNXMXNlbU41U1RaSmJXZ3daRWhDZWs5c2QzWllRemt6V1ZkNGMxcFlVWFZaV0UxMFRWUlpNVTE1Tld0YVdGbDFZVmRTYkdKdVVuWmplVFZxV1ZOSmMwbHVTbXhqTWpreFkyMU9iRmd5Ykd0SmFtOXBZMjFXZW1JelZubFpNbFptWVZkUmFVeERTbTVqYlVaMVpFZFdhMWd6VG1waU0wSnNZM2xKTmxkNVNubGFWMFpyU1d3d2MwbHVValZqUjFWcFQybEtkMXBZU25SaFdFNTZZVmM1ZFVscGQybGFXR2gzU1dwdmVFNXFXWGRQUkVrMVQxUkJla3hEU21waVIyeHNZbTVTWm1GWFVXbFBhVXB0WTBob2VtTkdPVEZpVjBabVdUSjRjRnBYTlRCSmJqQXVhMXBOYTB0NFdFNTNRbkpzZFdzM1dURmFZWEl3WTIwMWJFVmtOMWR1ZUhObWJsQTVZbG80VVRSeFVTSXNJbUYxWkNJNkltaDBkSEJ6T2x3dlhDOXpiV2xzWldOa2NpNWhjeTB4TmpVekxtUmxkaTVwWkdWdWRHOXpMbU5oSWl3aWNHVnliV2x6YzJsdmJuTWlPbHQ3SW5OMVlpSTZJbVY1U2pCbFdFRnBUMmxLUzFZeFVXbE1RMHBvWWtkamFVOXBTa2xWZWtreFRtbEtPUzVsZVVwb1pGZFJhVTlwU205a1NGSjNZM3B3WTB3eGQzWmpNakZ3WWtkV2FscElTWFZaV0UxMFRWUlpNVTE1Tld0YVdGbDFZVmRTYkdKdVVuWmplVFZxV1ZOSmMwbHVUakZaYVVrMlNXdGpNbU42Vm5sVE1EVjFVMnhPVWxVeVZraFZTRlpVWVZSc2FXRjZRazFVU0VwdVQxUkdkMUl6YUVoT2FteG9XbFJDZVUxR2NGVlZSbXg1WWpOd2FHTnVSa05PTTBwYVZUQlJlRlJyT1VOT01EbDNaVlZOYVV4RFNubGFXRTUyWkZoS2FscFdPWFprTWpWc1kybEpOa2xxUW1oT1JHaHRUbFJCTlV4WFdUQk5hbWQwVGtSYWFrNXBNRFJhVjBrMVRGUlNhMDlVV1hkUFYwMTNUVlJhYlZscFNYTkpiV3g2WTNsSk5rbHRhREJrU0VKNlQyeDNkbGhET1ROWlYzaHpXbGhSZFZsWVRYUk5WRmt4VFhrMWExcFlXWFZoVjFKc1ltNVNkbU41TldwWlUwbHpTVzVLYkdNeU9URmpiVTVzV0RKc2EwbHFiMmxqYlZaNllqTldlVmt5Vm1aaFYxRnBURU5LYm1OdFJuVmtSMVpyV0ROT2FtSXpRbXhqZVVrMlYzbEtlVnBYUm10SmJEQnpTVzVTTldOSFZXbFBhVXAzV2xoS2RHRllUbnBoVnpsMVNXbDNhVnBZYUhkSmFtOTRUbXBaZDA5RVNUVlBWRUY2VEVOS2FtSkhiR3hpYmxKbVlWZFJhVTlwU20xalNHaDZZMFk1TVdKWFJtWlpNbmh3V2xjMU1FbHVNQzVyV2sxclMzaFlUbmRDY214MWF6ZFpNVnBoY2pCamJUVnNSV1EzVjI1NGMyWnVVRGxpV2poUk5IRlJJaXdpY21WemIzVnlZMlZmYzJOdmNHVnpJanBiSW5KbFlXUWlYU3dpY21WemIzVnlZMlZmZEhsd1pTSTZJbWgwZEhCek9sd3ZYQzl2Y0dWdWFXUXVibVYwWEM5emNHVmpjMXd2YjNCbGJtbGtMV052Ym01bFkzUXRZMjl5WlMweFh6QXVhSFJ0YkNJc0luSmxjMjkxY21ObFgybGtJam9pY21WemIzVnlZMlZmYVdRaUxDSmxlSEFpT2pFMk5qTTRNamd4TVRKOVhTd2lZWHB3SWpvaVpuQjRjM0JmWTJ4cFpXNTBYMmxrSWl3aWFYTnpJam9pYUhSMGNITTZYQzljTDJGMWRHaHpaWEoyWlhJdVlYTXRNVFkxTXk1a1pYWXVhV1JsYm5SdmN5NWpZU0lzSW1WNGNDSTZNVFkyTURnek1UY3pNU3dpYVdGMElqb3hOall3T0RJNE1UTXhmUS5IWFBRYmk2UUZHdTNDRW80bHVaR0ZYMGJjdEs2QTJnWENOb19oV2p1Znlqd3FobVJIcDZoMzRSb3BUdDZlbGhDZVhORS1rYlBjZmo1b0FYdkVHNURGeUk4X2J2VDhzemZOd1JIc2Z4OUQxaFJDR0k2TlpKNU1FM3lqVlNaODZtZlJFb2V1WFZqUGl5RHJxdVVJRm43Q2dFbFh3cWYxLXZkRXpEblp4NWIwSFpOeEROZld6aF95bGhDT2RpZUxiOTZsaFhfMzEzSXBaRGY3VzY4dnlMZTltTGFUSVpMc1ZvZzdjcU5iZkJyMVlXeW9QQTJYcUx5eHYtSzdlblVQbHA3eElJVmgzT05EQVNNeGp3VGo3UWJDWm45QzNlRk9ncXR0ci1pc19BTEVhbWlXNHktUmtTdFhkSV96WURlYlAyRTNIbE5YQ0NMM2ZLb3otTVhMclMweWciLCJyZWZyZXNoX3Rva2VuIjoiMTk0NjczODMtY2RjZC00NWNkLWE4YzQtMmU4MDM3YmRhOGE5IiwicmVzb3VyY2VfdHlwZSI6Imh0dHBzOlwvXC9vcGVuaWQubmV0XC9zcGVjc1wvb3BlbmlkLWNvbm5lY3QtY29yZS0xXzAuaHRtbCIsInJlc291cmNlX2lkIjoicmVzb3VyY2VfZGVmX2lkIiwidG9rZW5fdHlwZSI6ImJlYXJlciIsImV4cGlyZXNfaW4iOiIzNTk5IiwicmVzb3VyY2VfbG9jYXRpb24iOiJodHRwczpcL1wvc21pbGVjZHIuYXMtMTY1My5kZXYuaWRlbnRvcy5jYVwvYXBpXC91c2VyaW5mbyJ9XX0.eOS8Bw7HUcVa5BhTkcT8_FTeggiteRqQGqtazQrMCKmdgp96056grUUP9jDiq6zu1rE7-Af5zdumrMscr-gfIdnTD4Sp-4GsoNVXxvLzS0bIwb_kXxcaWUacVOHR9S1ToBA4Op8wMSih9a8LxzDeB01aaINncqos8_m79eFey6JWuIvCGcgSUwLxkB74std6hUNcKgHIo1XvzApK1dGMuYDmy3z7MJ0FmGmtxyjIsG2keaEb7_yciq85A6NAUU7BTI2c432GlCsTqxgpjQDqmpe7YWtnR1mZcoefh0wyKu_uc7NO8KiG-QJa3a2x_k2Xa8PvS9MXxv-axzZiqT5I4g",
    "expires_in": 259199,
    "token_type": "fpx:rpt.rs.location.token"
}


note

The JWT shown is for illustrative purposes only and is not valid as it is typically 4kb in length.

When the JWT contained within the access token is decoded, it has the following claims:

Claims

issThe JWT issuer. Must be the base URL of the Authorization Server.
audMust be the Client ID
subThe ticket (OAuth 2.0 auth_code) that was sent to the Authorization Server.
iatTime the JWT was issued.
expTime the JWT will expire.
access_tokensAn array of access tokens - one for each of the resources granted access to. Format is described in the next table.

Access Token Array Element

resource_locationThe location of the resource server authorized to disclose this resource.
access_tokenAccess token to use when requesting this resource from the Resource Server.
refresh_tokenRefresh token to use to request new access tokens after the initial one has expired.
resource_typeThe type of resource that this access token grants access to will be a URI.
resource_idIdentifier of the requested resource.
token_typeWill have the value “Bearer”.
expires_inValidity of the access token in seconds.

Sample Payload

{
  "sub": "43fd5565-c722-4b89-983a-f05f10df1742",
  "aud": "test-identos-client",
  "iss": "https://authserver.fpx-staging.dev.identos.ca",
  "exp": 1620089222,
  "iat": 1619830022,
  "access_tokens": [
    {
      "access_token": "eyJraWQiOiJyc2ExIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpJVXpJMU5pSjkuZXlKaGRXUWlPaUiJodHRwczpcL1wvYXV0aHNlcnZlci5mcHgtc3RhZ2luZy5kZXYuaWRlbnRvcy5jYSIsImV4cCI6MTYxOTgzMDMyMiwiaWF0IjoxNjE5ODMwMDIyfQ.nJwzc8wonnmUM8b6JglLJaWHEE9pLpKgZ5kt7rU1z6NCycr4K99QpcIH9QAoK8aB08OWawjmtGYmfp9tDxfgwilO6kV0qTRV6UTP1SAqxh_7sNVGA",
      "refresh_token": "e6988f13-aa9e-421b-b1de-8abaf5484c34",
      "resource_type": "https://www.identos.com/resource-definitions/identity-profile",
      "resource_id": "id-profile",
      "token_type": "bearer",
      "expires_in": "299",
      "resource_location": "https://idstore.rs.dev.identos.ca/auth/realms/user-portal/identity"
    }
  ]
}

Failure Response​

If an error occurred or the end-user did not grant the client access, the Authorization Server will return an error code and description to the Client.

Sample Response

{
    "error": "request_denied",
    "error_description": "request was denied, no permissions granted"
}

Resource Server API​

Once the Client has an access token and locations representing the requested resources, interactions between the Client and RS are largely out of scope. When making requests to/for protected resources, the Client MUST include the correct Bearer token from within the Access Token Payload.

HeaderRequiredDescription
AuthorizationYESOAuth 2.0 Bearer Token.

The response will vary depending on the individual resource scope. See the details for the specific resource type that is being requested.

It is important to note that at any time the end user who has granted resources has the ability to revoke access to resources for any one client. In this case it may be required to re-ask the user to provide authorization to these resources again and starting the flow over.

Token Revocation​

Token Revocation enables clients to revoke an access token they no longer need. Token Revocation disables the submitted token, refresh token, and any other associated access tokens that are issued. Once a token gets revoked, it will no longer serve to access the Resource Server API, as the token will fail introspections at the Authorization Server.

A client can revoke a token by sending an access token or the associated refresh token to the defined endpoint, that is POST /oauth2/token/revoke

The endpoint requires client authentication - either JWT or Shared Secret Authentication as described above.

Request Parameters (JSON Data)

KeyRequiredDescription
tokenYESAn access token or refresh token that is retrieved from the token endpoint
token_type_hintSometimesMust be one of: 'access_token', 'refresh_token', or 'fpx:rpt.rs.location.token'. Only required if token value being revoked is the top-level token returned by the FPX UMA 2.0 token response (type is 'fpx:rpt.rs.location.token')
note

When revoking a token of type fpx:rpt.rs.location.token, it is required to provide the token_type_hint. This hint corresponds to the top-level token returned by the FPX UMA 2.0 token response. The RPTs nested in that top-level token may be revoked without a hint, or using the access_token hint

Sample Request

curl --location --request POST 'https://{authserver-base-url}/oauth2/token/revoke' \
--header 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<TOKEN VALUE>' \
--data-urlencode 'token_type_hint=access_token'

Response

On successful revocation, the Authorization Server returns a '200' status code.

References​