Instructions for

Implement authorization by grant type

Grant-type flow

Authorization Code flow

Sequence diagram that displays the back and forth between the resource owner, authorization server, and resource server for Authorization Code flow"

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

Your application (app) directs the browser to the Okta sign-in page.

Before implementing this redirect request to the authorization server (Okta), you need to set up your app in Okta to obtain a client ID to embed in your request. See Request an authorization code.
Okta redirects the authentication prompt (Okta sign-in page) to the user.
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.
After the user is authenticated, the browser receives an authorization code from the authorization server (Okta). The authorization code is passed to your app.
Your app sends this code and the client secret to Okta. See Exchange the code for tokens.
Okta returns access and ID tokens, and optionally a refresh token.
Your app can now use these tokens to call the resource server (for example an API) on behalf of the user.
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.

In the Admin Console, go to Applications > Applications.
Click Create App Integration.
Select
OIDC - OpenID Connect
as the Sign-in method.

Flow specifics

The following sections outline the main requests required to implement the Authorization Code 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.

Request an authorization code

To get an authorization code, your app redirects the user to your authorization server's /authorize endpoint. 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=0oabucvy
c38HLL1ef0h7&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fexample.com&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601

Note the parameters that are being passed:

client_id matches the Client ID of your Okta OAuth application that you created above. You can find it at the bottom of your application's General tab.
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 URI 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.

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

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

http://localhost:8080/?code=P5I7mdxxdv13_JfXrCSq&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601

This code remains valid for 300 seconds, during which it can be exchanged for tokens.

Exchange the code for tokens

To exchange this code for access and ID tokens, you pass it to your authorization server's /token endpoint. If you are using the default custom authorization server, then your request would look something like this:

curl --request POST \
  --url https://${yourOktaDomain}/oauth2/default/v1/token \
  --header 'accept: application/json' \
  --header 'authorization: Basic MG9hY...' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&code=P59yPm1_X1gxtdEOEZjn'

Important: The call to the /token endpoint requires authentication. In this case, it's Basic Authentication with the client ID and secret Base64 encoded. You can find the Client ID and secret on your application's General tab. This requirement is why this call is only appropriate for applications that can guarantee the confidentiality of the client secret. See Client Authentication Methods.

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.

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

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

{
    "access_token": "eyJhbG[...]9pDQ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "openid",
    "id_token": "eyJhbG[...]RTM0A"
}

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 web application examples show you the Authorization Code flow as it would be implemented by a web app that needs to authenticate the end user and then create a local session for that user. These projects use popular web frameworks to handle the heavy lifting. Each project can be cloned and ran locally.

	Framework	Example Repository
	ASP.NET	ASP.NET MVC & Okta-Hosted Login Page Example (opens new window)
	ASP.NET Core 3.x	ASP.NET Core & Okta-Hosted Login Page Example (opens new window)
	Go	Golang + Okta Hosted Login Example (opens new window)
	Node Express	Express & Okta-Hosted Login Page Example (opens new window)
	PHP	PHP + Okta Hosted Login Example (opens new window)
	Python	Flask + Okta Hosted Login Example (opens new window)
	Spring Boot	Okta Spring Security & Okta-Hosted Login Page Example (opens new window)

Next steps

Edit This Page On GitHub