Overview

Authorization Code Grant is meant for obtaining access token using two-step process of:

1. User interactively performs logon against Authentication Server at the Authorization endpoint, resulting Authorization Code upon successful logon
2. Exchanging Authorization Code using Token endpoint into valid access token

Typically you would want to use this grant if you need to access APIs on behalf of some Applixure user account rather than in non-interactive machine-to-machine communication context. For non-interactive purposes, you should use Client Credentials Grant flow.

🚧

Authorization Code Grant vs. Authorization Code Grant with PKCE

Applixure recommends implementing Authorization Code Grant flow always with the PKCE extension for increased security.

Future revisions of Oauth2 standard may deprecate the use of Authorization Code Grants without the use of PKCE.

Flow description

Authentication with browser

In technical terms, first step requires opening up Internet browser for the user and navigating into Authorization endpoint URL with the following parameters in the URI:

📘

An example of authorization endpoint URL

https://auth.applixure.com/oauth2/authorize?response_type=code&client_id=plbDrF3shSTQooL&scope=openid&redirect_uri=http%3A%2F%2Flocalhost%3A54833%2Fcallback&state=7dee7d5780a94ee3bbff31e84f5abda8

As this phase only requires Application ID for registered client application, it can be initiated from applications that are publicly distributed and running on untrusted devices.

User will then see the Applixure logon screen and has to enter valid user account credentials, optionally verify logon with with 2FA token and finally consent into allowing the client application to obtain requested permissions as defined by the scopes.

📘

Consent on first use

Once user has consented for specific scopes for specific registered client application, AAS will no longer ask about consent for the same application and for the same scopes for that user account.

Depending on the result of authentication and authorization operation, AAS will finally call back (i.e. redirect the browser) into specified callback URI that the client application should listen to to continue forward with the flow.

As AAS will redirect using GET HTTP method, both success and error result is signalled through URI parameters for the callback URI and no request body is used for the purpose.

If authentication attempt resulted an error response, do not proceed to next phase but handle the error condition and/or notify the user appropriately.

📘

An example of authorization code callback URL

http://localhost:54833/callback?code=FtWXmTKps72U4iBaj5YW2w6q7XGWhwCcBnkfEUtDJHRdBFHYm9VtMsfZTGMStDddFKSSkzTXMuv3oqjEjapFFJvmiSDBLzRL3FW9R6BqisntP2kq9T7GC2NYG9FTnKQMkmqkaU4etUQdKJmmw1TPYhmzjM9biGxwXaVJrTPjFWs&state=7dee7d5780a94ee3bbff31e84f5abda8

🚧

Remember to check state!

If and when using state parameter, make sure to verify that your callback URI receives the same state parameter value back you originally generated for the request. If not, you should discard the response!

Getting access token

Next, using the authorization code received from the Authentication Server, you must exchange this code into valid access token using another endpoint.

❗️

Do NOT use for code running on untrusted client devices

This phase should NOT be run from untrusted client or device - such Javascript running in user's Internet browser or publicly available mobile or other applications - as retrieving token necessitates storing Client secret of your registered client application at the client side.

With both Application ID and Client secret, anyone can impersonate your registered client application and may lead to Applixure disabling such registration if misuse is detect!

As an alternative for such environment, you should use Authorization Code Grant variation using Proof Key for Code Exchange (PKCE).

For token exchange, you will need to send application/x-www-form-urlencoded encoded HTTP request in UTF-8 character set to the token endpoint with following parameters:

📘

An example of token endpoint payload

grant_type=authorization_code&code=FtWXmTKps72U4iBaj5YW2w6q7XGWhwCcBnkfEUtDJHRdBFHYm9VtMsfZTGMStDddFKSSkzTXMuv3oqjEjapFFJvmiSDBLzRL3FW9R6BqisntP2kq9T7GC2NYG9FTnKQMkmqkaU4etUQdKJmmw1TPYhmzjM9biGxwXaVJrTPjFWs&redirect_uri=http%3A%2F%2Flocalhost%3A54833%2callback

Additionally, you must authenticate your client application for the request. OAuth2 specification for Authorization Code Grant flow supports using unauthenticated clients, but Applixure Authentication Servers requires that normal Authorization Code Grant flow clients authenticate themselves, except in the case of Authorization Code Grant with PKCE flow.

Authenticating the client happens by two alternative ways:

1. Encoding Application ID and Client secret as username and password -parts for HTTP Basic Authentication (authentication information in the HTTP request header)
2. Adding Application ID and Client secret as parameters to application/x-www-form-urlencoded encoded request body as additional client_id and client_secret parameters (authentication information in the HTTP request body)

🚧

HTTP request body authentication NOT RECOMMENDED

As per RFC 6749 Section 2.3.1, authentication using HTTP request body is not recommended and HTTP request header -method should always be favoured instead.

AAS supports both methods but Applixure always recommend using headers for client application authentication.

Successful call result

If token endpoint call is successful, you will receive JSON formatted payload back with following properties available:

📘

An example of success JSON payload

{ "access_token": "2bCL1o2gTwFrsMaSFBK1FbusqfdDUR5J7WyDcci8BkxY4zzQZ7S...", "token_type": "bearer", "expires_in": 3600, "refresh_token": "AXXtUZBWvfee7KSiSL98RwhYtNwEMhaswN7LkySYPXoUneYmi8mny4AzmtpRvs6dcK...", "scope": "environments:read users:manage" }

Error call result

Possible HTTP error response codes returned are: