Implement authorization by grant type

This guide explains how to implement an Authorization Code with PKCE flow for your app in Okta.

---

Learning outcomes

• Understand the OAuth 2.0 Authorization Code with PKCE flow.
• Set up your app with Authorization Code and Refresh Token grant types.
• Implement the Authorization Code with PKCE flow in Okta.

What you need

• Okta Developer Edition organization (opens new window)
• An app that you want to implement OAuth 2.0 authorization with Okta

Note: Okta's Developer Edition makes most key developer features available by default for testing purposes. Okta's API Access Management product — a requirement to use Custom Authorization Servers — is an optional add-on in production environments.

Sample code

Native and single-page app examples

---

About the Authorization Code grant with PKCE

If you are building a native application, then the Authorization Code flow with a Proof Key for Code Exchange (PKCE) is the recommended method for controlling the access between your application and a resource server. The Authorization Code flow with PKCE is similar to the standard Authorization Code flow with an extra step at the beginning and an extra verification at the end.

See the OAuth 2.0 and OpenID Connect decision flowchart for flow recommendations.

Note: Some browsers have begun blocking third-party cookies by default, disrupting Okta functionality in certain flows. See FAQ: How Blocking Third Party Cookies Can Potentially Impact Your Okta Environment (opens new window).

Grant-type flow

Authorization Code with PKCE flow

At a high-level, the flow has the following steps:

1. Your application (app) generates a code verifier followed by a code challenge. See Create the proof key for code exchange.

2. Your app directs the browser to the Okta sign-in page, along with the generated code challenge.

   You need to register your app so that Okta can accept the authorization request. See Set up your app to register and configure your app with Okta. After registration, your app can redirect the browser to Okta. See Request an authorization code.

3. The authorization server (Okta) redirects the authentication prompt to the user.

4. The user authenticates.

   For Okta to authenticate the user credentials, Okta needs user profile data. See Add a user using Console (opens new window), Import Users, and the Users API. Alternatively, you can set up self-service registration to allow users to register their membership with the app.

5. Okta redirects back to your native application with an authorization code.

6. Your application sends this code, along with the code verifier, to Okta. See Exchange the code for tokens.

7. Okta evaluates the PKCE code.

8. Okta returns access and ID tokens, and optionally a refresh token.

9. Your application can now use these tokens to call the resource server (for example, an API) on behalf of the user.

10. The resource server validates the token before responding to the request. See Validate access token.

Set up your app

Before you can implement authorization, you need to register your app in Okta by creating an app integration from the Admin Console.

1. In the Admin Console, go to Applications > Applications.
2. Click Create App Integration.
3. Select

   OIDC - OpenID Connect

   as the Sign-in method.

4. Select either Native Application or Single-Page Application (depending on the type of application that you are working on) as the Application type, then click Next.

   Note: It is important to choose the appropriate application type for apps that are public clients. Failing to do so may result in Okta API endpoints attempting to verify an app's client secret, which public clients are not designed to have and would break the sign-in or sign-out flow.

5. Specify the App integration name.

6. Authorization Code is selected automatically as a Grant type. In addition, select Refresh Token.

   Note: For mobile applications, Authorization Code is required.

7. Specify the Sign-in redirect URIs to redirect the user with their authorization code.

8. Fill in the remaining details for your app integration, then click Save.

On the General tab, the Client Credentials section contains the Client ID for your app integration. It also shows the Client authentication that defaults to None. The use of None for client authentication requires the use of a Proof Key for Code Exchange (PKCE) for additional verification. PKCE ensures that only the client that requests the access token can redeem it.

Save the generated Client ID value to implement your authorization flow.

Use an SDK

Okta recommends using existing libraries and OAuth 2.0 helper methods to implement your authentication flow. You can use one of Okta's array of language and framework SDKs or an open-source library if an appropriate Okta SDK is not available. See Languages & SDKs overview for a list of Okta SDKs that you can download to start using with your app.

For instructions on how to install and use Okta SDKs, refer to Configure the SDK for front-end SDKs and Add packages for mobile native SDKs. You can download Okta sample apps to see how the SDKs are used in your app's framework. See Examples for a list of sample apps.

Flow specifics

The following sections outline the main components required to implement the Authorization Code with PKCE flow using direct calls to Okta's OIDC & OAuth 2.0 API. Typically, you don't need to make direct calls to the OIDC & OAuth 2.0 API if you're using one of Okta's SDKs.

Create the Proof Key for Code Exchange

Similar to the standard Authorization Code flow, your app starts by redirecting the user's browser to your authorization server's /authorize endpoint. However, in this instance you also have to pass along a code challenge.

Your first step is to generate a code verifier and challenge:

• Code verifier: Random URL-safe string with a minimum length of 43 characters
• Code challenge: Base64URL-encoded SHA-256 hash of the code verifier

You need to add code in your native app to create the code verifier and code challenge.

The PKCE generator code creates output like this:

{
  "code_verifier":"M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag",
  "code_challenge":"qjrzSW9gMiUgpUvqgEPE4_-8swvyCtfOVvg55o5S_es"
}

The code_challenge is a Base64URL-encoded SHA256 hash of the code_verifier. Your app saves the code_verifier for later, and sends the code_challenge along with the authorization request to your authorization server's /authorize URL.

Request an authorization code

If you are using the default custom authorization server, then your request URL would look something like this:

https://${yourOktaDomain}/oauth2/default/v1/authorize?client_id=0oabygpxgk9lXaMgF0h7&response_type=code&scope=openid&redirect_uri=yourApp%3A%2Fcallback&state=state-8600b31f-52d1-4dca-987c-386e3d8967e9&code_challenge_method=S256&code_challenge=qjrzSW9gMiUgpUvqgEPE4_-8swvyCtfOVvg55o5S_es

Note the parameters that are being passed:

• client_id matches the Client ID of your Okta OAuth application that you created in the Set up your app section.
• response_type is code, indicating that we are using the Authorization Code grant type.
• scope is openid, which means that the /token endpoint returns an ID token. See the Create Scopes section of the Create an authorization server guide.
• redirect_uri is the callback location where the user agent is directed to along with the code. This must match one of the Sign-in redirect URIs that you specified when you created your Okta application in the Set up your app section.
• state is an arbitrary alphanumeric string that the authorization server reproduces when redirecting the user agent back to the client. This is used to help prevent cross-site request forgery.
• code_challenge_method is the hash method used to generate the challenge, which is always S256.
• code_challenge is the code challenge used for PKCE.

See the OAuth 2.0 API reference for more information on these parameters.

If the user doesn't have an existing session, this request opens the Okta sign-in page. If they have an existing session, or after they authenticate, the user arrives at the specified redirect_uri along with an authorization code:

yourApp:/callback?code=BdLDvZvO3ZfSwg-asLNk&state=state-8600b31f-52d1-4dca-987c-386e3d8967e9

This code can only be used once, and remains valid for 300 seconds, during which time it can be exchanged for tokens.

Exchange the code for tokens

To exchange the authorization code for access and ID tokens, you pass it to your authorization server's /token endpoint along with the code_verifier that was generated at the beginning:

curl --request POST \
  --url https://${yourOktaDomain}/oauth2/default/v1/token \
  --header 'accept: application/json' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&client_id=0oabygpxgk9lXaMgF0h7&redirect_uri=yourApp%3A%2Fcallback&code=CKA9Utz2GkWlsrmnqehz&code_verifier=M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag'

Important: Unlike the regular Authorization Code flow, this call doesn't require the Authorization header with the Client ID and secret. That is why this version of the Authorization Code flow is appropriate for native apps.

Note the parameters that are being passed:

• grant_type is authorization_code, indicating that we are using the Authorization Code grant type.
• redirect_uri must match the URI that was used to get the authorization code.
• code is the authorization code that you got from the /authorize endpoint.
• code_verifier is the PKCE code verifier that your app generated at the beginning of this flow.
• client_id identifies your client and must match the value preregistered in Okta.

See the OIDC & OAuth 2.0 API reference for more information on these parameters.

If the code is still valid, and the code verifier matches, your application receives back access and ID tokens:

{
    "access_token": "eyJhb[...]Hozw",
    "expires_in": 3600,
    "id_token": "eyJhb[...]jvCw",
    "scope": "openid",
    "token_type": "Bearer"
}

Validate access token

When your application passes a request with an access token, the resource server needs to validate it. See Validate access tokens.

Examples

The following native and single-page application examples show the Authorization Code with PKCE flow as it would be implemented by an application that needs to authenticate a user. These are complete example applications that show the entire experience.

	Environment	Example Repository
	Android	Browser Sign-In Example (opens new window)
	iOS	Okta iOS Browser Sign-In Example (opens new window)
	React Native	Okta React Native + Browser Sign-In Example (opens new window)
	Angular	Okta Angular + Okta Hosted Login Example (opens new window)
	Blazor WebAssembly	Blazor WebAssembly & Okta-Hosted Sign-In Page Example (opens new window)
	React	Okta React + Okta Hosted Login Example (opens new window)
	Vue	Okta Vue + Okta Hosted Login Example (opens new window)

Next steps

Now that you have implemented authorization in your app, you can add features such as:

• Brand customization (custom domain, custom SMS messages, custom emails, and custom error pages).
• Self-service enrollment.