OIDC Frontend flow Authentication

The OIDC Authorization Code Flow is a secure way to obtain an access token in a frontend application running on the user device. It is based on the OAuth 2.0 Authorization Code Flow. Note that some APIs require the use of PKCE (Proof Key for Code Exchange) extension. This is specified in the documentation of each API. You can find more information about how to use PKCE below in the document.

The base URL of the authorization server is provided in the description of each API.

The following steps describe how to implement the OIDC Authorization Code Flow to obtain a token in a frontend application.

The Application on the Consumption Device must be able to handle HTTP redirections (302 redirect).

Step 1: Retrieve the Authorization code

The API invoker (for example, the Application Backend) instructs the Application on the Consumption Device to initiate the OIDC Authorization Code Flow with the Operator. The authorization request must include various parameters.

Authorization code request parameters

client_id: The client_id of the ASP's Application requesting access to the API.
redirect_uri: The Application's redirect_uri (invoker_callback) where the authorization code will be sent.
scope: It is mandatory to provide a scope parameter with the value openid dpv:<dpvValue> <technicalParameter>. Orange implementation follows the CAMARA scope definition. The values to use are specified in the documentation of each API.
- dpv stands for Data Privacy Vocabulary, for example FraudPreventionAndDetection
- technical parameters are the data claims by the API consumer, for example number-verification:verify
response_type: The response_type parameter must be set to code.
code_challenge (only with PKCE): The code_challenge parameter is used to secure the Authorization Code Flow with PKCE. The code_challenge is created from a randomly generated code_verifier that will be use in the next step.
code_challenge_method (only with PKCE): The hashing method used to create the code_challenge. It must be set to S256.
state (optional): An opaque value used by the client to maintain state between the authorization code request and the callback. The authorization server includes this value when redirecting the user-agent back to the client.

Handling the response

Once the consumption device has executed the request, it will be redirected to the redirect_uri specified in the request parameters.

If successful the URI will contain the following parameters:

code: The code to use in the next step to retrieve the access token.
state: The opaque value set by the client in the request.

In case of error the callback URI will contain the following parameters:

error: the error code
error description (optional): Human readable description of the error.

If the requested scope requires the end-user consent, an intermediate redirect will present a consent page on which the end-user can give (or reject) its consent.

Sample code request

curl --get <authorization server base url>/authorize \
--data-urlencode 'client_id=<your client id>' \
--data-urlencode 'redirect_uri=<your redirect uri>' \
--data-urlencode 'scope=openid dpv:<dpvValue> <technicalParameter>' \
--data-urlencode 'response_type=code' \
--data-urlencode 'code_challenge=<derived code challenge>' \
--data-urlencode 'code_challenge_method=S256'

Step 2: Retrieve the access token

Once the client backend application obtains the authorization code, it must retrieve the access token, which grants access to the protected resources. To do so, the client application triggers a POST request to the token endpoint.

This endpoint is authenticated and the API consumer must authenticate itself using Basic authentication. To do so, the Authorization HTTP header must be populated with Basic base64_encode(client_id:client_secret).

Access token request parameters

grant_type: The value of this parameter must be authorization_code.
code: The authorization code received during the previous step from the authorization server.
redirect_uri: The redirect URI used in the authorization request.
code_verifier (only with PKCE): Following PKCE usage, the code_verifier must be provided in the request. Orange Exposure Platform will check this value with the code_challenge provided in the /authorize request.

Handling the response

If the transaction is successful, the POST response includes the following parameters:

acccess_token: The token used to access API resources.
token_type: The type of the token (e.g. Bearer).
expires_in: The validity time of the token in secondes.

Sample token request

curl -X POST \
  <authorization server base url>/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  -u '<your client id>:<your client secret>' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=<your redirect uri>' \
  --data-urlencode 'code=<code obtained from previous step>' \
  --data-urlencode 'code_verifier=<randomly generated code verifier>'

PKCE in a nutshell

PKCE (Proof Key for Code Exchange) is an extension of OAuth 2.0 designed to enhance security during authentication, especially for public clients like mobile apps and SPAs.

For more details, refer to the RFC 7636 OAuth PKCE specification.

How it works

Generate a Code Verifier: A high-entropy, randomly generated string, approximately 43 to 128 characters long as the code_verifier.
Create a Code Challenge: The code_verifier is hashed using SHA-256 and then Base64 URL-safe encoded to create the code_challenge.
Authorization Request: The code_challenge is sent to the authorization server during the authorization request.
Token Request: The code_verifier is sent to the token endpoint during the token request.

Usages Steps Sample Code

1. Generate the code verifier and code challenge

import os
import hashlib
import base64

# Generate code verifier
code_verifier = base64.urlsafe_b64encode(os.urandom(40)).rstrip(b'=').decode('utf-8')

# Create code challenge
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode('utf-8')).digest()
).rstrip(b'=').decode('utf-8')

2. Initiate the authorization request

Include the code_challenge in the authorization URL:

https://authorization-server/auth?
response_type=code
&client_id=<your client id>
&redirect_uri=<your redirect uri>
&scope=openid dpv:<dpvValue> <technicalParameter>
&code_challenge=<code challenge>
&code_challenge_method=S256

3. Obtain the authorization code

The user grants permission, and the server redirects to your redirect_uri with an authorization code.

4. Exchange the code for tokens

Make a POST request to the token endpoint with:

code
redirect_uri
client_id
code_verifier

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "client_id": "YOUR_CLIENT_ID",
  "code_verifier": "CODE_VERIFIER"
}

On this page

Step 1: Retrieve the Authorization code
Step 2: Retrieve the access token
PKCE in a nutshell
- How it works
- Usages Steps Sample Code