Implement authorization by grant type

This guide explains how to implement a Resource Owner Password flow for your app with Okta.

---

Learning outcomes

• Understand the OAuth 2.0 Resource Owner Password flow.
• Set up your app with the Resource Owner Password grant type.
• Implement the Resource Owner Password flow in Okta.

What you need

• Okta Integrator Free Plan org (opens new window)
• An app that you want to implement OAuth 2.0 authorization with Okta

Note: The Okta Integrator Free Plan org 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.

---

About the Resource Owner Password grant

The Resource Owner Password flow isn’t a recommended approach. It’s intended for applications for which no other flow works, as it requires your application code to be fully trusted and protected from credential-stealing attacks. It’s made available primarily to provide a consistent and predictable integration pattern for legacy applications that can't otherwise be updated to a more secure flow such as the Authorization Code flow. This should be your last option, not your first choice.

To select the appropriate flow to use for your application, see OAuth 2.0 and OpenID Connect overview's decision flowchart.

Grant-type flow

Resource Owner Password flow

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

1. The user authenticates with your client application, providing their user credentials.

2. Your app sends these credentials to the Okta authorization server with its client ID and secret in the request header.

   Before implementing this redirect request to the authorization server (Okta), you need to set up your app in Okta. See Request for tokens.

3. The authorization server responds with an access token if the credentials are accurate.

4. Your app uses the access token to make authorized requests to the resource server.

5. 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. Open the Admin Console for your org.
2. Choose Applications > Applications to view the current app integrations.
3. Click Create App Integration.
4. Select

   OIDC - OpenID Connect

   as the Sign-in method.

5. For Application type, select Native Application, then click Next.
6. Enter an App integration name.
7. Click Advanced in the Grant type section, and then select Resource Owner Password.

   Note: If you're using Classic Engine, select Resource Owner Password in the Grant type section.

8. Enter the remaining details for your app integration, then click Save.
9. Locate the Client Credentials section on the General tab, and then click Edit.
10. For Client authentication, select Client secret, then click Save.

Save the generated Client ID and Client secret values to implement your authorization flow.

Flow specifics

If implementing the Resource Owner Password flow is your only option, you need to make direct calls to the OIDC & OAuth 2.0 API (opens new window). See the following sections for requests required in the flow.

Request for tokens

Before you can begin this flow, collect the user's password in a manner of your choosing. After you collect the credentials, all that's required is a single API call to the authorization server's /token endpoint. If you're using the org authorization server, then your request would look something like this:

curl --request POST \
  --url https://{yourOktaDomain}/oauth2/v1/token \
  --header 'accept: application/json' \
  --header 'authorization: Basic MG9hYn...' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=password&username=testuser1%40example.com&password=%7CmCovrlnU9oZU4qWGrhQSM%3Dyd&scope=openid'

Important: The call to your authorization server's /token endpoint requires authentication. In this case, it's a Basic Authentication digest of the client ID and secret. You can find the client ID and secret on your application's General tab. See Client Authentication Methods (opens new window).

Note the parameters that are being passed:

• grant_type is password, indicating that you're using the Resource Owner Password grant type.
• username is the username of a user registered with Okta.
• password is the password of a user registered with Okta.
• scope is at least openid. For custom scopes, see the Create Scopes section of the Create an authorization server guide.

For more information on these parameters, see the OAuth 2.0 API reference (opens new window).

If the credentials are valid, your application receives back access and ID tokens:

{
    "access_token": "eyJhb[...]56Rg",
    "expires_in": 3600,
    "id_token": "eyJhb[...]yosFQ",
    "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.

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.