We’ve developed some resources to help you work effectively from home during COVID-19 Click to learn more

Authorization code flow

In this article

    In the authorization code flow, a human user accesses a client application that requires the user to authenticate.

    There are two types of Authorization Code Flow. The standard as described below, and Proof Key for Code Exchange (PKCE) to support native applications such as Windows apps and mobile phone apps. PKCE support was introduced in January 2020.

    Authorization Code Flow

     

    1. After clicking Sign in, the partner application redirects the user agent, typically a browser, to the authorization endpoint of the identity provider.

      https://sod.superoffice.com/login/common/oauth/authorize

    2. The user agent sends  a request to the identity provider authorization URI with the following information:

      • a response type
      • the scope
      • the client ID
      • the state
      • the redirect URI
      GET Request (test in a browser to handle the login/redirect)

https://sod.superoffice.com/login/common/oauth/authorize?
client_id=c789b7d98f3c496fb5aaa4b1a81ca11b&
scope=openid&
redirect_uri=https://partnerapp/callback&
state=12345&
response_type=code&

      Authorization code flow parameters
      Parameter Required Description
      client_id yes The client ID (application ID) assigned to your app when you registered it with SuperOffice.
      scope yes Must be openid.
      redirect_uri yes

      The redirection endpoint of your app, where authentication responses are sent and received.

      It must exactly match one of the redirect_uris registered with SuperOffice.
      state recommended A value set by the relying party to maintain state between the request and the callback itself.
      Included in the request and also returned in the token response.
      response_type yes Must include code for the authorization code flow.
      response_mode no

      Can be one of:

      • fragment and returns parameters in the URI after hash #
      • form_post and returns values in form data
      login_hint no Hint to the authorization server about the login identifier the user might use to sign in. For SuperOffice, this must be SuperID username.
      When used, it updates the user's name in the login cookie and is displayed in the username field. (added June 2019)
      code_challenge with PKCE Required for PKCE only. (added January 2020)
      code_challenge_method no Optional for PKCE only. Defaults to "plain" if not present in the request. Code verifier transformation method is "S256" or "plain". (added January 2020)

    3. The user is then directed to the authentication server sign-in screen, where they enter their credentials. An identity provider authenticates the user and asks for consent to access their resources on behalf of the relying party.

    4. With consent given, the authentication server sends an authorization response message from its authorization endpoint. This redirects the user-agent back to the relying party using the redirection URI provided earlier. This URI includes an authorization code and any state provided by the client earlier.

      GET Response

https://partnerapp/callback?
state=12345&
code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFT
      Authorization code response
      Parameter Description
      code The authorization code generated by the authorization server.
      Expires after 10 minutes.
      state The exact value received from the client.

    5. The relying party then makes a request for an ID token to the token endpoint by sending the client ID, the client secret, the authorization code, the redirect URI, and the grant type.

      POST Request (can be tested in a client such as Postman or Fiddler)Content-Type: application/x-www-form-urlencoded

https://sod.superoffice.com/login/common/oauth/tokens?
client_id=c789b7d98f3c496fb5aaa4b1a81ca11b&
client_secret=83d0f3bcb9afbc7eb9d0682e9b86db52&
code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFT&
redirect_uri=http://partner-app/callback&
grant_type=authorization_code&
      Authorization code request
      Parameter Required Description
      client_id yes The ID assigned to your application when you registered it with SuperOffice.
      client_secret yes The application secret (token) assigned to your application when you registered it with SuperOffice.
      code yes The authorization code that the application requested.
      The application can use the authorization code to request an access token for the target resource.
      redirect_uri yes The redirect_uri of your application, where authentication responses are sent and received by your app.
      It must exactly match one of the redirect_uris registered with SuperOffice.
      grant_type yes Must be authorization_code for the authorization code flow.
      code_verifier with PKCE Required for PKCE only. (added January 2020)

    6. The identity provider authenticates the client using the client ID and secret and validates the redirect URI. When the grant type is set to authorization_code, the identity provider will validate the code parameter. Alternatively, the grant_type is set to refresh_token and the provider will validate the refresh_token parameter.

    7. If valid, the identity provider responds back with the ID token from the token endpoint. The response also includes an access token and an optional refresh token. The client validates the ID token, and if successful, the identity is proven and the authorization code flow is complete.

      POST Response

{
"token_type": "Bearer",
"access_token": "8A:Cust12020.AR2s3phb0gXK8DP0NfoYlsrQAQAACIJ/KQ+cbGp0l9g8PJNlBCEZxS/1hL3Cxt8ITWlQipRbdt5CL1lQmUotYHaQQH9/Y7nq98WduG7QuSY7KMiSQRxHn7W5qppkEjlSTLW2+xfaV42eL2Vvw6V2WVwICzP6iE6wUDv/VX8Zgbp757BdKY4mIRnxsaGtpFGBFwKASLiLJ69SoUnYz753mx6XCwTFtgZRywCKDwykXLFoQ5qgAbhCkxs7IFmcBszRIgAAdul49zG/iAho24yw6fgcz/J+TpxVE/CpSsXsdDV/JpSA96ny9SQQ97t8HeRvCG5F/uUdE8TvzKorwIbccEvAGbsjRNsH0iKCP1BsnPUIRdq6f3iQf2R+LVEN1XqvxE7JsbF9cYwQ0IWtW3hfFy8BanBvqbYFYQcHLC3Qq/KTIJF8jZeV0djYoM8fzVY/hkLavIKWHXQnVWU7Vw/yTWHpuX+5xUTjJbHEhyduDImLNvOCPXzRQpQgso7agBMUEHzTXyTE348g1OZA32SfnAWwXMh/AvLZ1IQ0m5rzRcM1g3AolEmJWm3+2wPY5pmV6D6N3JTGgUA+b6USonaknTbIFxUuUChHj4U1qUlP6/dJA+aKE1psfT8F4XwFlYBjvw6xmM086Vckm0Mmh+fEPuoLspl+EgtQzD0F8Ka4qLFGWICvUg==",
"expires_in": 3600,
"refresh_token": "KSamN1Tp4sd26pZJSGK6JobrWOUWorIZ2Y5XxcAqX86K9qoZRp4d3lUH32F4fiT3",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.eyJzdWIiOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlciI6InN1cGVyb2ZmaWNlLW9ubGluZSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnkueWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L3VwbiI6InRvbnkueWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QxMjAyMCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTUwMTE3ODU4NCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QxMjAyMC9SZW1vdGUvU2VydmljZXM4Mi8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MTIwMjAvYXBpLyIsImlhdCI6IjE1MTYyOTk2NTYiLCJub25jZSI6IjczNjJDQUVBLTlDQTUtNEI0My05QkEzLTM0RDdDMzAzRUJBNyIsImlzcyI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbSIsImF1ZCI6ImRiMTgzNDAzN2M1OGMwMmI2YmQ5ODk4ZmVlZjE5ODQ1IiwiZXhwIjoxNTE2Mjk5OTU2LCJuYmYiOjE1MTYyOTk1OTZ9.jVW0KWtOeaYV4V3372rSVosPQqlOsaOj6-Oew_Ompe9GZ932aQi6tcc7uXdaz9jmBgLh8mlIZWyW4rFcTnyLQzjjK3nSYWNxxvobQRntigD1lNFYFR7ev9nrYnLw7oTQ9DkuluduWDMcdHYfmImeVNDC93txA_njdmta45ZG0VBeG9lrxInXMdxWXqb_W-ogEaHYbkfugMXwlim7V1c38Wl8QR9QVNImFACzmdma_HBILmUDK9f4XdTA93TnB-WYhesJ_tvdmzrScMIFKANvNNT3smxec6ST-j1uCUBCQrVNxILapXiUrJER4aMmAbFweWs9bbgfhR9_sQVQDmLbVw"
}
      Authorization code token response
      Parameter Description
      access_token The access token issued by the authorization server.
      token_type Provides the client with the information required to successfully utilize the access token to make a protected resource request.
      expires_in The lifetime in seconds of the access token.
      refresh_token

      The refresh token, which can be used to obtain new access tokens.
      The refresh token is a long-lived JWT token that can be re-used.
      It is coupled to an end-users consent and is valid as long as the application authorization record (consent) exists. Tenants can revoke authorizations.
      id_token

      JSON Web Token or JWT, which consists of a Header, Payload and Signature. The claims in the token form part of the payload.