Authorization Code flow
Authorization Code flow is the best flow to use for web applications. When it was first introduced Authorization code flow required the client_secret. However, on a windows or mobile application that causes security problems. Proof Key for Code Exchange (PKCE) (rfc7636) was introduced as extra layer of security on top of Authorization Code flow, and provides a way for native applications to use Authorization Code flow without exposing the client_secret in a vulnerable way.
🛈 Note
PKCE does not replace the use of a client secret for all scenarios, and in fact PKCE is recommended even when a client is securely using the client secret.
Getting the user’s consent
OAuth is about enabling users to grant access to applications, and allowing those application access to their SuperOffice web services.
The Authorization Code flow begins when a client application redirects a user to the authorize endpoint.
# test in a browser to handle the login/redirect
GET Request https://sod.superoffice.com/login/common/oauth/authorize?
client_id=c789b7d98f3c496fb5aaa4b1a81ca11b&
scope=openid&
redirect_uri=https://[registered-application-redirect_uri]/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 for your registered application. |
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. |
acr_values | no | Allows passing in additional related information. SuperOffice allows tenant:contextIdentifer, i.e. tenant, used to skip the tenant selection dialog |
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) |
The user is then directed to the SuperOffice SuperID 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 (app).
Redirect back to the application
When successfully authenticated and consent given, SuperID sends a response that redirects the user agent back to the Relying Party (app) redirect_uri. The response includes an Authorization Code and any state provided by the client earlier.
GET https://partnerapp/callback?
state=12345&
code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFTAuthorization 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. |
Exchange the authorization code for an access token
This is the final step, where the Relying Party (app) requests an access token.
# can be tested in an HTTP client (such as Postman, Fiddler or VS Code)
POST 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&
Content-Type: application/x-www-form-urlencoded
Accept: application/jsonAuthorization 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 endpoint 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) |
The identity provider (central-superid) will verify all the parameters, ensuring the client ID and secret match and the code hasn’t expired. When that’s complete, it will generate an access token and send it in the response.
Post response
POST Response
{
"token_type": "Bearer",
"access_token": "8A:Cust12020.AR2s3phb0gXK8DP0NfoYlsrQAQAACIJ/KQ+cbGp0l9g8PJNlBCEZxS/1hL3Cxt8ITWlQipRbdt5CL1lQmUotYHaQQH9/Y7nq98WduG7QuSY7KMiSQRxHn7W5qppkEjlSTLW2+xfaV42eL2Vvw6V2WVwICzP6iE6wUDvVX8Zgbp757BdKY4mIRnxsaGtpFGBFwKASLiLJ69SoUnYz753mx6XCwTFtgZRywCKDwykXLFoQ5qgAbhCkxs7IFmcBszRIgAAdul49zG/iAho24yw6fgcz/J+TpxVE/CpSsXsdDV/JpSA96ny9SQQ97t8HeRvCG5FuUdE8TvzKorwIbccEvAGbsjRNsH0iKCP1BsnPUIRdq6f3iQf2R+LVEN1XqvxE7JsbF9cYwQ0IWtW3hfFy8BanBvqbYFYQcHLC3Qq/KTIJF8jZeV0djYoM8fzVY/hkLavIKWHXQnVWU7Vw/yTWHpu+5xUTjJbHEhyduDImLNvOCPXzRQpQgso7agBMUEHzTXyTE348g1OZA32SfnAWwXMh/AvLZ1IQ0m5rzRcM1g3AolEmJWm3+2wPY5pmV6D6N3JTGgUA+b6USonaknTbIFxUuUChHj4U1qUlP6/dJA+aKE1psfT8F4XwFlYBjvw6xmM086Vckm0Mmh+fEPuoLsp+EgtQzD0F8Ka4qLFGWICvUg==",
"expires_in": 3600,
"refresh_token": "KSamN1Tp4sd26pZJSGK6JobrWOUWorIZ2Y5XxcAqX86K9qoZRp4d3lUH32F4fiT3",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9eyJzdWIiOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlcI6InN1cGVyb2ZmaWNlLW9ubGluZSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnkueWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L3VwbiI6InRvbnkeWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QxMjAyMCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTUwMTE3ODU4NCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QxMjAMC9SZW1vdGUvU2VydmljZXM4Mi8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MTIwMjAvYXBpLyIsImlhdCI6IjE1MTYyOTk2NTYiLCJub25jZSI6IjczNJDQUVBLTlDQTUtNEI0My05QkEzLTM0RDdDMzAzRUJBNyIsImlzcyI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbSIsImF1ZCI6ImRiMTgzNDAzN2M1OGMwMmI2YmQ5ODk4ZmVlZjE5ODQ1IiwiZXhwIjoxNTE2Mjk5OTU2LCJuYmYiOjE1MTYyOTk1OTZ9jVW0KWtOeaYV4V3372rSVosPQqlOsaOj6-Oew_Ompe9GZ932aQi6tcc7uXdaz9jmBgLh8mlIZWyW4rFcTnyLQzjjK3nSYWNxxvobQRntigD1lNFYFR7ev9nrYnLw7oTQ9DkuluduWDMcdHYfmImeVNDC93txA_njdmta45ZG0VBeG9lrxInXMdxWXqb_W-ogEaHYbkfugXwlim7V1c38Wl8QR9QVNImFACzmdma_HBILmUDK9f4XdTA93TnB-WYhesJ_tvdmzrScMIFKANvNNT3smxec6ST-j1uCUBCQrVNxILapXiUrJER4aMmAbFweWs9bbgfhR9_sQVQDmLbVw"
}| 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. 3600 / 1 hour is expected |
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. |
The application now has an access token and can start making API requests to the SuperOffice tenant web services.
Certified OpenID Connect libraries automatically verify the id_token. If your application doesn’t use a certified library, read how to validate the id_token JWT.
With a verified id_token the application can safely store the refresh_token for fetching a new access token when the current expires.
The Authorization Code flow is complete!
Refresh token
When an access token has expired, refresh tokens are used to get a new access tokens without forcing the user to go through the Authorization Core flow again.
🛈 Note
No other flow, only the Authorization Code flow, returns a refresh token.
The refresh token is only used:
- when the access (or ID) token has expired
- when there is a need to update the claims in an ID token
⚠️ Warning
Refresh tokens must never be stored client-side in the browser!
This is a long-lived token that is a contract between an application and tenant user. It can be re-used:
- for the lifetime of the application, or
- as long as the application authorization record (consent) exists, or
- until it has been revoked - tenants can revoke authorizations
⚠️ Caution
Refresh tokens may be revoked if we suspect its security has been compromised, or a customer or application vendor requests it be revoked.
Send a refresh_token request
A refresh_token is used in a POST request sent to the tokens endpoint.
POST Request (can be tested in a client such as Postman or Fiddler)
https://{env}.superoffice.com/login/common/oauth/tokens?
grant_type=refresh_token&
client_id=4ref5376616343b38d14ddcd804f2654&
client_secret=18f45229e442772a78df5f554e24a456&
refresh_token=nKHwerkjh3asd6QShsnGKk4casdwCv3XtJu9PW2XasdtUMygLdI57BJjwCU0&
redirect_url=http://localhost/callback
Accept: application/jsonRefresh token parameters:
| Parameter | Required | Description |
|---|---|---|
grant_type | yes | Must be set to refresh_token |
client_id | yes | The client ID (application ID) assigned to your app when you registered it with SuperOffice. |
client_secret | yes | The client secret (application token) assigned to your app when you registered it with SuperOffice. |
refresh_token | yes | The refresh token issued as one of the response items in the Authorization Code flow. |
redirect_uri | no | The redirect URL of your app, where authentication responses are sent and received by your app. It must exactly match one of the redirect URLs registered with SuperOffice. |
scope | no | SuperOffice only supports the scope openid and is implicit for each flow. |
Receive a refresh_token response
The response contains the token type, access token, expiration in seconds, and id token.
{
"token_type": "Bearer",
"access_token": "8A:Cust12345.AZuHwfgrDEMONSTRATION_ONLYsdfswerwe3z5BnSYUSk4U4sdfr1Bjzycu0S1NC+xvghQ4VoUz9r6xpF2YAOCj0rb3LWnjLqllp3fYk8h2sxwc8d+5nb5bzGvHLHJ1UIRk38Ye4dPpmLSr4B8UaYNc9gs4Wgfgxqtii+o5w5XTYhPFW1rTcqbXbsnAtv8S+tJWHGPDxi2T/XUHpZxaDp2FT50nVePNiT9tAfP9QQwH0hbXN6RZzKfOcX37DtGcigMLsoc1qM+bJ8oWJqhVbPQIQ4J7**DEMONSTRATION_ONLY16y62E5hhs0e+ePThKSS7h52iaq5cwQMj0u2EAInK80UUjRTTpwznJWSlCFXsOD+cSNC6livOOz54PJoejKS+VxRqsr3TYQK+DEMONSTRATION_ONLYYIZr7fvFnvuTvGJTRSvOR2TuZhy2wl6/qOTLSpG9gvtPD2zjC+BiVmMW/P4Qhv3DWoSFCVqyQISqtFXy3rGexPIL+dz7kutoSkDYhcAl6aO8B0kdYKSsPow+8Jo8N3SD453r9uTGGiAl1tVWXfHo53eDEMONSTRATION_ONLYqCybSS9hF2sb5+v2HF36RPpt6bqOuCEIMAcpYJkiQ87kLTqsEGA9AA43sf1RfcB7lbVaVLFGmjUj1jgtIzVKiAR9eyMiWXL3dWMg+WM2Y0MOTsUrSb10kXkJ4g3M4TvH3rV4HTK3ohToxUleYvFbarx/8jeO7oLJfn3nth8NGtd1lJ",
"expires_in": 3600,
"id_token": "eyJ0eFor_Demonstration_PurposeszI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.For_Demonstration_PurposesbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlciI6ImNlbnRyYWwtc3VwZXJpZCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnlAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubDEMONSTRATION_ONLYaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QyNjc1OSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTgwMTU1MDE5MyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QyNjc1OS9SZW1vdGUvU2VydmljZXM4Ni8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MjY3NTkvYXBpLyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9zeXN0ZW1fdG9rZW4iOiJTdXDEMONSTRATION_ONLYTm9kZSBPSURDLThrOFE3RG1CZ28iLCJpYXQiOiIxNTQ2NjEzMTk4IiwiaXNzIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tIiwiYXVkIjoiNmNmMjUzNzY2MTYzNDNiMzhkMTRkZGNkODA0ZjI4OTEiLCJleHAiOjE1NDY2MTM0OTgsIm5iZiI6MTU0NjYxMzEzOH0.ZzeDsNHJr86pLyqvpPQ5rMzRGd88Fh_RHLdBuG8fBmk_iZnFI5zaARDsTQffEzM30l61rZVmmpQo7KfAN6w27QB6XawURYwye59Z5c3fWRg8BJ4K5Uwik3PxtDEMONSTRATION_ONLYCQBG0D8I1jF2YZrI8ZO33PtRPisYHJ1F2F5O-qStzCXqhSjd1u7FjsJhqr1xGLDqLzkOm9_0v0nWFHESjBuPhFPIdt6lmcCuy48HGg5G0eM1_3h6SESsukXe0hNMqp3ZHjm5dCEoxE4HziLWSdRZIUa6tkP6wfHDHU_XUJu7PHo8Wx5aG9IBPZ_r1Xd8mgmt6g"
}