Authorization code grant flow without proof key for code exchange

Introduction

While the traditional authorization code flow remains a valid method for web applications, it is highly recommended to adopt Proof Key for Code Exchange (PKCE). By using PKCE, you ensure a more robust and secure implementation of the OAuth 2.0 protocol.

But the OAuth 2.0 specification allows to obtain a token pair via authorization code flow even without PKCE as well. If the external system/application is unable to enhance to support PKCE, then this method can be used.

It consists of the following steps:

Step 1: Authorizing the user

The URL of the Pagero Login page is:

https://sso.pageroonline.com/oauth/v2/oauth-authorize

Request method: GET

Required query parameters:

Parameter	Description
`response_type`	Should be set to `code` to generate an `authorization_code`.
`redirect_uri`	The client URI where the user will be redirected after successfully providing credentials. This URI must be the one that was agreed upon when the client was registered. Note: This URI should be URL-encoded with `UTF-8` to ensure it is correctly processed.
`client_id`	The client ID.

Optional query parameters:

Parameter	Description
`state`	Returned to the client in the final redirect to track the session or prevent unauthorized requests.
`scope`	The scopes must be separated by spaces. These scopes must be a subset of the scopes configured on the client. Possible values: - `all`: Default value - `openid`: If set, it will provide an additional `id_token` property along with the `access_token` and `refresh_token` in the response
`prompt`	Specifies whether the authorization server prompts the user login for re-authentication. Possible values: - `login`: Force the user to re-authenticate, ensuring that the person using the application is the legitimate owner of the account.

Example

https://sso.pageroonline.com/oauth/v2/oauth-authorize?response_type=code&client_id=test-client&redirect_uri=https://urltoclient:4443

Step 2: Obtaining authorization code

Upon successful login, the authorization_code is posted back as a query parameter to the url defined in the redirect_uri query parameter.

Response Structure:

Parameter	Description
`state`	Matches the value provided in the initial request. Used to align the request with the redirect response.
`iss`	Identifier of the authorization server where the request was sent.
`code`	A code used for authorization, utilized in the token request.

Example

https://urltoclient:4443/?code=0F7ijeaW4BCwhvyg6ozY9PeLsFF6KUi1&state=exampleState&iss=https%3A%2F%2Fauthorization-server.com

Step 3: Exchanging to a token

Using the authorization_code, it’s now possible to obtain an access_token and a refresh_token.

Important

The refresh token is issued with a rolling lifetime of three years, allowing it to generate new access tokens continuously within this period. After three years, user authentication will be required to obtain a new refresh token.

The URL for doing so is:

https://sso.pageroonline.com/oauth/v2/oauth-token

Request method: POST

Required parameters in application/x-www-form-urlencoded:

Parameter	Description
`grant_type`	Should be `authorization_code`.
`code`	The authorization code.
`redirect_uri`	Must be identical to the redirected uri that was provided in the first step above.
`client_id`*	The client ID.
`client_secret`*	The client secret.

Required headers (if not client_id and client_secret provided in the body):

Header	Description
`Authorization`	Authorization header for basic authorization, where the user should be the client id and password should be the client secret.

Response Structure:

Parameter	Description
`access_token`	A freshly generated JSON Web Token (JWT)
`refresh_token`	A freshly generated refresh token
`expires_in`	Time in seconds until expiration
`scope`	A string with space-separated values
`token_type`	Bearer or another type of token
`id_token`*	A signed JSON Web Token (JWT) containing user information like `email` and this is only present if the `scope` is set to `openid`

Example with header option

Example with curl
curl https://sso.pageroonline.com/oauth/v2/oauth-token \
  -d 'grant_type=authorization_code' \
  -d 'code=0F7ijeaW4BCwhvyg6ozY9PeLsFF6KUi1' \
  -d 'redirect_uri=https://urltoclient:4443' \
  --user 'client-id:client-secret'  

The response will contain a JSON body that looks like this (when scope is set to all):

{
  "token_type": "bearer",
  "access_token": "eyJraWQiOiIxNTUzNzgyMDQxIiwieDV0IjoiYldvWF...",
  "refresh_token": "_1XBPWQQ_e61b091b-9139-4268-a7c7-765d2d418d52",
  "scope": "",
  "claims": "publicid",
  "expires_in": 600
}

Note

The access_token value is redacted for brevity. The actual JWT that is issued will be longer.

Making an API request using an access token

When making an API request, the access token should be provided in an Authentication header as a bearer token.

Example with curl
curl https://api.pageroonline.com/someresource \
  -H 'Authorization: Bearer eyJraWQiOiIxNTUzNzgyMDQxIiwieDV0IjoiYldvWF...'