Skip to main content

Consent 3.0 Flow

High-level Flow​

The following diagram shows the high-level phases of the Consent 3.0 flow. Detailed step descriptions are provided in the sections below.

Preparation step

The Service User retrieves the list of Service Providers from the bLink Directory. Before showing the list to the end user, the entries are filtered so that only Service Providers appear which:

  1. support Consent Flow 3.0
  2. have an Implementation validity window that includes today’s date
  3. have a Consent Flow 3.0 Configuration Status of CERTIFIED

  1. PAR + PKCE
    The Service User prepares the authorization request securely by generating PKCE parameters and sending a Pushed Authorization Request through bLink. See Details

  2. Authorization and consent
    The end user is redirected to the authorization server, authenticates if required, and approves the consent. The authorization server then returns an authorization code. See Details

  3. Token exchange
    The Service User exchanges the authorization code through bLink and proves possession of the PKCE code_verifier. The token response includes the access token, refresh token, and grant_id. See Details

  4. API call
    The Service User calls bLink with the issued access token, and bLink forwards the request to the Service Provider resource server using the same token. See Details

  5. Refresh Flow When the access token expires, the Service User uses the refresh token through bLink to obtain a new access token. The grant_id remains stable for the same consent. See Details

PAR & PKCE​

  1. The Service User generates a PKCE code_verifier and code_challenge according to RFC7636.
    • The code_verifier MUST be a random string using characters from the unreserved URI set: [A–Z a–z 0–9 - . _ ~]
    • The code_verifier MUST have a length between 43 and 128 characters
    • The code_challenge MUST be derived using S256 (S256 is the only supported code_challenge_method in Consent 3.0.)

Example value:

   code_verifier = dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
   code_challenge = BASE64URL-ENCODE( SHA256( ASCII(code_verifier) ) )
  1. The Service User sends a pushed authorization request to bLink including the code_challenge and code_challenge_method.
POST "api/consent-flow/v3/oauth/par"
-H "Content-Type: application/x-www-form-urlencoded"
-H "X-Correlation-ID: 8a5fdd1d-7e56-45d8-9c55-2cb90b9d72e2"
-H "X-CorAPI-Target-ID: IIDP99999"
-H "X-PSU-IP-Address: 203.0.113.10"
-H "X-PSU-User-Agent: Mozilla/5.0"
-H "User-Agent: MySU/1.0"
--data-binary "response_type=code&client_id=654321&redirect_uri=https%3A%2F%2Fclient.example.com%2Foauth%2Fcb&scope=urn%3Ablink%3Axs2a%3Aais%20urn%3Ablink%3Axs2a%3Apss%3Awrite&state=d60dbae3-b1b2-419c-bc72-1054fab294ec&code_challenge=JPaMZZhWRl4uceYCpN4QV9RFOHV4tlrD-lCUqDUsEh4&code_challenge_method=S256&provider_id=IIDP99999&username=username&grant_management_action=create"

Successful response (201)

{ 
   "request_uri": "urn:ietf:params:oauth:request_uri:OsL1Z3VqIxAT9R77wB7KCw", 
   "expires_in": 60 
}

Error response (400)

{ 
   "error": "invalid_request", 
   "error_description": "missing or invalid code_challenge, redirect_uri, or scope" 
}
  1. bLink forwards the PAR request to the Service Provider authorization server.
  2. The authorization server validates the client, redirect URI, scopes, PKCE parameters, and optional grant management parameters.
  3. The authorization server stores the authorization request and returns a request_uri.
  4. bLink returns the request_uri to the Service User.
  1. The Service User starts the browser-based authorization step using the returned request_uri.
  2. The user agent calls the authorization server with the request_uri.
  3. The authorization server resolves the pushed request and presents the authentication and consent flow.
  4. The end user authenticates if required and approves the consent.
  5. The authorization server stores the consent, creates or updates the grant, and binds it to a stable grant_id.
  6. The authorization server redirects the user agent back to the Service User with an authorization code.
  7. The Service User receives the authorization code.

Token exchange​

  1. The Service User exchanges the authorization code via bLink and includes the PKCE code_verifier.
POST "api/consent-flow/v3/oauth/token"
-H "Content-Type: application/x-www-form-urlencoded"
-H "X-Correlation-ID: 36f3ecb5-89a7-4d53-84f3-8d74be1a19a2"
-H "X-CorAPI-Target-ID: IIDP99999"
-H "X-PSU-IP-Address: AUTO"
-H "X-PSU-User-Agent: AUTO"
--data-binary "grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient.example.com%2Foauth%2Fcb&client_id=654321&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Successful response (200)

{ 
   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.auth123", 
   "token_type": "Bearer", 
   "expires_in": 3600, 
   "refresh_token": "YXV0aC1yZWZyZXNoLXRva2Vu", 
   "grant_id": "3f5dd8a4-7e3a-47af-92e8-2e2bc5bcd011", 
   "scope": "urn:blink:xs2a:ais urn:blink:xs2a:pss:write" 
}

Error response (400)

{ 
   "error": "invalid_grant", 
   "error_description": "authorization code is invalid, expired, or does not match the PKCE verifier" 
}
  1. bLink forwards the token request to the authorization server.
  2. The authorization server validates the authorization code, client, redirect URI, and PKCE verifier.
  3. The authorization server returns the token response including access_token, refresh_token, and grant_id.
  4. bLink forwards the token response to the Service User, which stores the tokens securely.

API call​

  1. The Service User calls bLink with the issued access token.
  2. bLink verifies the Service User authorization and swaps the blink-issued access token for the Service Provider access token.
  3. bLink forwards the request to the Service Provider resource server:
    • CaaS clients: bLink swaps the Service User access token for the internal Service Provider token and sends the Service Provider token to the RS.
    • CF clients: bLink forwards the Service User access_token unchanged (pure forwarding).
  4. The resource server validates the Service User access token.
  5. The resource server returns the business response.
  6. bLink forwards the response to the Service User.

Refresh Flow​

The refresh flow differs depending on whether the Service User is a CaaS or CF client:

  • CF clients:
    bLink forwards the refresh request unchanged to the Service Provider.
    The Service Provider returns new tokens (including a grant_id if migrating from CF2), and bLink returns them directly to the CF client.

  • CaaS clients: The Service User presents the bLink-issued refresh_token.
    bLink converts this into a refresh request to the SP using the internal Service Provider-issued refresh token, receives the Service Provider tokens, and issues new bLink tokens back to the Service User.

CF Refresh Flow (native Service Provider tokens, no token swap)​

The following steps describe the generic refresh behavior. For CaaS, bLink uses internal Service Provider tokens, for CF, bLink forwards the refresh request unchanged.

  1. The Service User refreshes tokens via bLink using the refresh token.
POST "api/consent-flow/v3/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Correlation-ID: 2b2a22c4-3a51-46a5-8f2f-c3b6f3ac21a9" \
  -H "X-CorAPI-Target-ID: IIDP99999" \
  -H "X-PSU-IP-Address: AUTO" \
  -H "X-PSU-User-Agent: AUTO" \
  --data-binary "grant_type=refresh_token&refresh_token=dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4="

Successful response (200)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.new456",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dXBkYXRlZCByZWZyZXNoIHRva2Vu",
  "grant_id": "3f5dd8a4-7e3a-47af-92e8-2e2bc5bcd011",
  "scope": "urn:blink:xs2a:ais urn:blink:xs2a:pss:write"
}

OAuth error response (400)

{
  "error": "invalid_grant",
  "error_description": "refresh_token expired or revoked"
}
  1. bLink forwards the refresh request to the authorization server.
  2. The authorization server returns a new access token and optionally a new refresh token, while keeping the same grant_id for the same consent.
  3. The Service User updates its token store.
Last updated on