Author. code flow usage
13.3.2.1. AS-centric AS - Authorization code flow usage

Use Case Scenario

This use case demonstrates the different steps required to execute an authorization code flow with user interactions.

Prerequisites

The client is already registered through dynamic client registration (13.3.2.2. AS-centric AS - client credentials grant usage example) or configured as a static client in the configuration (17.7.1. OAuth AS configuration - AS-centric

Overview of Steps

  • A client starts an authorization code flow (authorize call).
  • User authenticates and consents with the request.
  • The client receives the authorization code.
  • The client and exchanges token for access and refresh token (token call).

Step 1: Start an Authorization Code Flow

To start the authorization code flow, open a browser window and enter the following URL:

Browser URL to start an authorization code flow

https://oidc.airlock.com/auth-login/oauth2/v3/myAS/authorize?response_type=code&redirect_uri=https://oidc.airlock.com/application/demo&client_id=oidc-client&state=ee26b0dd4a...28a8ff&scope=employee%20openid

To successfully start an authorization code flow, the following conditions must be met:

  • A redirect_uri must be present in the request.
  • The redirect_uri must be on the list of redirect_uris registered during client registration.
  • A client_id must be present.
  • The scope "openid" must be present.
  • One additional scope must be present, if the authorization server has required scopes configured.
  • The redirect_url must be URL encoded.

If one of the conditions is not met, the authorization server will return an error message in the browser.

Submitting the "state" parameter is not required by the standard, but it is strongly recommended to protect against CSRF.

Step 2: Authentication and Consent

Airlock IAM will present a login screen:

jdoe Loginapp

... and optionally ask for consent:

Authorization of a request

Step 3: Retrieve Authorization Code

If both authentication and consent grants have succeeded, Airlock IAM will redirect the browser to the redirect_uri requested in step 1.

Code Block Redirect URL in response to authorization code flow

https://oidc.airlock.com/application/demo?code=xRbH9uoaMMWB6urmWsg8b1xwJQF~JfD2s9CoUvwVWX42YxBwqfeC2RVWeG1HkvkdtxHz&state=ee26b0dd4a...28a8ff

The code provided in the redirect URL is called an authorization code.

Step 4: Obtain Access and Refresh Tokens

Now follows a request to the token endpoint of the authorization server to exchange the authorization code for access, refresh, and optionally ID token.

token endpoint request

https://oidc.airlock.com/auth-login/rest/oauth2/authorization-servers/myAS/token

Content-Type: application/x-www-form-urlencoded

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ

grant_type=authorization_code
code=RSEzh6Ay3rCuCXY5znRBeY2Z5Fb%7EyHCbrg17CdEcdQMxy76pgbdXvM1dJBkFfnxMNiEy
redirect_uri=https://oidc.airlock.com/application/demo

It is recommended to configure the authorization server, to enforce authentication on the token endpoint.

The authorization server will respond as follows:

Code Block token endpoint response

200 OK
 {
    "access_token": "eyJraWQiOiI3YWRmMz...E9nfs7YyJZdRFP",
    "scope": "email",
    "id_token": "eyJraWQiOiI3YWRmMzgp74...Ex86vUkyMGqxQg",
    "token_type": "bearer",
    "expires_in": 17999
 }