Implement authorization by grant type

This guide explains how to implement a Client Credentials flow for your app with Okta.

---

Learning outcomes

• Understand the OAuth 2.0 Client Credentials flow.
• Set up your app with the Client Credentials grant type.
• Implement the Client Credentials 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 Client Credentials grant

Use the Client Credentials flow for server-side ("confidential") client apps with no end user. Typically, that means for machine-to-machine communication. In this scenario, your app needs to securely store its client ID and secret, and then exchange them with Okta for an access token.

This guide uses the Client Credentials flow with a custom authorization server to get access tokens for use with your APIs. If you need access tokens to make calls to the Okta APIs (OAuth for Okta), see Implement OAuth for Okta with a service app.

See the OAuth 2.0 and OpenID Connect decision flowchart for the appropriate flow recommended for your app.

Grant-type flow

Client Credentials flow

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

1. Your client app makes an authorization request to your Okta authorization server using its Client Credentials.

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

2. Okta responds with an access token if the request credentials are accurate.

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

4. 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

   API Services

   as the Sign-in method.

5. Click Next.
6. Enter the app integration name, then click Save.

On the General tab, the Client Credentials section contains the Client ID and Client secret for your app integration. Copy these to implement your authorization flow.

Create custom scopes

The Client Credentials flow never has a user context, so you can't request OpenID scopes. Instead, you must create a custom scope. To learn about creating custom scopes, see the Scopes section of Create a custom authorization server.

Use an SDK

Okta recommends using existing libraries and OAuth 2.0 helper methods to implement your authentication flow. You can use one of the Okta SDKs or an open-source library if an appropriate Okta SDK isn’t available. See Recommended Okta SDKs for a list of Okta SDKs that you can download to start using with your app.

Flow specifics

Before implementing the flow, you must first create custom scopes for the custom authorization server used to authenticate your app from the Admin Console.

If you aren’t using existing libraries, you can make a direct request to the Okta OIDC & OAuth 2.0 API (opens new window) through the /token endpoint. See Request for token in the next section.

Request for token

The Client Credentials flow is intended for server-side (confidential) client apps with no end user, which normally describes machine-to-machine communication. Your client app needs to have its client ID and secret stored in a secure manner. You can find the client ID and secret on the General tab for your app integration.

Base64-encode the client ID and secret (as shown later) and then pass through Basic Authentication (opens new window) in the request to your custom authorization server's /token endpoint:

curl --request POST \
  --url https://{yourOktaDomain}/oauth2/default/v1/token \
  --header 'accept: application/json' \
  --header 'authorization: Basic MG9hY...' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=customScope'

Note: The client ID and secret aren't included in the POST body. Instead, they are in the HTTP Authorization header following the rules of HTTP Basic Auth (opens new window).

Note the parameters that are being passed:

• grant_type=client_credentials: Indicates that you're using the Client Credentials grant type
• scope: Must be at least one custom scope that you create. See the Create Scopes section of the Create an authorization server guide.

If the credentials are valid, the app receives an access token:

{
    "access_token": "eyJhbG[...]1LQ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "customScope"
}

Base64-encode the client ID and client secret

Use this section to Base64-encode the client ID and secret. When you finish encoding, you can then use the encoded client ID and secret in the HTTP Authorization header in the following format: 'authorization: Basic <Base64-encoded client ID and secret>'

If you're using macOS or Linux:

1. Open the Admin Console for your org.

2. Choose Applications > Applications to view the available app integrations.

3. Select the app that you want to use, and then on the General tab, copy the Client ID and Client secret.

4. Launch your preferred text editor and then paste the client ID and secret into a new file.

5. Place the client ID and secret on the same line and insert a colon between them: clientid:clientsecret

6. Copy the clientid:clientsecret line to the clipboard.

7. Launch a terminal and enter the following command, replacing clientid:clientsecret with the value that you copied.

   echo -n clientid:clientsecret | base64

8. Copy the value that is returned.

Note: Make sure that the entire results are on a single line with no text wrapping.

If you're using Windows:

1. Open the Admin Console for your org.

2. Choose Applications > Applications to view the available app integrations.

3. Select the app that you want to use, and then on the General tab, copy the Client ID and Client secret.

4. Launch your preferred text editor and then paste the client ID and secret into a new file.

5. Save the file to C:\temp and name the file appCreds.txt.

6. In Windows Explorer, right-click C:\temp, and then select CMD Prompt Here from the context menu.

7. Enter the following command to encode the client ID and client secret:

   copycertutil -encode appCreds.txt appbase64Creds.txt

8. Locate and open appbase64Creds.txt in C:\temp, copy its contents, and then close the file.

Note: Delete the appCreds.txt and the appbase64Creds.txt files after you finish.

Validate access token

When your app 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 customize several components of the authentication process to match your brand:

• Custom domains
• Custom SMS messages
• Custom emails
• Custom error pages