Choosing the Right Okta OAuth 2.0 Grant or OIDC Flow

Okta provides various OAuth 2.0 grants and OpenID Connect (OIDC) flows to initiate user sessions and exchange tokens securely. Administrators must select the correct flow or grant based on the application type, security requirements, and specific use cases to ensure secure authentication.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• OAuth 2.0
• OpenID Connect (OIDC)

What are the primary authentication flows and grants?

Choosing the correct OAuth 2.0 grant or OIDC flow depends on the application type and security requirements. The available options include primary flows used to start a new user session, dependent flows that rely on an existing token, and legacy flows that administrators must avoid for new integrations.

Review the following primary authentication flows and grants used to initiate a user or machine session from scratch.

Authorization Code Flow with Proof Key for Code Exchange (PKCE)

• Use Case: PKCE protects the authorization code flow in single-page applications and mobile apps. Its ability to prevent authorization code injection makes it useful for every type of OAuth client, including web apps that use client authentication.
• Description: This flow adds a security layer to the standard Authorization Code flow by using a dynamic code verifier and code challenge. It prevents authorization code interception attacks and serves as the recommended standard for OAuth clients.
• Documentation: Implement the Authorization Code flow with PKCE.

Client Credentials Grant

• Use Case: This grant supports Machine-to-Machine (M2M) communications, such as daemons, backend scripts, or services with no end-user interaction.
• Description: The application authenticates as itself using client credentials to obtain an access token. This grant lacks a user context, returns no ID token or user identifier, and does not function with OpenID scopes.
• Documentation: Implement the Client Credentials Grant.

Direct Auth

• Use Case: Direct authentication allows client apps to verify user credentials and authentication factors directly without relying on browser interactions. This approach gives apps more control over authentication and improves the user experience for non-browser apps, such as mobile apps.
• Description: Direct authentication provides a set of authentication APIs. These APIs allow a client to verify a user's authentication factors directly in exchange for OAuth 2.0 tokens. The client completes this action without interacting with the Sign-In Widget in a browser.
• Documentation: Configure Direct Auth Grants.

Interaction Code Flow (IDX)

• Use Case: This flow supports native, Single-Page Application (SPA), and web apps using the Okta Identity Engine (OIE) that require an embedded authentication experience.
• Description: This flow allows applications to manage user interactions directly with OIE without browser redirects. Okta returns an interaction code that the client exchanges for tokens.
• Documentation: Implement the Interaction Code flow.

Device Authorization Grant Flow

• Use Case: This flow supports input-constrained devices such as smart TVs, IoT devices, or command-line interfaces (CLI) that lack a browser or keyboard.
• Description: This flow supports devices that cannot perform a standard browser-based login. It initiates a request that requires the user to complete authentication on a separate device, such as a smartphone or laptop. Once the user enters the provided code and authenticates on the second device, the original device receives the access token to complete the grant.
• Documentation: Implement the Device Authorization grant flow.

What are the dependent and specialized flows and grants?

Review the following dependent and specialized flows and grants that require a token or assertion obtained from a primary flow.

Refresh Token Grant

• Use Case: This grant supports applications that require access to resources for an extended period without forcing the user to authenticate again.
• Description: A refresh token acts as a credential artifact originally obtained during an initial user-authenticated flow, such as the Authorization Code flow with PKCE or the Interaction Code flow. Once the initial flow completes and the access token expires, the application uses this refresh token to obtain a new access token without further user interaction.
• Documentation: Refresh access tokens.

Identity Assertion Grant

• Use Case: This grant supports Cross App Access (XAA) scenarios where an application needs to access resources in another application within the same trust domain without direct user interaction.
• Description: This flow requires a specialized identity assertion, the id-jag token, originally obtained via a Cross-App Access flow. The application exchanges the assertion for a new access token to interact with a third-party API, using a common identity provider to bridge the trust between the independent applications.
• Documentation: Cross App Access.

On-Behalf-Of (OBO) Token Exchange Grant

• Use Case: This grant supports service-to-service chaining in which a middle-tier API calls a downstream API while preserving the original user's identity and permissions.
• Description: This flow requires an existing access token, the subject token, originally obtained via a user-facing flow, such as the Authorization Code flow with PKCE. The middle-tier service exchanges the incoming token for a new access token specifically scoped for the downstream service.
• Documentation: Set up On-Behalf-Of Token Exchange.

Native to Web SSO

• Use Case: This flow creates a seamless, unified authentication experience when a user transitions from an OIDC origin app, like a native mobile app, to a web app using OIDC or Security Assertion Markup Language (SAML).
• Description: This flow allows an origin app to exchange an existing session token for a single-use interclient token. The native app launches the system browser and passes this token to the target web app's authorization URL to bootstrap the user's session without a second login.
• Documentation: Configure Native to Web SSO.

Native to Native SSO

• Use Case: This flow provides a seamless Single Sign-On (SSO) and Single Logout (SLO) experience across multiple independent native applications installed on the same device.
• Description: This flow uses the Token Exchange grant to share the authentication state. A primary app obtains a device_secret and id_token which a secondary app exchanges for its own tokens via the /token endpoint. This mimics web-based cookie sharing for native OS environments.
• Documentation: Configure SSO for Native apps.

SAML 2.0 Assertion Flow

• Use Case: This flow supports applications that already have a trust relationship with a SAML Identity Provider (IdP) and need to access OAuth-protected APIs without requiring the user to sign in again or provide direct consent. Hybrid environments commonly use this flow when a user logs into a legacy system via SAML but needs to interact with modern OIDC or OAuth 2.0 resources.
• Description: This flow allows a client application to exchange a valid, signed SAML 2.0 assertion for an OAuth 2.0 access token. The client obtains the assertion from the SAML IdP and presents it to the Okta /token endpoint using the urn:ietf:params:oauth:grant-type:saml2-bearer grant type. Okta validates the assertion's signature and trust before issuing tokens, bridging the gap between SAML-based authentication and OAuth-based authorization.
• Documentation: Implement the SAML 2.0 Assertion grant.

Hybrid Flow

• Use Case: This flow supports server-side applications that securely store secrets but need immediate access to an ID token before exchanging the code for an access token.
• Description: This flow combines the Implicit flow with Form Post and the Authorization Code flow. It allows the client to receive an ID token immediately from the authorization endpoint while simultaneously obtaining an authorization code that the client later exchanges for an access token.

What are the legacy and discouraged flows and grants?

Review the following legacy flows and grants, which Okta discourages for new integrations.

Authorization Code Flow

• Use Case: This flow supports server-side web applications, such as ASP.NET, Java, PHP, and Node.js, where the code executes on a secure server. The Authorization Code flow with PKCE serves as the preferred alternative.
• Description: This flow served as the standard method for controlling access to web applications capable of securely storing a client secret. The application exchanges an authorization code for an access token and ID token directly with the authorization server, ensuring that the tokens remain hidden from the user agent.
• Documentation: Implement the Authorization Code flow.

Resource Owner Password Grant (ROPG)

• Use Case: This grant supports highly trusted legacy applications where no other flow functions correctly.
• Description: The user enters their username and password directly into the client application, which exchanges them for a token.
• Documentation: Implement the Resource Owner Password grant.

NOTE: Okta strongly discourages this flow because it bypasses Multi-Factor Authentication (MFA) and Single Sign-On (SSO) flows and exposes user credentials to the client.

Implicit Flow

• Use Case: Single-Page Applications (SPAs) that lacked a backend and could not securely store a client secret historically used this flow.
• Description: This flow returns tokens directly to the browser's address bar via a redirect. Okta strongly discourages this flow for modern applications because it exposes access tokens in the browser history and logs. The Authorization Code flow with PKCE supersedes this flow and provides a more secure way to handle tokens in the browser.

NOTE: This flow remains highly susceptible to token theft and interception. Administrators must only use this flow if maintaining legacy applications where no other flow functions correctly.