Sample use-case Code Grant
13.4.1.2. OAuth 2.0 / OpenID Connect – Sample use-case for the authorization Code Grant (Client-centric)

We describe a sample use case in order to illustrate the interaction with Airlock IAM that occurs during an Authorization Code Grant. This takes a 'black-box' view and does not discuss the configuration of Airlock IAM. Please refer to the configuration pages for explanations of how IAM is configured.

Setting description

We reference the following OAuth 2.0 parameters and refer to the RFC 6749 for more details.

Name
Value
Comments
client_id
myclient
 
response_type
code
identifies an authorization code grant request
state
eaf26ac3a6b8b3b9
 
scope
customer employee
scopes are a space-separated list
redirect_uri
https://airlock-client.iam/client-login/oauth2-client
In a multi-provider (AS) setup the redirect uri can optionally be AS-specific (e.g. https://airlock-client.iam/client-login/oauth2-client/providerId)

The sample use case illustrates a setup where both the Client role and the Authorization Server role are implemented using Airlock IAM at the following locations:

Role
Location
OAuth 2.0 Client
https://airlock-client.iam/client-login/
OAuth 2.0 Authorization Server
https://airlock-as.iam/as-login/

Workflow description

  • 1.
    The (unauthenticated) user starts a login process:
    • 1.
      Single Provider: User visits any page on the Client: 
    • https://airlock-client.iam/client-login/login (login page type: OAUTH2_SSO)

    • 2.
      Multiple Provider: User chooses a provider (AS) on the login page (login page types: USERNAME_PASSWORD, USERNAME_TOKEN, USERNAME_PASSWORD_TOKEN), resulting in the subpath (/providerId) in further steps.
  • 2.
    The Client redirects the user to the landing page https://airlock-client.iam/client-login/oauth2-login(/providerId) from which it is possible to start the grant (page can be omitted by configuration):
  • 81023320.png
  • 3.
    The user clicks the link and is redirected to https://airlock-client.iam/client-login/oauth2-client(/providerId), which automatically initiates the Authorization Code Grant by sending an Authorization Request to the Authorization Server:
  • https://airlock-as.iam/as-login/oauth2/myclient?response_type=code&client_id=myclient&redirect_uri=https%3A%2F%2Fairlock-client.iam%2Fclient-login%2Foauth2-client&scope=employee%20customer&state=eaf26ac3a6b8b3b9

    Note that the parameters used here are URL-encodings of the parameters in the setting description above. Furthermore, note that the client id appears in both the URL and as URL parameter "client_id".

  • 4.
    The Authorization Server requires the user to login by displaying the login page https://airlock-as.iam/as-login/login as follows:
  • 81023325.png

    In this example, the user is requested to log in using her username and password only. However, Airlock IAM allows using any other means of authentication in this step, e.g. two-factor authentication.

  • 5.
    The user logs in using her username and password.
  • 6.
    If the login is successful, the user is redirected to the confirmation page https://airlock-as.iam/as-login/oauth2-confirm, where she is asked to grant a selection of the requested scope: (confirmation page can be disabled by configuration - in this case all scopes matching user roles are granted automatically). Note that Airlock IAM also supports delegating this step to a separate remote consent application (see 13.3.1.3.1. Remote consent applications with OAuth).
  • 81023317.png
  • 7.
    Assuming the user grants the scope 'employee', the user is redirected back to the Client with an authorization code:
  • https://airlock-client.iam/client-login/oauth2-client?code=itester.-C7OhEkOVoCq9m9j8zBd4LSQYrAp5vtOVnYrovMH&state=a8bce490e4f3b0ea
    • 1.
      For completeness, in case the user decided to deny access, the following page would be displayed on the Client:
    • 81023329.png
  • 8.
    The Client uses this authorization code to obtain access and refresh tokens. These requests happen between the Client and the Authorization Server directly, and are not visible here. For an illustration, refer to 13.4.1. OAuth 2.0 / OpenID Connect authorization Code Grant (Client-centric), where this is shown in step 6 and 7. Assuming the Authorization Server issues these tokens, the Client might obtain resources from the Authorization Server's Resource Endpoint, see steps 8 and 9 in the illustration. In this example, we assume that the username is obtained using a resource request from the Client to the Authorization Server. This username will be used by Airlock IAM on the Client.
  • 9.
    Finally, the user is logged in at the Client and gets redirected to a target application, such as the portal on https://airlock-client.iam/client-login/portal:
  • 81023331.png