Overview

Authorization Code Grant with Proof Key for Code Exchange 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

This grant flow must be used for non-confidential clients that cannot store Client secret for your application registration, such as publicly distributed mobile clients etc., that need to access Applixure APIs using user account credentials. Regular Authorization Code Grant can be used for code that runs on trusted devices capable of storing Client secret for your application registration.

This flow uses an extension to base OAuth2 protocol to try and mitigate possible authorization code interception that would otherwise happen if client secret is not used.

Flow description

Code verifier generation

Code verifier

As a first phase, your application code - before calling any endpoints - has to generate a cryptographically random code verifier string that is between 43 and 128 characters in length, and can only contain following characters (i.e. characters allowed in URL variant of Base64 without padding):

• A-Z
• a-z
• 0-9
• "-", ".", "_" or "~"

🚧

Always use unique verifier

Code verifier should never be re-used across authentication attempts, always generate new code verifier for each new authentication attempt when using Authorization Code Grant!

Code Challenge

Based on the generated code verifier, application then has to derive a code challenge string from the verifier. This challenge string can be generated using either of two methods:

📘

An example of S256 code challenge

GIven cryptographically generated code verifier of "xHh9ioRsgVFv3O4Rgwdi.7IJ2KTKOtNfkUechMNAhHOfN35Iwo", treating each character as its ASCII representation ("0x78,0x48,0x68...") and hashing the whole string with SHA-256, resulting Base64Url encoded - without padding - code challenge would be: "WNGSeD2uXAfb4Ga_6b2J1Aj3XUl_D1FDVaBRFVaZ_qM".

Authentication with browser

Next, authentication 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&code_challenge=WNGSeD2uXAfb4Ga_6b2J1Aj3XUl_D1FDVaBRFVaZ_qM&code_challenge_method=S256&scope=openid&redirect_uri=http%3A%2F%2Flocalhost%3A54833%2Fcallback&state=7dee7d5780a94ee3bbff31e84f5abda8

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.

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&code_verifier=xHh9ioRsgVFv3O4Rgwdi.7IJ2KTKOtNfkUechMNAhHOfN35Iwo

As Authorization Code Grant flow with PKCE is intended for untrusted clients that cannot store Client secret, calling token endpoint in this flow does not require client 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: