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'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

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 along a Client ID, as well as a Proof Key for Code Exchange (PKCE) to keep the flow secure. Confidential clients such as web apps must also pass a client secret in their 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, both the client app and the authorization server must have the Interaction Code grant type enabled in the Okta org.

3. The client app begins interaction with an authorization server (Org or Custom), 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 the client, either confidential or public, needs to be registered 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 of 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 of 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

The Interaction Code grant type is a sign-in flow used by embedded applications to connect to Okta. The Embedded widget sign-in support setting controls this grant type for all OpenID Connect and API access management servers in your org. With this setting enabled, you can allow or deny apps the ability to use embedded sign-in flows across your entire org. See Interaction Code grant type for detailed information on this grant type and how to use it.

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

1. To access this setting, from your Okta org's Admin Console, go to Settings > Account > Embedded widget sign-in support.

2. Click Edit.

3. Select the checkbox if you want to use the Interaction Code as a grant type for your OpenID Connect app integrations and authorization servers.

   If the Interaction code checkbox is selected, the number of applications and authorization servers that use the Interaction Code grant type appear.

   If you disable the Interaction Code grant type:

   • You can’t configure any new OpenID Connection app integrations to use the Interaction Code grant.
   • For any app integrations previously configured to use the Interaction Code grant type, the grant type is disabled and no longer an available option.
   • Users that attempt to sign in to the app integration receive a message that the client isn’t authorized to use the provided grant type.
   • Access rules for authorization servers don't show the Interaction Code as an available grant type.
   • When an API call is made using the Interaction Code grant type, Okta returns an error message that the client isn’t authorized to use the provided grant type.
   • If you disable this feature for your org and then re-enable it, the Interaction Code grant type isn't automatically re-enabled for any app integration or authorization server.

4. Click Save.

Set up your authorization server

To use the Interaction Code flow, both your client app and the Okta authorization server that you are using with the app must have the Interaction Code grant type enabled in your Okta org.

If your Okta org uses Identity Engine, then the Interaction Code grant type is automatically configured in your org authorization server. For custom authorization servers that you are using with your app, verify that the Interaction Code grant type is an available option. If it isn’t, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled for more information on how to toggle the Interaction Grant type for your org.

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

Enable Interaction Code grant on your authorization server

1. In the Admin Console, go to Security > API.

2. On the Authorization Servers tab, select the pencil icon next to the custom authorization server that you want to update.

3. Select the Access Policies tab.

4. Select the pencil icon from the Actions column for the Default Policy Rule. If you aren’t using the Default Policy for your client app that requires the Interaction Code grant, select the Policy that applies to your app.

5. In the Edit Rule dialog box, select the Interaction Code check box (in addition to any other grant type that is already supported by the authorization server).

   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 Update Rule.

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

5. Specify the App integration name.

6. Select Interaction Code and Refresh Token as 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.

7. Specify the Sign-in redirect URIs to redirect the user with their Interaction Code.

8. Fill in 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 value to implement your authorization flow. If you have a web application, you also need to save the Client secret value.

Enable the Interaction Code grant on an application

If you have an existing app registered in Okta and want to enable the app to use the Interaction Code flow, complete the following steps to enable the Interaction Code grant.

1. In the Admin Console, go to Applications > Applications.

2. Select your app from the application list.

3. From the General tab, click Edit in the General Settings panel.

4. In the Grant type > Client acting on behalf of a user option, select the Interaction Code checkbox You can retain any other grant types that your app currently supports).

   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.

5. Click Save.

Flow specifics

The Interaction Code flow is intended for developers who want to control the remediation user experience without redirecting the authentication experience to Okta. The Interaction Code flow is used in the embedded authentication deployment model where you can manage the user interaction by leveraging either an Identity Engine SDK or the Sign-In Widget with an Identity Engine SDK.

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: Even if you are not using the Sign-In Widget in your final embedded app, the Sign-In Widget can be used to validate and test your defined policies before investing a lot of time on coding the authentication flow.

For instructions on how to install and use Okta Identity Engine SDKs, refer to Download and set up the SDK, Sign-In Widget, and sample app. 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.

Embedded authentication app using the Sign-In Widget and a native 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 most of the remediation process is handled by the Widget. 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 are 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 are using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the config.

Note: Also see setting up your Okta org for typical use case configurations.

Embedded authentication app using a native Identity Engine SDK

If you have a native or web 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 completes successfully, your app is provided with an Interaction Code to then exchange for OpenID Connect tokens to use for authenticated access to your app’s resources.

Note: The Interaction Code flow remediation experience is dictated by Authenticators and sign-on policies configured in your Okta org. See set up your Okta org for typical use case configurations.

Examples

There are sample embedded authentication apps included in each Identity Engine SDK repository. 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.