Authorization code for native applications

In the Authorization Code flow, API clients authenticate an end user and obtain an authorization code (a one-time use token). The code is then exchanged for an access token, and optionally, a refresh token.

Special security considerations apply to native applications, such as mobile apps, when using the authorization code flow. RFC 8252 - OAuth 2.0 for Native Apps was created to define best practices for such cases. These best practices include RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE), an extension to the core OAuth 2.0 specification that secures the authorization code flow when used in native applications.

AppDirect conforms to both RFC 8252 and RFC 7636.

tip

We recommend that you use the AppAuth client SDK to simplify integration with native applications and ensure that you follow best practices.

The following diagram illustrates the authorization code flow for native applications:

1. The Developer generates a cryptographically random code_verifier and associated code_challenge:

   code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

   Next, the application initiates authorization by sending a request to the authorization endpoint and including the code_challenge_method and code_challenge query parameters (required for PKCE).

   Sample request:

   https://marketplace.example.com/oauth2/authorize?response_type=code&client_id=appdirect-49&scope=ROLE_USER%20ROLE_BILLING_ADMIN&state=bf0jksdldqj&code_challenge_method=S256&code_challenge=FULBvRhW7stRYdJC2WQ1Tar4QtmoKtArNR6H-cnAGXg&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2Freturn

   Parameter	Description
   response_type	Must be code, which indicates that this is the Authorization Code grant type.
   client_id	Your API client ID.
   scope	A space-separated list of requested scopes.
   redirect_uri	Endpoint where the marketplace will redirect the user to with the authorization code. It must match the return URL registered with your API client.
   state (optional)	An opaque value used by your application to maintain state. The marketplace includes this value when redirecting to the redirect_uri. See the OAuth 2.0 specification for details on how to use this to prevent cross-site request forgery.
   code_challenge_method	Transformation method used when generating the code_challenge. This is always set to S256
   .code_challenge	The string value that’s transformed from the cryptographically random code_verifier and SHA 256 transformation method.

2. The user is authenticated with the marketplace.

3. An authorization code is returned to the redirect_uri passed in step 1.

   note

   This URI must also be registered within the product configuration. The state parameter is also returned.

   Sample request:

   https://www.example.com/oauth2/return?code=Ib08m7&state=bf0jksdldqj

4. The application sends a POST request to the token endpoint to exchange the code for an access token and optionally the refresh token. The request includes the code_verifier generated in step 1.

   Sample request:

   curl -X POST "https://marketplace.example.com/oauth2/token?grant_type=authorization_code&code=Ib08m7&code_verifier=rtDJlZb3hnHD0P65DYiUF0Xmplzg_anBoflHNGq0yCM&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2Freturn"

   Parameter	Description
   grant_type	Must be authorization_code, indicating that this is the Authorization Code grant type.
   code	The authorization code returned to your API client. A space-separated list of requested scopes.
   redirect_uri	The return URL registered with your API client. It must match the redirect_uri used in the authorization code request. Endpoint where the marketplace will redirect the user to with the authorization code. Must match the return URL registered with your API client.
   .code_verifier	The cryptographically random string generated in step 1. Used to verify this request came from the same client that code was returned to.

5. The AppDirect authorization server transforms the code_verifier using the following method:

   BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) = transformed_code_verifier

   The authorization server then authenticates the request by ensuring that the transformed_code_verifier matches the code_challenge passed in step 1. If the request is verified then the access and refresh tokens are returned.​

   Sample response:

   {
       "access_token": "7iVGxe84f1ew6QENpCD3",
       "refresh_token": "qsdfbasfsa1bjbfdjbfs",
       "token_type": "bearer",
       "expires_in": 43199,
       "scope": "ROLE_USER ROLE_BILLING_ADMIN"
   }

6. Call an AppDirect API and include the access token in the Authorization header as a bearer token.

   Sample request:

   curl -H 'Authorization: Bearer 7iVGxe84f1ew6QENpCD3' "http://marketplace.example.com/api/account/v2/subscriptions/6c31d072-8480-11e3-b2f4-22000ae812a4/assignments"

7. Receive the API response.