Execute an Authorization Code Grant Flow with PKCE
The Authorization Code with PKCE is the OAuth 2.0 grant that native apps use in order to access an API. In this document we will work through the steps needed in order to implement this: create a code verifier and a code challenge, get the user's authorization, get a token and access the API using the token.
Before beginning this tutorial, please:
1. Create a Code Verifier
First, you need to generate and store a
2. Create a Code Challenge
code_verifier, generate a
code_challenge that will be sent in the authorization request.
To begin an Authorization Code Grant flow, your native application should first send the user to the authorization URL including the
code_challenge and the method used to generate it.
audience: The unique identifier of the API the native app wants to access. Use the Identifier value on the Settings tab for the API you created as part of the prerequisites for this tutorial.
scope: The scopes that you want to request authorization for. These must be separated by a space. You can request any of the standard OIDC scopes about users, such as
offline_accessto get a Refresh Token (make sure that the Allow Offline Access field is enabled in the API Settings). The custom scopes must conform to a namespaced format. For more information on this, refer to the Namespacing Custom Claims panel.
response_type: Denotes the kind of credential that Auth0 will return (code vs token). For this flow, the value must be
client_id: Your application's Client ID. You can find this value at your Application's Settings.
redirect_uri: The URL to which Auth0 will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the
codeURL parameter. This URL must be specified as a valid callback URL under your Application's Settings.
code_challenge: Generated challenge from the
code_challenge_method: Method used to generate the challenge.
The PKCE spec defines two methods,
plain, the former is used in this example and is the only one supported by Auth0 since the latter is discouraged.
Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to call your API. Using the Authorization Code (
code) from the previous step, you will need to
POST to the Token URL sending also the
grant_type: This must be
client_id: Your application's Client ID.
code_verifier: Cryptographically random key that was used to generate the
code: The Authorization Code received from the initial
redirect_uri: The URL must match exactly the
The response contains
token_type values, for example:
refresh_token will only be present in the response if you included the
offline_access scope AND enabled Allow Offline Access for your API in the Dashboard. For more information about Refresh Tokens and how to use them, see our documentation.
5. Call the API
Once you have the Access Token, you can use it to make calls to the API, by passing it as a Bearer Token in the
Authorization header of the HTTP request:
6. Verify the Token
Once your API receives a request with a Bearer Access Token, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected.
For details on the validations that should be performed refer to Verify Access Tokens.
Optional: Customize the Tokens
You can use Rules to change the returned scopes of the Access Token and/or add claims to it (and the ID Token) with a script like this:
Namespacing Custom Claims
Auth0 returns profile information in a structured claim format as defined by the OIDC specification. This means that in order to add custom claims to ID Tokens or Access Tokens, they must conform to a namespaced format to avoid possible collisions with standard OIDC claims. For example, if you choose the namespace
https://foo.com/ and you want to add a custom claim named
myclaim, you would name the claim
https://foo.com/myclaim, instead of
myclaim. You can add namespaced claims using Rules.
If you wish to execute special logic unique to the Authorization Code (PKCE) grant, you can look at the
context.protocol property in your rule. If the value is
oidc-basic-profile, then the rule is running during the Authorization Code (PKCE) grant.
For an example implementation see the Mobile + API architecture scenario.
This is a series of tutorials that describe a scenario for a fictitious company. The company wants to implement a mobile app that the employees can use to send their timesheets to the company's Timesheets API using OAuth 2.0. The tutorials are accompanied by a sample that you can access in GitHub.