Implement authorization by grant type

This guide explains how to implement an Interaction Code flow for your app with Okta.

---

Learning outcomes

• Understand the Interaction Code flow.
• Set up your app with the Interaction Code grant type.
• Implement the Interaction Code flow in Okta.

What you need

• Okta Developer Edition organization
• An app that you want to implement OAuth 2.0 authorization with Okta

Note: Okta Developer Edition makes most key developer features available by default for testing purposes. The Okta API Access Management product — a requirement to use custom authorization servers — is an optional add-on in production environments.

Sample code

Embedded authentication app examples

---

About the Interaction Code grant

Identity Engine

The Interaction Code grant type is an OAuth 2.0 and OpenID Connect (OIDC) standard extension that is available in the Identity Engine to manage user interactions. The Interaction Code grant is typically used by native, SPA, and web client apps that want to interact directly with the user and mediate between the user and the authorization server, instead of using a browser-based redirect to hand off the authentication experience.

See Interaction Code grant type for more information.

Grant-type flow

Interaction Code flow

The Interaction Code flow is similar to the OAuth 2.0 Authorization Code flow with PKCE. All clients are required to pass a client ID and a Proof Key for Code Exchange (PKCE) in their authorization request to keep the flow secure. Confidential clients such as web apps must also pass a client secret in the authorization request.

1. The Interaction Code flow can start with minimal user information. For example, the user (resource owner) may only provide the client app with their username. Alternatively, the client can also begin the flow without any user information for a passwordless sign-in experience.

2. The client app generates the PKCE code verifier & code challenge.

   Note: To use the Interaction Code flow, you must enable the Interaction Code grant type for your org, app integration, and authorization server. See Verify that the interaction code grant type is enabled.

3. The client app begins interaction with an authorization server, providing any context it may have, such as a sign-in hint, as well as sending the PKCE code challenge in a request for authorization of certain scopes to the authorization server.

   Note: A confidential client authenticates with the authorization server while a public client (like the Sign-In Widget) identifies itself to the authorization server. Both must provide the PKCE code challenge.

4. Okta evaluates the sign-on policies for the app and authentication server and determines that remediation is required.

5. The Identity Engine component of the authorization server sends the interaction_handle parameter in a response body to the client app.

   Note: The interaction_handle is used to continue the interaction directly with the Identity Engine. This is why you need to register the client, either confidential or public, with the Identity Engine to perform this direct interaction.

6. The client sends the interaction_handle to the Identity Engine and in return, the Identity Engine sends any required remediation steps back to the client.

7. The client begins an interactive flow with the Identity Engine and the resource owner, handling any type of interaction required by the Identity Engine (the remedial information is provided by the user to the client).

8. The client responds to all the remediation steps required by the Identity Engine.

9. When the remediation steps are complete, the Identity Engine sends back a success response—including the interaction_code—to the client.

   Note: The interaction_code has a maximum lifetime of 60 seconds.

10. The client sends the code verifier and the interaction_code to the authorization server to exchange for tokens.

    Note: The interaction_code indicates that the client (and user) went through all the necessary policy-driven remediation and received a successful response from the Identity Engine.

11. The authorization server authenticates the client, evaluates the PKCE code, and validates the interaction_code.

12. If the client ID, PKCE, and interaction codes are valid, the authorization server sends the tokens (access, ID, and/or refresh) that were initially requested.

13. The client makes a request with the access token to your app.

14. Your app sends a response to the client.

Verify that the Interaction Code grant type is enabled

You must enable the Interaction Code grant type for your org, authorization server, and app integration so you can use the Interaction Code flow.

Enable Interaction Code grant for your org

The Embedded widget sign-in support setting in your Admin Console enables or disables the Interaction Code grant type for your org. With this setting enabled, you can allow or deny apps the ability to use embedded sign-in flows across your entire org.

Note: Super Admin permissions (opens new window) are required. If you don’t have those permissions for your org, contact your administrator.

To access this setting:

1. Open the Admin Console for your org.
2. Go to Settings > Account > Embedded widget sign-in support.
3. Click Edit.
4. Select the Interaction code checkbox to enable Interaction Code as a grant type.
5. Click Save.

If you enable the Interaction Code grant type, the number of applications and authorization servers that use the Interaction Code grant type appear.

If you disable the Interaction Code grant type:

• No OIDC app integrations or API calls can use the Interaction grant type. Okta returns an error saying the client isn't authorized to use the provided grant type if you don’t reconfigure them accordingly.
• Access rules for authorization servers don't show the Interaction Code as an available grant type.
• Interaction Code grant type isn’t re-enabled for your app integrations or authorization servers when you re-enable it for your org.

Enable Interaction Code grant for your authorization server

After you enable the Interaction Code grant for your org, it’s automatically configured in your org authorization server. If you're using a custom authentication server, you need to enable Interaction Code grant for it in the Admin Console:

1. Open the Admin Console for your org.

2. Go to Security > API.

3. Select the Authorization Servers tab, and then select the pencil icon next to the custom authorization server that you want to update.

4. Select the Access Policies tab.

5. Select the pencil icon from the Actions column for the policy that applies to your app. For example, the Default Policy Rule.

6. Locate the Edit Rule dialog box, and then select the Interaction Code checkbox.

   Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.

7. Click Update Rule.

Note: See Create an authorization server to create your own custom authorization server.

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, Single-Page Application, or Web Application (depending on the type of application that you're creating), then click Next.

6. Enter the App integration name.

7. Select Interaction Code and Refresh Token as allowed Grant types.

   Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.

8. In the Sign-in redirect URIs box, enter the callback location where Okta returns the browser (along with their Interaction Code).

9. Enter the remaining details for your app integration, then click Save.

Note: Remember to add the appropriate path in your app for redirection.

From the General tab of your app integration, save the generated Client ID and Client secret values to implement your authorization flow.

Enable the Interaction Code grant on an application

Complete the following steps to enable the Interaction Code grant for an existing app integration.

1. Open the Admin Console for your org.

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

3. Select your app integration from the list.

4. Locate the General Settings panel on the General tab, and then click Edit.

5. Select the Interaction code checkbox under the Grant type.

   Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.

6. Click Save.

Flow specifics

The Interaction Code flow is intended for developers who want to embed the authentication process in their apps rather than redirect it to Okta. Implement it in the embedded authentication deployment model using an Identity Engine SDK either alone or with the Sign-In Widget.

Use an SDK

Okta recommends using an Identity Engine SDK with the Sign-In Widget to implement your embedded authentication Interaction Code flow. See Languages and SDKs for information on Identity Engine SDKs that you can download to start using with your app.

Note: Consider using the Sign-In Widget to test your authentication policies even if you don’t plan to use it in production. It’s quicker to embed it in a test app than code the whole flow from scratch.

For instructions on how to install and use Identity Engine SDKs, see Download and set up the SDK, Sign-In Widget, and sample app. Each Identity Engine SDK contains its own example applications with embedded authentication. See Examples.

Apps using an embedded Sign-In Widget and Identity Engine SDK

An app integration using the client-hosted Sign-In Widget with an appropriate Identity Engine SDK is a simpler way of implementing embedded authentication where the Widget handles most of the remediation process. You still have control over the step-by-step remediation user experience by configuring authenticators and sign-on policies in your Okta org. With the remedial process managed by the Widget, your app just needs to handle the Interaction Code returned from the completed user interaction. See how this flow is built by reviewing the Build a use case with the embedded Widget guide.

In addition to configuring the Interaction Code grant type in your authorization server and your app, make sure you’re using the interaction code flow when you initialize the Sign-In Widget:

• In Okta Sign-In Widget version 7+, Identity Engine is enabled by default, so there are no additional steps to take.
• If you’re using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the config.

Note: For typical use case configurations, see setting up your Okta org.

Apps using an embedded Identity Engine SDK only

If you have a platform-specific app, use an appropriate Identity Engine SDK to start the Interaction Code flow by initializing the authentication client object and then calling the authenticate() method corresponding to the SDK that you are using. The remediation process is implemented by handling the authentication status responses of the authentication client object. See how this flow is built by reviewing the Build a use case with the embedded SDK guide. When the remediation process succeeds, Identity Engine sends your app an Interaction Code to exchange for OIDC tokens. Your app uses these tokens to access to your app’s resources.

Note: The authentication policies defined in your org configure the Interaction Code flow remediation experience in your app. See set up your Okta org.

Examples

Each Identity Engine SDK contains its own example applications with embedded authentication. See Download and set up the SDK, Sign-In Widget, and sample app to download the sample app source and instructions on how to run the sample apps.

Next steps

After running the sample apps, you can review the detailed step-by-step Embedded authentication guide on how to implement typical Identity Engine use case flows.