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.

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.

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:Cust12345, 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=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.

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/json

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 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.

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

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

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/json

Refresh 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"
}

​Getting the user’s consent

​Authorization Code flow parameters

​Redirect back to the application

​Authorization Code response

​Exchange the authorization code for an access token

​Authorization Code request

​Post response

​Refresh token

​Send a refresh_token request

​Receive a refresh_token response

Getting the user’s consent

Authorization Code flow parameters

Redirect back to the application

Authorization Code response

Exchange the authorization code for an access token

Authorization Code request

Post response

Refresh token

Send a refresh_token request

Receive a refresh_token response