Okta Developer

Build a Secure TypeScript MCP Client with Cross App Access (XAA)

Fri, 09 Oct 2026 00:00:00 -0500

Enterprise apps rarely work alone. Imagine this scenario: HR wants to ensure that a new employee completes their new hire onboarding, and they want this verification in the company’s HR app so it’s tied to the employee’s personnel file. But the onboarding tasks come from a task-tracking tool with requirements defined by each department, from a different vendor and on a different domain than the HR app. It’s on IT to bridge the two.

Wiring the two together normally costs the user an OAuth consent screen or costs IT a shared service account. Cross App Access (XAA) removes that step. The company’s identity provider vouches for the user across the boundary, under a policy the admin sets in advance. In this tutorial, you’ll build that flow end-to-end in TypeScript.

You’ll build a Model Context Protocol (MCP) requesting app: a web app that signs a user in through an enterprise Identity Provider (IdP), exchanges that identity for a delegation token called an Identity Assertion JWT Authorization Grant (ID-JAG), trades the ID-JAG for an access token, and calls a protected MCP server to fetch real data. You’ll use the MCP TypeScript SDK, which added first-class Cross App Access support, and you’ll test everything against xaa.dev, the free XAA playground from the Okta Dev Advocacy team.

By the end of this post, you can:

Explain what XAA is and why AI agents and enterprise apps need it
Read an ID-JAG and understand key claims in it
Understand each step of the XAA flow through the SDK functions
Let the SDK’s CrossAppAccessProvider run the whole flow for you

Prerequisites

Node.js 20 or later
npm, which ships with Node.js
A free xaa.dev registration (email only)
Familiarity with OAuth 2.0 concepts. If Proof Key for Code Exchange (PKCE) is new to you, read Secure Your Express App with OAuth 2.0, OIDC, and PKCE first.

The code in this tutorial runs against @modelcontextprotocol/client version 2.0.0-alpha.2, openid-client 6, Express 4, and the xaa.dev playground services. The MCP SDK version is a prerelease of the v2 line, and APIs can change between prereleases, so check the sample repository for the exact dependency versions.

Table of Contents

What you’ll build: a TypeScript MCP requesting app
Register your requesting app on xaa.dev
Set up the TypeScript project
Run your TypeScript MCP app with xaa.dev
The four-step XAA flow
Inspect the tokens in the dashboard
ID-JAG: the token that carries identity across apps
Why Cross App Access matters for AI agents
The Model Context Protocol and its TypeScript SDK
Inside the MCP TS SDK’s crossAppAccess module
Walk through the XAA flow in TypeScript
Where XAA fits in your real architecture
Learn more about Cross App Access, ID-JAG, and MCP

What you’ll build: a TypeScript MCP requesting app

The sample app is an employee onboarding dashboard. After a single sign-in at the playground IdP, it fetches the user’s onboarding checklist from a protected MCP server and renders progress stats, an “up next” card, and the checklist itself. A “behind the scenes” panel shows all four XAA steps executing live, with timings and expandable decoded tokens, because watching the tokens flow is the best way to learn the protocol.

One naming note before the build: in this post, the MCP client and the requesting app are the same thing. The app is an MCP client toward the server it calls, and a requesting app in XAA terms, because it requests delegated access on behalf of the signed-in user.

The app spans four files:

src/server.ts: an Express server that handles the OpenID Connect sign-in with openid-client and streams the flow steps to the browser over server-sent events (SSE)
src/xaa.ts: the XAA flow via CrossAppAccessProvider, built on the MCP TypeScript SDK
src/config.ts: environment variables and app configuration
public/index.html: the dashboard

The complete project is on GitHub in the okta-xaa-typescript-mcp-sdk-example repository. Get it running first, then this post walks back through what each token in the chain does and how the SDK produces it.

Register your requesting app on xaa.dev

Rather than stand up an enterprise IdP and a protected resource yourself, you’ll code against xaa.dev, the free XAA playground from the Okta Dev Advocacy team. It hosts the three services you don’t have to build: the IdP (IdenX at https://idp.xaa.dev), the resource’s authorization server (https://auth.resource.xaa.dev), and a protected todo resource available as both a REST API and an MCP server (https://mcp.xaa.dev/mcp). You register your app once and get the credentials your project needs because XAA spans two trust domains: your app needs one identity at the IdP to sign users in and another at the resource’s authorization server to get access tokens. For a tour of the playground itself, read Introducing xaa.dev: A Playground for Cross App Access.

Go to the requesting app registration page
Enter your email address. It scopes which registered apps are visible to you; xaa.dev creates no account and sends no email.
Select + Register New App and fill in the form:
- Application Name: any label, for example, Onboarding App - Local Dev
- Redirect URIs: http://localhost:3001/callback (the match is exact, including scheme, host, port, and path)
- Connect to Resource: select the Todo MCP server resource (todo0-mcp) and keep the todos.read and mcp.access scopes
Save the credentials from the confirmation modal

Registration gives you at least two sets of credentials, and mixing them up is the most common XAA mistake:

Client	Credentials	Identifies your app at
Main client	`client_id` / `client_secret`	the IdP, for sign-in and for the token exchange
Resource client	`resource_client_id` / `resource_client_secret` (the ID looks like `client_xxx-at-todo0-mcp`)	the resource’s authorization server

Note: Why separate credentials? The IdP and the resource’s authorization server are separate trust domains, so your app holds a separate identity at each. Using the main client’s credentials at the resource’s authorization server results in an invalid_client error.

Note: Some registrations also show a distinct pair for the token exchange itself. If yours does, keep it aside; the sample has a slot for it, and reuses the main client when you leave that slot empty.

Set up the TypeScript project

Clone the sample and install the dependencies:

git clone https://github.com/oktadev/okta-xaa-typescript-mcp-sdk-example.git
cd okta-xaa-typescript-mcp-sdk-example
npm install
cp .env.example .env

Fill in .env with the credentials from your registration:

# Main client: identifies your app at the IdP
XAA_CLIENT_ID=YOUR_CLIENT_ID
XAA_CLIENT_SECRET=YOUR_CLIENT_SECRET

# Token-exchange client, if your registration shows a separate pair for it.
# Leave both blank to reuse the main client above.
EXCHANGE_CLIENT_ID=
EXCHANGE_CLIENT_SECRET=

# Resource client: identifies your app at the resource's authorization server
MCP_CLIENT_ID=YOUR_RESOURCE_CLIENT_ID
MCP_CLIENT_SECRET=YOUR_RESOURCE_CLIENT_SECRET

# xaa.dev endpoints (no trailing slashes)
IDP_BASE_URL=https://idp.xaa.dev
AUTH_SERVER_URL=https://auth.resource.xaa.dev
MCP_SERVER_URL=https://mcp.xaa.dev/mcp

PORT=3001
BASE_URL=http://localhost:3001
XAA_SCOPE=todos.read mcp.access

Note: Keep the URLs free of trailing slashes. The IdP compares the audience value as an exact string, so https://auth.resource.xaa.dev/ with a slash fails where https://auth.resource.xaa.dev succeeds.

Note: The sample’s .gitignore excludes .env. Never commit client secrets, ID tokens, ID-JAGs, or access tokens to version control.

Run your TypeScript MCP app with xaa.dev

Start the server and open the dashboard:

npm start

Go to http://localhost:3001 and select Sign in with company SSO.

IdenX accepts any email address, so no real credentials are involved. It then shows a Verify Your Identity screen asking for a verification code. The playground runs in demo mode and sends no email, so enter any six digits.

After sign-in, the app runs the flow automatically: four steps light up in order in the “behind the scenes” panel with real timings, and the onboarding checklist renders as soon as the last one delivers the data.

You never saw a consent screen, and your app never held a credential for the todo service. That’s the point of XAA, and the panel shows how it happened.

The four-step XAA flow

The panel’s four cards are the whole protocol. Steps 1, 3, and 4 are standard OAuth 2.0; step 2 is the exchange XAA adds.

Step 1: User signs in (OpenID Connect + PKCE)
  Browser -> IdP                            -> your app gets an ID token

Step 2: Token exchange (RFC 8693)
  Your app -> IdP token endpoint            -> ID-JAG

Step 3: JWT bearer grant (RFC 7523)
  Your app -> resource authorization server -> access token

Step 4: Call the resource (RFC 6750)
  Your app -> MCP server (Bearer token)     -> data

The user authenticates once with the IdP, and your app receives an ID token. Your app exchanges that ID token at the IdP for an ID-JAG using OAuth 2.0 Token Exchange (Request for Comments (RFC) 8693). Your app presents the ID-JAG to the resource’s authorization server using the JWT bearer grant (RFC 7523) and receives a scoped access token. Finally, your app calls the protected resource with that token as a standard Bearer credential (RFC 6750).

Inspect the tokens in the dashboard

Select any step card to expand its decoded token. The next section walks through what the ID-JAG’s claims mean; for now, the one thing worth confirming is that the access token’s aud matches the ID-JAG’s resource, byte for byte. That match is the delegation chain holding together, and a mismatch is the most common cause of a 401 from the resource server.

Below the flow steps, the ACCESS TOKEN card displays the Bearer token issued in step 3, with an expand toggle to inspect the full JWT. The TOKEN CLAIMS card decodes the same token and surfaces iss, aud, sub, and scope. Together, they confirm the right issuer signed the token, it targets the MCP server, it carries the user’s identity, and the authorization server granted the scopes you asked for.

Select 🔄 Re-run (SDK discovers the auth server) at any time to replay the flow and watch CrossAppAccessProvider handle discovery automatically.

Note: The dashboard’s token inspector exists for learning and local debugging. Keep raw tokens out of production interfaces and logs; when troubleshooting in production, log redacted identifiers and non-sensitive claims instead.

Note: This app is read-only by design. It requests todos.read and mcp.access, and nothing else. Least privilege applies to AI agents and requesting apps the same way it applies to users.

ID-JAG: the token that carries identity across apps

The ID-JAG is a new token type introduced by XAA. It’s a signed JSON Web Token (JWT) that the IdP issues when your app exchanges the user’s ID token for it. Think of it as a sealed envelope from the IdP that says: “This app acts for this user, toward this specific resource, with these scopes, for the next five minutes.”

Here is a decoded ID-JAG from the app you just ran:

{
  "iss": "https://idp.xaa.dev",
  "sub": "usr_1a2b3c4d5e6f",
  "aud": "https://auth.resource.xaa.dev",
  "resource": "https://mcp.xaa.dev/mcp",
  "client_id": "client_1a2b3c4d-at-todo0-mcp",
  "scope": "todos.read mcp.access",
  "email": "user@example.com",
  "jti": "69586a9a-b962-4f5d-971f-40f12173bcf2",
  "iat": 1783333416,
  "exp": 1783333716
}

Most of those claims are standard JWT fields. Three decide whether your integration works:

aud names the token’s consumer: the authorization server that validates this ID-JAG. It isn’t the resource itself.
resource names the target API. The authorization server copies this value into the access token’s aud claim, so whatever you put here is what the resource validates later.
client_id is your app’s identity at the resource’s authorization server, not at the IdP. That’s the two-client model from registration, showing up in the token.

Get aud and resource backwards and the exchange either fails outright or succeeds into a token the resource server rejects, which is the error that costs the most debugging time.

The JWT header also carries "typ": "oauth-id-jag+jwt", and authorization servers reject anything else. That prevents attackers from replaying other JWTs, such as ID tokens, as authorization grants. The five-minute exp window and the one-time jti close off replay from the other direction.

Why Cross App Access matters for AI agents

You just watched one user action cross one app boundary. Enterprise software rarely stops at one. A single action fans out across many systems, and AI agents make the fan-out constant: an assistant reads a document, files a ticket, checks a calendar, and logs an audit event, all on behalf of one person.

Each of those hops needs the user’s identity. The traditional answer is a consent screen at every boundary. Users click through prompts they don’t read, and IT teams lose visibility into which app talks to which other app, because the authorization rests on personal consent. Some teams give up and share a service account, which puts a single overprivileged credential in front of everyone’s data.

XAA replaces that consent step with a policy the admin configures in advance. Your enterprise IdP already knows who the user is, because the user signed in this morning, so it vouches for that identity across the boundary with a short-lived signed token. The admin decides which app connects to which resource, with which scopes. The user signs in once, and every hop after that is an auditable cryptographic handoff.

Cross App Access is the industry term for a pattern built on the Identity Assertion Authorization Grant specification, an active Internet-Draft at the Internet Engineering Task Force (IETF) that defines the ID-JAG token and the exchange flow that XAA uses. To go deeper on the protocol itself, read Build Secure Agent-to-App Connections with Cross App Access (XAA).

The Model Context Protocol and its TypeScript SDK

Before diving into code, a quick word on the other protocol in this tutorial. The Model Context Protocol is an open standard created by Anthropic that continues to evolve, providing AI applications with a common way to connect to tools and data. An MCP server exposes capabilities (tools to call, resources to read, prompts to use), and an MCP client connects to those servers over a standard transport. Instead of building one custom integration per data source, build to one protocol so any MCP-capable AI application can use it. The MCP TypeScript SDK is the official implementation for JavaScript and TypeScript developers, handling protocol details such as transports, the initialization handshake, message schemas, and authorization.

The MCP community evolves the specification through Specification Enhancement Proposals (SEPs). Cross App Access support entered the protocol as Specification Enhancement Proposal (SEP) 990, Enterprise Managed Authorization, and the TypeScript SDK ships the implementation in its crossAppAccess module.

With SEP-990 implemented in the SDK, an XAA-enabled MCP client differs from a plain one by a single authProvider option and one callback, plus any compatibility adjustments your authorization server needs. The protocol work (discovery, token exchange, the JWT bearer grant, and retries) lives in the SDK rather than in your app.

Inside the MCP TS SDK’s `crossAppAccess` module

Three pieces of the TypeScript SDK matter for this tutorial:

discoverAndRequestJwtAuthGrant() performs step 2. It discovers the IdP’s token endpoint from its metadata, then sends an RFC 8693 token-exchange request and returns the ID-JAG. A sibling function, requestJwtAuthorizationGrant(), skips discovery when you already know the token endpoint.
exchangeJwtAuthGrant() performs step 3: given the resource authorization server’s token endpoint, it presents the ID-JAG with the RFC 7523 JWT bearer grant and returns the access token. Unlike the step 2 function, it does no discovery of its own.
CrossAppAccessProvider is the production path. It plugs into the SDK’s transport as an OAuthClientProvider and runs steps 2 through 4 automatically: it calls the MCP server, receives a 401 challenge, discovers the authorization server through protected resource metadata (RFC 9728), invokes your callback to obtain a fresh ID-JAG, exchanges it, and retries the request with the new access token.

You see discoverAndRequestJwtAuthGrant() in step 2 and the provider in the final section. exchangeJwtAuthGrant() is the standalone way to do step 3; the sample never calls it, because the provider builds that same JWT bearer request itself.

Walk through the XAA flow in TypeScript

The next four sections take each step in turn, so that you can trace every token in the chain. The fifth shows CrossAppAccessProvider, which drives steps 2 through 4 from one configuration. The code below is adapted from src/server.ts and src/xaa.ts, trimmed to the lines that matter for each step.

Sign the user in with OpenID Connect and PKCE

Step 1 is a standard OpenID Connect Authorization Code flow with PKCE, and standard means you shouldn’t write it yourself. The sample uses openid-client, which handles discovery, the PKCE challenge, and the code exchange. The piece XAA cares about is the ID token in the response, because it becomes the input to step 2.

Discovery returns a configuration object that the other calls take as their first argument. In src/server.ts:

import * as client from 'openid-client';

const config = await client.discovery(
  new URL('https://idp.xaa.dev'),
  process.env.XAA_CLIENT_ID,
  process.env.XAA_CLIENT_SECRET,
);

The /login route generates a fresh PKCE verifier, state, and nonce, stores them in the session, and builds the authorization URL:

const verifier = client.randomPKCECodeVerifier();
session.pkceVerifier = verifier;
session.state = client.randomState();
session.nonce = client.randomNonce();

const url = client.buildAuthorizationUrl(config, {
  redirect_uri: REDIRECT_URI,
  scope: 'openid email profile',
  state: session.state,
  nonce: session.nonce,
  code_challenge: await client.calculatePKCECodeChallenge(verifier),
  code_challenge_method: 'S256',
});

res.redirect(url.href);

The /callback route then exchanges the code for tokens in one call:

const tokens = await client.authorizationCodeGrant(
  config,
  new URL(req.originalUrl, BASE_URL),
  {
    pkceCodeVerifier: session.pkceVerifier,
    expectedState: session.state,
    expectedNonce: session.nonce,
  },
);

session.idToken = tokens.id_token;
session.claims = tokens.claims();

That one call verifies the ID token’s signature against the IdP’s published keys, checks the iss, aud, and exp claims, and confirms the state and nonce match what you stored. Hand-rolled sign-in code tends to decode the ID token payload without verifying any of it, which means trusting claims from a token you haven’t proven came from your IdP. Here, the ID token is the subject_token for step 2 and the root of the whole delegation chain, so that verification is load-bearing.

The app keeps the ID token in a server-side session. It never sends the ID token to the resource server; the token’s only job now is to prove the user’s identity to the IdP during token exchange.

Production note: Configure session cookies with HttpOnly, Secure, and an appropriate SameSite value, and keep client secrets out of browser code. The sample stores sessions in memory, which is fine for a local demo and wrong for production: use a session store so tokens survive a restart and scale past one process.

Exchange the ID token for an ID-JAG

Step 2 is the XAA step. One SDK call performs the whole RFC 8693 token exchange:

import { discoverAndRequestJwtAuthGrant } from '@modelcontextprotocol/client';

const jag = await discoverAndRequestJwtAuthGrant({
  idpUrl: 'https://idp.xaa.dev',
  audience: 'https://auth.resource.xaa.dev', // who validates the ID-JAG
  resource: 'https://mcp.xaa.dev/mcp',       // what the access token targets
  idToken: session.idToken,
  clientId: process.env.XAA_CLIENT_ID,       // main client
  clientSecret: process.env.XAA_CLIENT_SECRET,
  scope: 'todos.read mcp.access',
});

console.log(jag.jwtAuthGrant); // the ID-JAG (a JWT)
console.log(jag.expiresIn);    // 300 seconds

Under the hood, the function discovers the IdP’s token endpoint from its metadata, then sends a form-encoded POST with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, your ID token as the subject_token, and requested_token_type=urn:ietf:params:oauth:token-type:id-jag. The response’s access_token field carries the ID-JAG. The naming feels odd, but RFC 8693 reuses the standard token response shape, and the token_type value N_A signals that this token isn’t a bearer credential.

Pay attention to audience versus resource, because they answer different questions. audience names who validates this ID-JAG in step 3: the authorization server. resource names what your access token targets in step 4: the MCP server. The authorization server copies the resource verbatim into the access token’s aud claim, so an incorrect resource here later surfaces as a confusing 401 from the resource server.

One optimization worth noting: the discovery call incurs an extra network round trip on every run. If your server already fetched the IdP metadata (this app caches it during sign-in), call requestJwtAuthorizationGrant() with the known tokenEndpoint instead and skip rediscovery. Caching static configuration is fine; the tokens themselves are always requested live.

Exchange the ID-JAG for an access token

In step 3, your app presents the ID-JAG to the resource’s authorization server with the RFC 7523 JWT bearer grant, authenticating with the resource client credentials. The request posts grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer with the ID-JAG as the assertion, and the response is an ordinary OAuth token response: an access_token, token_type of Bearer, and an expires_in lifetime worth reading rather than assuming.

You don’t write that request yourself. CrossAppAccessProvider makes it, and the last section of this walkthrough shows how to configure it. Two details about this step save you real debugging time:

Client authentication method. Developer-registered clients on xaa.dev use client_secret_post, which means credentials belong in the request body. The provider declares client_secret_basic (an Authorization: Basic header) by default, so the client information has to name the method explicitly.
Send the scope parameter. The provider only sends a scope when the authorization server’s metadata advertises one, and xaa.dev’s does not. Omit it and the authorization server issues an access token with an empty scope, after which the failure is quiet. The MCP server still completes the handshake, resources/list still returns the resource names, and reading the todos still returns HTTP 200 with a JSON-RPC result. The rejection hides inside the resource payload: {"error":"Unauthorized","message":"Invalid or expired token"}. Nothing throws, so your app parses that error object instead of a todo list and renders an empty checklist. Request the scopes you need, then verify the scope claim in the decoded access token.

The resulting access token is itself a JWT. Its aud claim matches the resource you sent in step 2, its sub identifies the user, and its client_id is the resource client. This is the delegation chain made visible: user identity from step 1, admin policy from the resource connection, and app identity from your registration, all cryptographically bound into one credential.

Fetch data from the MCP server

With a token in hand, step 4 is regular MCP SDK code. Given a connected Client, which the next section builds, reading a resource takes one call:

const read = await client.readResource({ uri: 'todo0://todos' });

// A resource's contents can be text or binary, so narrow before parsing.
const first = read.contents[0];
const todos = first && 'text' in first ? JSON.parse(first.text) : [];

readResource() returns the user’s todo list as JSON. The playground’s MCP server exposes the todos as an MCP resource (read-only data at a URI) rather than a tool. Both primitives ride the same authenticated pipeline, so switching to a tool call is a one-line change to client.callTool() when your resource server offers tools.

Notice that the access token never appears in this code. You can attach it to the transport yourself through requestInit.headers, but the sample gives the transport an authProvider instead, and the SDK fetches the token, attaches it, and refreshes it when it expires.

CrossAppAccessProvider runs the whole flow

The sections above describe what each step sends and receives. Here is the code that runs all three, from src/xaa.ts:

import {
  Client,
  CrossAppAccessProvider,
  StreamableHTTPClientTransport,
  discoverAndRequestJwtAuthGrant,
  requestJwtAuthorizationGrant,
} from '@modelcontextprotocol/client';

const provider = new CrossAppAccessProvider({
  // Called when the transport needs an ID-JAG. The provider has already
  // discovered the authorization server and resource via RFC 9728.
  assertion: async (ctx) => {
    // idpTokenEndpoint is the IdP token endpoint this app cached during
    // sign-in, passed in by the caller. Falls back to discovery without it.
    const jagOptions = {
      audience: ctx.authorizationServerUrl.replace(/\/+$/, ''),
      resource: ctx.resourceUrl,
      idToken: await getIdTokenFromSession(),
      clientId: process.env.XAA_CLIENT_ID,
      clientSecret: process.env.XAA_CLIENT_SECRET,
      scope: ctx.scope ?? 'todos.read mcp.access',
      fetchFn: ctx.fetchFn,
    };
    const jag = idpTokenEndpoint
      ? await requestJwtAuthorizationGrant({ ...jagOptions, tokenEndpoint: idpTokenEndpoint })
      : await discoverAndRequestJwtAuthGrant({ ...jagOptions, idpUrl: 'https://idp.xaa.dev' });
    return jag.jwtAuthGrant;
  },
  clientId: process.env.MCP_CLIENT_ID,
  clientSecret: process.env.MCP_CLIENT_SECRET,
});

// Two adjustments for xaa.dev developer clients. First, they authenticate
// with client_secret_post, while the provider declares client_secret_basic
// by default. Declaring the method on the client information makes the SDK
// select the right one.
provider.saveClientInformation({
  client_id: process.env.MCP_CLIENT_ID,
  client_secret: process.env.MCP_CLIENT_SECRET,
  token_endpoint_auth_method: 'client_secret_post',
} as Parameters<typeof provider.saveClientInformation>[0]);

// Second, the provider only sends a scope when the server's metadata
// advertises one, and xaa.dev's does not. Without a scope parameter, the
// authorization server issues an empty-scope token, so add it here.
const prepareTokenRequest = provider.prepareTokenRequest.bind(provider);
provider.prepareTokenRequest = async (scope) => {
  const params = await prepareTokenRequest(scope ?? 'todos.read mcp.access');
  if (!params.has('scope')) params.set('scope', 'todos.read mcp.access');
  return params;
};

const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.xaa.dev/mcp'),
  { authProvider: provider },
);

const client = new Client({ name: 'xaa-requesting-app-typescript', version: '1.0.0' });
await client.connect(transport); // 401 -> discovery -> ID-JAG -> token -> retry

Walk through what the provider does on that one connect() call. It sends the first request without a token and receives a 401 with a WWW-Authenticate header pointing at the server’s protected resource metadata. It fetches that metadata, learns which authorization server protects this resource, and then fetches the authorization server’s metadata to find the token endpoint. It calls your assertion callback with the discovered URLs, exchanges the returned ID-JAG for an access token, stores the token, and then retries the original request. When the access token later expires, the next 401 response triggers the same sequence again, without any code from you. Both adjustments in the snippet come from testing this flow against the live playground.

Nothing in this snippet names auth.resource.xaa.dev. The provider discovered it, so the same client code works against any spec-compliant protected MCP server.

Where XAA fits in your real architecture

The playground stands in for real systems, and the mapping is direct. IdenX stands in for your production IdP. Okta offers Cross App Access as an Early Access feature, and the token exchange in this tutorial works the same way against an Okta org once you enable the feature; check the Okta Cross App Access documentation for current availability. To try it against a real org, sign up for an Okta Integrator Free Plan. The todo MCP server serves as an enterprise resource you can make available to agents and apps. Your requesting app serves as the AI agent or SaaS integration acting on the user’s behalf.

The read-only scope in this tutorial is a deliberate starting point, not a limitation of the protocol. Scopes are strings that your resource server defines and an admin grants. When you’re ready to build the other side of the boundary, the resource app guides show how to validate ID-JAGs and issue access tokens from your own authorization server, whether your app federates with OpenID Connect (OIDC) or Security Assertion Markup Language (SAML).

Learn more about Cross App Access, ID-JAG, and MCP

The complete source for this tutorial is in the okta-xaa-typescript-mcp-sdk-example repository. To keep exploring:

Remember to follow us on LinkedIn, X, and subscribe to our YouTube channel for more exciting content. We also want to hear from you about the topics you’d like to see and any questions you may have. Leave us a comment below!

Classic Engine Feature EOL: SSR, Desktop SSO, Device Trust

Fri, 18 Sep 2026 00:00:00 -0500

Starting March 5, 2027, Okta ends support for a few capabilities on Classic Engine. Identity and security requirements continue to evolve. Organizations expect authentication experiences that are more secure, flexible, and adaptable to changing users, devices, and applications. Okta invests in Okta Identity Engine, the modern foundation for passwordless authentication, device assurance, phishing-resistant multifactor authentication, and adaptive security policies.

By moving to Okta Identity Engine, you access an environment aligned with modern security practices that is stronger, more capable, and built to support how you protect access.

What’s changing in Okta Classic Engine

Here’s the full list of affected capabilities:

Self-Service Registration
Desktop Single Sign-On (Integrated Windows Authentication, or IWA)
Device Trust

Once support ends, Okta turns off these capabilities on Classic Engine, and you lose access to them unless you upgrade to Okta Identity Engine first. Okta no longer addresses bugs, security vulnerabilities, or broken flows associated with them after that date. Each capability moves to a modern, more secure approach within Identity Engine, where it continues to benefit from ongoing innovation.

Why upgrade to Okta Identity Engine

Identity Engine gives you authentication capabilities Classic Engine doesn’t have, including passwordless authentication, device assurance, and a modernized policy framework built on a newer authentication pipeline. The upgrade itself is free, you get all these capabilities at no additional licensing cost as part of your existing Okta subscription.

Identity Engine accelerates five core use cases:

Passwordless: Remove password from the sign-in flow entirely, instead of layering a second factor on top of it
Phishing-resistant: Close every route to the account, not just the front door. An account is only as phishing-resistant as its weakest enrollment and recovery path.
ID verification : Confirm that employees and customers are who they claim to be before you issue a credential or reset one
Zero trust: Identity and access management that goes beyond what NIST Authenticator Assurance Level (AAL) guidelines recommends
Device assurance: Fine-grained controls that check device posture as a condition of access

Okta Identity Engine elevates identity capabilities

Self-Service Registration allows end users to create their own accounts without administrator involvement. In Identity Engine, you use the Profile Enrollment Policy, which provides the same user self-service experience while enhancing security and modern account management.

Desktop Single Sign-On (SSO), specifically IWA, provides silent desktop authentication through on-premises infrastructure. Migrate to Agentless Desktop Single Sign-On (ADSSO) for modern desktop authentication without agents, or to Okta FastPass for passwordless platform authentication. Consult your Okta account team to determine which option fits your authentication and device management strategy.

Device Trust restricts app access to managed devices through Workspace ONE. In Identity Engine, migrate to management attestation with Okta Verify instead, which verifies that Okta Verify manages and trusts the mobile device before allowing access, providing enhanced device assurance beyond the previous Device Trust feature.

For step-by-step guidance on replacing these Classic Engine auth flows, see Replace Classic Engine authentication flows with Okta Identity Engine.

Planning your migration to Okta Identity Engine

Every organization’s environment differs, so your timeline and steps depend on your current configuration and feature usage. Reach out to your account executive for help and clarification on scheduling your upgrade.

Key timeline for Classic Engine capabilities sunsetting

Self-Service Registration, Desktop SSO (IWA), and Mobile Device Trust sunset on Classic Engine according to the timeline below.

Milestone	Date(s)
Initial notice	August 5, 2026
Reminders	September 7, October 7, and November 9, 2026; January 11, February 15, and March 1, 2027
End of support	March 5, 2027

Mark your calendar: March 5, 2027, is the hard deadline. Upgrade before then to avoid losing access to Self-Service Registration, Desktop SSO (IWA), and Device Trust on Classic Engine.

Best practices after your Okta Identity Engine upgrade

Not every Classic Engine feature carries over to Identity Engine. Identity Engine fully supports most features, and in most cases, a comparable feature is available. Your Okta field and upgrade teams tell you which features are unsupported and provide steps to migrate to the replacement feature.

If you have questions about any part of this transition, contact Okta Support or your account team.

Plan your migration now!

Schedule testing in a non-production environment before planning your production upgrade during an appropriate maintenance window. Contact Okta Support or your account team with any questions. You have until March 5, 2027, to complete your upgrade, so start your assessment now to make sure you land on the best upgrade window for your organization.

Resources to aid your Okta Identity Engine migration

If you’d like to learn more about identity and the concepts covered in this post, explore these official Okta resources:

Remember to follow us on LinkedIn and subscribe to our YouTube for more exciting content. Let us know how your Identity Engine upgrade goes in the comments below, we’d love to hear about it.

Supercharge Auth with Signals and the New Okta Angular SDK

Tue, 25 Aug 2026 00:00:00 -0500

Have you noticed that the Okta Angular SDK went fully standalone? There’s no NgModule left to import, no importProvidersFrom wrapper to remember, and the guards are plain functions now. If you’ve been waiting for the SDK to look like the rest of your standalone Angular app, this is the release you were waiting for.

In this post, we’ll pick up a small Angular v22 project and finish it. We’ll make the following changes:

Add authentication using the new provideOktaAuth provider function
Protect a route with the SDK’s functional guard
Load each user’s groups with rxResource and a signal input
Move the Okta configuration to runtime loading

We’re calling Okta’s APIs directly for this project, so we don’t have to stand up a separate backend. If you want to jump to the completed project, you can find it in the okta-angular-auth-signals-example GitHub repository. Otherwise, warm up your fingers and let’s get coding!

Note

This post is best for developers familiar with Angular. If you are an Angular newbie, start by building your first Angular app using the tutorial created by the Angular team.

Prerequisites

For this tutorial, you will need the following tools:

Node.js v22 or greater
Angular CLI
An Okta Integrator Free Plan account
A web browser with good debugging capabilities
Your favorite IDE
Terminal window (if you aren’t using an IDE with a built-in terminal)

Table of Contents

Get the starting Angular project
Secure the Angular app with OAuth 2.1 and OpenID Connect (OIDC) using Okta
- Grant API scopes to read users and groups
- Allow cross-origin requests and protect the access token
Add authentication with the standalone Okta Angular provider
Protect routes with functional route guards
Add users to your Okta org
Display users and review Angular’s rxResource API
Load a user’s groups with rxResource and a signal input
- Display group details using signal inputs
Load your Okta configuration at runtime
Learn more about Angular signals, standalone APIs, and OIDC

Get the starting Angular project

We’re starting from a project instead of building everything from scratch, because a pile of ng generate commands would distract us from the exciting coding parts. Open a terminal window and run the following commands to get a local copy of the starter and install dependencies. Feel free to fork the repo so you can track your changes.

git clone -b starter https://github.com/oktadev/okta-angular-auth-signals-example.git
cd okta-angular-auth-signals-example
npm ci

Open the project in your IDE and take a look around. I already added Okta Angular and Okta Auth JS to the project, along with a few pieces you’d otherwise spend the afternoon typing:

src/app/okta.ts is a service that calls Okta’s user management API. It uses the @Service() decorator to declare a singleton service.
src/app/okta.types.ts holds the OktaUser and OktaGroup interfaces
src/app/okta-auth.interceptor.ts attaches the access token and a proof of possession to Okta requests, and only to Okta requests
src/app/app.routes.ts has the routes, including the SDK’s OktaCallbackComponent on login/callback

Don’t run the app yet. It won’t start, and that’s on purpose – there’s no authentication configuration in the project. The service and the interceptor both ask Angular for an OktaAuth instance, and nothing provides one yet. That’s the first thing you’ll fix.

Secure the Angular app with OAuth 2.1 and OpenID Connect (OIDC) using Okta

You’ll use Okta to handle authentication and authorization for your Angular application securely.

Before you begin, you’ll need an Okta Integrator Free Plan account. To get one, sign up for an Integrator account. Once you have an account, sign in to your Integrator account. Next, in the Admin Console:

Go to Applications and Resources > Applications
Click Create App Integration
In the Sign in Method section, select OIDC - OpenID Connect
Select Single-Page Application as the application type, then click Next
Enter an app integration name
In the Grant type section, ensure that both Authorization Code and Refresh Token are selected
Configure the redirect URIs:
- Sign-in redirect URIs: http://localhost:4200/login/callback
- Sign-out redirect URIs: http://localhost:4200
In the Assignments section, assign a group or keep the default Everyone group assigned for all
Click Save

Where are my new app's credentials?

Creating an OIDC Single-Page App manually in the Admin Console configures your Okta Org with the application settings. You may also need to configure trusted origins for http://localhost:4200 in Security > API > Trusted Origins.

After creating the app, you can find the configuration details on the app’s General tab:

Client ID: Found in the Client Credentials section
Issuer: Found in the Issuer URI field for the authorization server that appears by selecting Security > API from the navigation pane.

Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta CLI Client or Okta PowerShell Module to automate this process. See this guide for more information about setting up your app.

Note the Client ID and the Issuer. You’ll need those values in a moment.

One important detail about that issuer. The credentials example above shows an issuer ending in /oauth2/default, which is the custom authorization server Okta creates for you. This project uses the org authorization server instead, so your issuer is your Okta domain with nothing after it, like https://{yourOktaDomain}. We need the org authorization server because it issues access tokens that the Okta management APIs accept, and reading users and groups is the entire point of this app.

In your own applications, you’ll most likely use a custom authorization server for your APIs, since that’s where you control scopes, claims, and access policies. Read Authorization servers to understand which one fits your case.

Grant API scopes to read users and groups

Our app asks Okta for a list of users and each user’s groups, but Okta won’t hand that over merely because we asked nicely. You must grant your application permission to make those calls.

Back in your Okta org, we have a couple of changes to make:

Navigate to Applications and Resources > Applications
Select the application you created
On the General tab, find the General Settings section and press Edit
Activate the Proof of possession checkbox then press Save
Open the Okta API Scopes tab, find okta.users.read, and press Grant

That single scope covers both calls this app makes. Listing a user’s groups counts as reading a user resource, so you don’t need okta.groups.read as well. Handy!

Allow cross-origin requests and protect the access token

Before the app can talk to Okta from a browser, we need to allow cross-origin requests:

Navigate to Security > API > Trusted Origins
Confirm you see http://localhost:4200 with both CORS and Redirect enabled

We’re taking a shortcut in the demo by calling the Okta management API directly from the Angular app. Okta’s APIs are a backend that’s already in place, which means we can take the SDK for a spin without having to stand up resource APIs ourselves.

The access token to call Okta’s APIs can perform sensitive admin actions, though, so let’s not send it around as a plain bearer token. Demonstrating Proof of Possession (DPoP) binds the token to a key pair that this browser generates and keeps to itself, so a stolen copy does a thief no good. The starter’s interceptor already sends the DPoP headers on every Okta request, so all that’s left is switching it on.

If you want to learn more about DPoP in an Angular app, you’ll want to check out:

Secure OAuth 2.0 Access Tokens with Proofs of Possession

Elevate access token security by demonstrating proof of possession (DPoP). Migrate a SPA to use DPoP in this hands-on project.

Alisa Duncan

Add authentication with the standalone Okta Angular provider

Here’s the part I’ve been looking forward to. Open src/app/app.config.ts. You already have an OktaAuth instance. Replace {yourOktaDomain} and {yourClientId} with the issuer URL and the client ID from the previous section. The issuer value should look something like https://integrator-123.okta.com.

There are a couple of OIDC properties worth calling out:

scopes includes okta.users.read alongside the usual OIDC scopes, which is how the access token ends up carrying the permission you granted a moment ago
dpop: true is the client half of the DPoP setting you switched on in the Okta app configuration. The SDK handles the key pair and the proof headers from here

With the OIDC configuration set, now it’s time to provide Okta authentication to the app. Update the app as shown:

export const appConfig: ApplicationConfig = {
  providers: [
    // other providers such as provideRouter and provideHttpClient here
    provideOktaAuth(
      withOktaConfig({ oktaAuth })
    )
  ]
};

Let’s talk through the code.

provideOktaAuth() is the provider function that registers the SDK. It sits in the providers array next to provideRouter and provideHttpClient, exactly like every other Angular provider function
withOktaConfig({ oktaAuth }) passes your configuration in

If you’ve added Okta to an Angular app before, compare that to what you used to write:

importProvidersFrom(
  OktaAuthModule.forRoot({
    oktaAuth: new OktaAuth({ /* config */ })
  })
)

The OktaAuthModule is gone, and so is the importProvidersFrom wrapper that existed only to drag an NgModule into a standalone app. Nothing left to bridge. That’s my favorite kind of API change – the kind where code disappears. 🎉

Protect routes with functional route guards

The dashboard route is wide open right now. Before we close it, let’s see the problem. Start the app:

npm start

Navigate straight to http://localhost:4200/dashboard without signing in. The page renders, the API calls fail, and you get an error message. Not a great experience for anyone.

Open src/app/app.routes.ts and add the guard to the dashboard route:

import { OktaCallbackComponent, canActivateAuthGuard } from '@okta/okta-angular';

export const routes: Routes = [
  // other routes here. We're only updating the dashboard route
  {
    path: 'dashboard',
    loadComponent: () => import('./dashboard/dashboard').then((m) => m.Dashboard),
    canActivate: [canActivateAuthGuard] // add the guard here
  }
];

The canActivateAuthGuard is a CanActivateFn, so it’s a function you drop into the canActivate array. There’s no guard class to instantiate and no provider to register. It has two siblings worth knowing about: canActivateChildAuthGuard for child routes, and canMatchAuthGuard, which pairs nicely with loadChildren because it can reject a route before Angular downloads the lazy-loaded bundle.

Try navigating to /dashboard while signed out now. Okta redirects you to sign in first. Much better!

Add users to your Okta org

When we sign in, we see a user table. And you’re in it!

However, a user portal with only one user isn’t much of a portal, so let’s add a few people to look at. Back in Okta:

Navigate to Directory > People and press Add person
Fill in with your favorite first name, last name, and username (email), then press Save
Repeat a couple of times

Add a totally made-up set of names for more fun. I went with Rosalind Park, Tobias Ferreira, and Ines Alvarez, but this is your org, and I’m not the boss of you.

Ensure you assign the users to your Okta app. Depending on your Okta app’s access policy, users may be automatically assigned to apps, but it’s always good to double check. You went through the effort to create users, so you want to see them in your dashboard, right?

Every user you create automatically joins the built-in Everyone group, which means the groups view you’re about to build has something to show from the first run. Thanks, Okta!

Display users and review Angular’s `rxResource` API

Time to see what we have. Back in the running app, take a closer look at that table.

Each row has a toggle button that currently does nothing. We’ll get there.

Before we do, open src/app/dashboard/dashboard.ts and look at how that table gets its data:

usersResource = rxResource({
  stream: () => this.okta.users(),
  defaultValue: []
});

That’s rxResource, the signal-based way to wrap an observable that loads data. You give it a stream, and it hands back a resource exposing value(), isLoading(), and error() as signals, which the template reads directly with @if and @for. No AsyncPipe, no subscription to unwind.

This resource loads once and never changes, because nothing it depends on ever changes. The groups resource you’re about to write is interesting because it has to reload every time you pick a different user.

Load a user’s groups with `rxResource` and a signal input

Generate a component for the groups view:

ng g c UserGroups --style=none --skip-tests

Open src/app/user-groups/user-groups.ts and replace the contents with this:

import { Component, computed, inject, input } from '@angular/core';
import { rxResource } from '@angular/core/rxjs-interop';
import { Okta as OktaService } from '../okta';
import { OktaUser } from '../okta.types';

@Component({
  selector: 'app-user-groups',
  imports: [],
  templateUrl: './user-groups.html'
})
export class UserGroups {
  private readonly oktaService = inject(OktaService);

  user = input.required<OktaUser>();

  groupsResource = rxResource({
    params: () => this.user().id,
    stream: ({ params: userId }) => this.oktaService.groups(userId),
    defaultValue: []
  });
}

Let’s step through the key parts:

user = input.required<OktaUser>() takes the user from the parent component. Inputs declared with the input() function are signals, which matters a lot for the next line.
params is where the reactivity lives. Reading this.user().id inside params subscribes the resource to that signal, so when the parent passes a different user, params recomputes, and the resource fetches that user’s groups on its own. You don’t wire up an effect, and you don’t call a reload method.
stream receives the resolved params and returns the observable to subscribe to. Destructuring it as { params: userId } keeps the call readable.
defaultValue: [] means value() is an empty array instead of undefined before the first response, so the template doesn’t need a null check.

Create two computed properties, the groupCount and displayGroups properties, in the component below the groupsResource definition:

groupCount = computed(() => this.groupsResource.value().length);
displayGroups = computed(() => this.groupsResource.value().slice(0, 3));

The two computed properties derive from the resource, and they intentionally disagree with each other. groupCount reports every group the user belongs to, while displayGroups caps the list at three. Users in a real org can belong to a long list of groups, and I’d rather show an honest count than let a wall of panels shove the table off your screen.

Now the template. Open src/app/user-groups/user-groups.html and add:

<h2 class="mb-4 text-sm font-semibold text-gray-700">
  {{ user().profile.firstName }} {{ user().profile.lastName }} groups
</h2>

@if (groupsResource.isLoading()) {
  <p class="text-sm text-gray-500">Loading groups...</p>
} @else if (groupsResource.error()) {
  <p class="text-sm text-red-600" role="alert">Failed to load groups.</p>
} @else {
  <p class="py-3">Group count: {{ groupCount() }}</p>

  <div class="grid gap-3 sm:grid-cols-2">
    @for (group of displayGroups(); track group.id) {
      <p>show group info here</p>
    } @empty {
      <p class="text-sm text-gray-500">No groups found.</p>
    }
  </div>
}

Notice the template reads isLoading() and error() straight off the resource, so the loading and failure states come along for free. We’ll replace that show group info here placeholder in the next section.

The next step is handing the component a user. Open src/app/dashboard/dashboard.html and find the row that appears when you toggle a user. Replace its placeholder content with the new component:

<app-user-groups [user]="user" />

Then add UserGroups to the dashboard’s imports array in src/app/dashboard/dashboard.ts:

import { UserGroups } from '../user-groups/user-groups';

@Component({
  selector: 'app-dashboard',
  imports: [UserGroups],
  templateUrl: './dashboard.html'
})

Feel free to start the app and press the toggle on a user. You’ll see a group count of 1 and a single show group info here for the Everyone group. Toggle a different user and watch the panel refill itself – that’s params doing its job. Pretty sweet!

Display group details using signal inputs

The placeholder has served us well, and now it can go. Generate a component for a single group:

ng g c user-groups/group-panel --inline-template --style=none --skip-tests

Open src/app/user-groups/group-panel/group-panel.ts and replace the contents:

import { Component, input } from '@angular/core';

@Component({
  selector: 'app-group-panel',
  template: `
    <div class="rounded-xl border border-gray-200 bg-white p-4 shadow-sm">
      <h3 class="mb-1 text-base font-semibold text-gray-800">{{ heading() }}</h3>
      <p class="text-sm text-gray-600">{{ description() }}</p>
    </div>
  `
})
export class GroupPanel {
  heading = input.required<string>();
  description = input<string>('');
}

This component has no services, no resources, and no idea Okta exists. It takes two inputs and renders them; the separation of concerns is exactly what we want. It makes this component reusable and minimal. Note description has a default of '', because group descriptions in Okta are optional.

Back in src/app/user-groups/user-groups.html, swap the placeholder <p>show group info here</p> for the panel:

<app-group-panel
  [heading]="group.profile.name"
  [description]="group.profile.description ?? ''"
/>

Then import it into the UserGroups component:

import { GroupPanel } from './group-panel/group-panel';

@Component({
  selector: 'app-user-groups',
  imports: [GroupPanel],
  templateUrl: './user-groups.html'
})

Start the app and toggle a user open.

This app is basic, but the data is real, and it reloads when it should. 🏆

One group per user works, but it could be more exciting. We can create more groups and add our users to them.

Back in your Okta org, navigate to Directory > Groups, press Add group, and create a group with a name and description. Then add a couple of your users to it. Read Manage groups if you want the full details. Toggle that user open again, and you’ll see the new panel show up alongside Everyone.

Load your Okta configuration at runtime

Right now, app.config.ts hardcodes the Okta configuration, so changing your issuer or client ID means a rebuild and a redeploy. If you’d rather fetch those values when the app starts, the new SDK still supports it. I wrote about this pattern in Flexible Authentication Configurations in Angular Applications Using Okta, and the good news is it survived the move to standalone providers.

The change has two halves. Set the configuration during app initialization and call provideOktaAuth() with no configuration. Something like this:

async function configInitializer(configService = inject(OktaAuthConfigService)): Promise<void> {
  const response = await fetch('/api/config.json');
  if (!response.ok) {
    throw new Error(`Couldn't load the Okta configuration: ${response.status}`);
  }
  const authConfig = await response.json();

  configService.setConfig({
    oktaAuth: new OktaAuth({
      ...authConfig,
      redirectUri: `${window.location.origin}/login/callback`,
      scopes: ['openid', 'profile', 'offline_access', 'email', 'okta.users.read'],
      pkce: true,
      dpop: true
    })
  });
}

export const appConfig: ApplicationConfig = {
  providers: [
    // remaining providers
    provideAppInitializer(configInitializer),
    provideOktaAuth(),
  ]
};

Let’s talk through what changed.

provideOktaAuth() now takes no withOktaConfig() feature. The SDK treats its configuration as optional at provide time, and builds the OktaAuth instance the first time something injects it, which is after initialization finishes.
provideAppInitializer() replaces the old APP_INITIALIZER multi-provider. It takes a plain function, so you inject() your dependencies inside it rather than declaring a deps array. Return a promise, and Angular waits for it before starting the app.
fetch reads the configuration. We’re not using Angular’s HttpClient here, and we’re not coding workarounds to get around the interceptor either.
response.ok guards the parse. When that path 404s, most servers hand back an HTML error page, and response.json() fails with a parse error that tells you nothing about what actually went wrong.

One sequencing detail that will bite you later if you don’t know it now: inject() has to run before your first await. Once you await, you’ve left the injection context and inject() throws. Evaluating it in the parameter list works, as does calling it on the first line of the body. 👀

Runtime configuration lets you point the same app to a different Okta org without rebuilding it. Still the ultimate flexibility!

Before you move on, let’s talk about what belongs in that config file. Fetching it without an access token is fine here. The request stays on your own origin, and the values it returns are already public. The JavaScript bundle includes your issuer and client ID. Anyone can read them out of your app today.

⚠️	Heads up! Anyone can request `/api/config.json`, so nothing sensitive goes in it. This is a browser-based app, which means it cannot keep a secret. A single-page app can’t maintain secrets. If a value would hurt you when published, it belongs on a server you control.

Learn more about Angular signals, standalone APIs, and OIDC

In this post, you added authentication to a standalone Angular app with provideOktaAuth, protected a route with a functional guard, and loaded each user’s groups with rxResource driven by a signal input. I hope you enjoyed it! You can find the completed project in the okta-angular-auth-signals-example GitHub repository.

If you liked this post, check out these resources.

Remember to follow us on LinkedIn and subscribe to our YouTube for more exciting content. We also want to hear from you about topics you’d like to see and any questions you may have. Leave us a comment below!

Add Cross App Access to Your OIDC Resource Application

Mon, 24 Aug 2026 00:00:00 -0500

If you currently federate enterprise customers using OpenID Connect (OIDC) and want to allow applications to access your API on behalf of those users, this Cross App Access (XAA) guide is for you.

The Identity Assertion Authorization Grant specification, the basis of XAA, was designed with OIDC in mind. Your authorization server already trusts the customer’s IdP for single sign-on (SSO), and XAA reuses that same trust for API access. This guide details what you need to support, how to validate the grant, and how to resolve the user at your resource authorization server.

Table of Contents

How XAA in OIDC works
Analyzing the ID-JAG claims
XAA implementation checklist for OIDC-federated applications
Making cross-application requests from your OIDC app securely
Configure your XAA OIDC Resource app in Okta
Verify your Okta XAA setup on xaa.dev
Takeaways for implementors who also have SAML apps
Learn more about Cross App Access, OIDC, and OAuth 2.0

How XAA in OIDC works

When an agent (like one running in Claude) needs API access, it presents an Identity Assertion Authorization Grant (ID-JAG). The ID-JAG is a short-lived JSON Web Token (JWT) issued by the customer’s Identity Provider (IdP) for your authorization server. Your resource server accepts the token, identifies the user, and issues your own access token, all while leaving the customer’s existing OIDC integration untouched.

The sequence diagram shown below describes the OIDC XAA flow. Notice that the OIDC SSO flow stays the same; the only change is the section highlighted with the comment “Your Resource Authorization Server (AS): redeem and resolve”. You’ll make a POST request to your resource’s authorization server with the ID-JAG, resolve the subject, and return an access token that you’ll use for resource requests.

⚠️ Note

You are not participating in the client’s SSO here. The only artifact crossing from the IdP to your domain is the ID-JAG. Everything upstream, including authentication, ID token issuance, and the token exchange, happens without you. Your responsibility is to validate the ID-JAG, redeem it for an access token, and resolve the user from the claims.

Analyzing the ID-JAG claims

When you decode the ID-JAG, you’ll see claims in the header and payload that impact how you process the access request:

// header
{
  "typ": "oauth-id-jag+jwt",
  ...
}

// payload
{
  "iss": "https://atko.okta.com",
  "sub": "00u1a2b3c4D5e6F7g8h9",
  "aud": "https://auth.chat.example",
  "client_id": "0oa8claudeMcpAtYourAS",
  "email": "alice@atko.com",
  "scope": "chat:read chat:write",
  "jti": "id-jag-7f3c9a21b8",
  ...
}

Focus on these key claims noted in the decoded ID-JAG payload:

iss + sub: Together, these are the primary key for user resolution. Neither one is unique on its own
aud: Indicates the issuer identifier for your resource authorization server
client_id: This is the client’s ID at your resource authorization server, which might differ from its ID at the IdP
email: Recommended by the specification for just-in-time provisioning if the user has not yet signed in
jti: The unique ID for this ID-JAG JWT, as required by JWT conventions

Three optional claims matter if you run a multi-tenant service: the tenant claim scopes the subject when the IdP itself is multi-tenant, aud_tenant scopes the subject when your resource authorization server is multi-tenant, and aud_sub carries the identifier that the IdP believes you already have for this user.

XAA implementation checklist for OIDC-federated applications

To fully support Cross App Access, implement these four steps in sequence:

Mapping user identity from iss and sub
Validating the ID-JAG and resolving the user
Issuing the access token
Updating authorization server metadata

Mapping user identity from `iss` and `sub`

You already resolve users from the sub claim during SSO, so the ID-JAG uses the identifier you know. The sub claim alone is not the key, though.

A sub value is only unique when scoped with the issuer. Resolve on iss + sub together. If the IdP is multi-tenant, the scope is iss + tenant + sub, and you’ll need the tenant claim to disambiguate. Two customers on the same multi-tenant IdP can otherwise collide.

If the user hasn’t signed in to your app yet, there’s no local record to resolve. Use the email claim, or aud_sub when the IdP supplies it, to provision just in time. Treat email as a linking hint rather than a primary key. Email addresses get reassigned when employees leave, and iss + sub does not.

Validating the ID-JAG and resolving the user

The client posts the ID-JAG as a JWT authorization grant and authenticates with its credentials at your server. Below is an example HTTP request for requesting an access_token:

POST /oauth2/v1/token HTTP/1.1
Host: chat.example
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=eyJ0eXAiOiJvYXV0aC1pZC1qYWcrand0...

Before processing, you must bind the ID-JAG’s iss to a registered IdP connection to prevent forgery.

If you verify the signature before checking the issuer binding, an attacker could stand up their own IdP, sign a token, and present a sub belonging to one of your users.

Always resolve the connection from the iss first, then verify the signature against that connection’s key. You’ll compare this using the JSON Web Key Set (JWKS) metadata.

Below is the pseudocode for implementing the validation and resolving a user:

connections = {
  "https://atko.okta.com": {
    jwks:        "https://atko.okta.com/oauth2/v1/keys",
    multiTenant: false,
    allowJit:    true,
  },
}

redeem(idJag, authenticatedClient):
    // 1. Bind iss to a connection before trusting the signature.
    iss  = unverified_issuer(idJag)
    conn = connections[iss]
    if conn is none: reject "invalid_grant"

    // 2. Verify signature against the specific issuers JWKS.
    payload = verify_jwt(idJag, jwks = conn.jwks)
    if payload is invalid: reject "invalid_grant"

    // 3-5. Perform remaining checks.
    require payload.typ       == "oauth-id-jag+jwt"
    require payload.aud       == "resource_authorization_server_url"
    require payload.client_id == authenticatedClient.id

    user  = resolveSubject(payload, conn)
    scope = applyScopePolicy(user, payload.scope)
    return issueAccessToken(user, scope)

resolveSubject(payload, conn):
    require payload.sub
    if conn.multiTenant: require payload.tenant

    user = lookup_user_by_federated_id(payload.iss, payload.tenant, payload.sub)
    if user is none and conn.allowJit:
        user = provision_user(payload.iss, payload.tenant, payload.sub, payload.email)

    if user is none: reject "invalid_grant"
    return user

Issuing the access token

Once you resolve the user, issue an access_token scoped according to your local policy. Below is an example of an access_token returned after successfully validating the ID-JAG and resolving the user.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "token_type": "Bearer",
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "expires_in": 86400,
  "scope": "chat:read chat:write"
}

⚠️ Note

Do not issue a refresh token. If your authorization server issues a refresh token, the client has durable access to your resource server, and the IdP cannot revoke access.

The ID-JAG replaces the need for a refresh token. On access token expiry, the client resubmits the same ID-JAG to your token endpoint, and you mint a new access token against it. Only once the ID-JAG itself expires does the client return to the IdP for a new one.

Updating authorization server metadata

Clients locate your XAA support via your authorization server metadata (/.well-known/oauth-authorization-server). Ensure you include the supported fields:

{
  "issuer": "https://chat.example",
  "token_endpoint": "https://auth.chat.example/oauth2/v1/token",
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ],
  "authorization_grant_profiles_supported": [
    "urn:ietf:params:oauth:grant-profile:id-jag"
  ]
}

Publish the profile identifier and nothing more. Don’t list the issuers you trust in public metadata, since that discloses your customer relationships. If clients need to check whether you accept a given issuer, put that check behind client authentication.

Making cross-application requests from your OIDC app securely

With these four steps complete, you’ve configured your OIDC application for Cross App Access. Agents can now authorize requests against your API using the federation you already run.

You can now use Okta to make cross-application requests with your OIDC app.

Before you configure anything, here’s who runs what in this walkthrough:

Component	Role
Your resource server and API	Runs on your infrastructure. The service XAA protects.
Your resource authorization server (your resource AS)	Runs on your infrastructure. Mints and validates the access tokens your API accepts.
Your Okta org	The IdP. Authenticates users and issues the ID-JAG.
The Okta app integration representing your resource app	A registration in Okta, not a running service. Holds the XAA configuration Okta uses to mint ID-JAGs for your resource AS.
The Okta app integration representing the requesting app	A registration in Okta, not a running service. Lets users sign in to the AI agent and lets Okta issue ID-JAGs on its behalf.
xaa.dev	Plays the requesting app for this walkthrough, running against your resource server.

xaa.dev drives the requesting side so you can verify the resource side, which is the only side you’re actually building.

Configure your XAA OIDC Resource app in Okta

This walkthrough tests an XAA implementation, it doesn’t build one. Before you continue, you’ll need already running:

Your resource AS, with a reachable issuer URL and token endpoint
The ability to register an OAuth client at your resource AS and issue it a client ID and secret, since the requesting app authenticates there at redemption
The ID-JAG redemption logic from the checklist earlier in this post, implemented
An API endpoint that accepts the access token your resource AS issues

If you haven’t built these yet, work through the checklist sections above first.

You’ll also need:

An Okta Integrator Free Plan account. Sign up for a new account to test out the XAA feature
xaa.dev to drive the requesting side while you test your resource server

See the guide’s prerequisites for AI agent-to-app XAA for the underlying Okta org requirements.

Open the xaa.dev resource app tester and enter any validly formatted email address to establish a session
In Your IdP’s issuer URL, enter your Okta org issuer URL. This is the IdP field, not the resource AS issuer URL field further down the panel. For example, https://integrator-xxxxxx.okta.com
Copy the generated Sign-in redirect URI, for example https://auth.resource.xaa.dev/api/federated-sso/callback/resapp-oidc-xxxxxxx. You’ll paste it into the requesting app integration in the next section
Leave the tab open. You’ll return to it after the Okta configuration is complete

Create the OIDC requesting app for testing

You’ll need a requesting app integration and a resource app integration set up in Okta. Create the requesting app integration by following the guide’s OIDC app creation steps, using these tutorial-specific values:

App integration name: “Requesting App”
Grant type: Authorization Code, plus Refresh Token — you’ll need it to request the ID-JAG
Sign-in redirect URIs: the Sign-in redirect URI you copied from xaa.dev above
Assignments: keep Skip group assignments for now

General configuration

Select the General tab and copy the Client ID and Client secret. Paste both into the requesting app fields at xaa.dev and save.

Assignments configuration

Assign your test user to the requesting app integration. See Assign an app integration to a user.

Note: The values here come from your Resource Authorization Server.

Create the OIDC resource app in Okta

Create the resource app integration the same way you created the requesting app integration, and use these tutorial-specific values:

App integration name: “Resource App”
Grant type: Authorization Code
Sign-in redirect URIs: any valid placeholder URL. This app integration never performs an interactive login in this walkthrough; it only holds the Resource Server XAA configuration and the user assignment, and Okta requires the field to be non-empty. Don’t reuse the xaa.dev URI here
Assignments: keep Skip group assignments for now

After creating the app integration, select the General tab to get the Client ID and Client secret. Use these credentials in your resource server.

Resource Server extra configuration

Enable Cross App Access (XAA) on the resource app integration from the Resource Server tab, and configure: Note: The values here come from your test Requestor SSO App on xaa.dev.

Issuer URL: Your resource AS issuer URL, the issuer of the authorization server you run. Entering it here tells Okta which external server to mint ID-JAGs for; Okta doesn’t host this server. This value becomes the aud claim in the ID-JAG and cannot change without deleting and resetting the connection.
Audience/tenant ID: This is optional and not needed for this walkthrough

⚠️ Note

This Issuer URL (your resource AS issuer URL) must exactly match the Resource AS issuer (ID-JAG audience) field you’ll enter on xaa.dev during verification. A mismatch still produces a correctly signed ID-JAG, but redemption fails the aud check, and that’s the hardest failure in this tutorial to diagnose.

Assignments configuration

Assign your test user to the resource app integration. See Assign an app integration to a user.

Register and configure the AI Agent in Okta

With your requesting app integration and resource app integration configured, register a new AI Agent in Okta. During registration, you’ll link your requesting app integration under User access and authentication, register the agent’s own OAuth client, and then connect the resource app integration as a Resource Connection.

Register the AI Agent and link your requesting app integration

Name: “Agent”
Allow users to access this agent: Select an existing app, then choose “Requesting App”
Add owners: assign your test user as an individual owner

This linked app integration is what your users sign in through to reach the agent: they authenticate against it, and the agent then acts on their behalf.

Connect the resource app integration

Add a resource connection to the AI agent. Use these tutorial-specific values:

Application instance: “Resource App”
AI agent’s client ID registered in this app: “this app” here means your resource AS, not the Okta app integration. Enter the client ID you issued to the AI agent when you registered it as an OAuth client at your resource AS. You perform that registration outside Okta, and the process varies by product
Scopes: Allow any scope

Activate the AI Agent

Activating the linked requesting app integration usually activates the AI Agent. If the agent’s status is STAGED, activate it manually.

Once the AI Agent is active, the configuration is complete. Except for Machine access, all checkmarks on the agent configuration page must be green.

Verify your Okta XAA setup on xaa.dev

Open the AI Agent you created, then go to Client registration tab: You’ll see the agent uses the same credentials as the linked requesting app. We will use this client ID and secret to request an ID-JAG from the IdP.

In xaa.dev, enter the following values:

Client ID: Use the values from the AI Agent’s client registration tab.
Client Secret: Use the values from the AI Agent’s client registration tab.
Resource AS issuer (ID-JAG audience): Use your resource AS issuer URL. This must exactly match the Issuer URL you set on the resource app integration’s Resource Server tab.
Scopes: Enter the scopes you want to request for the access token. For example, chat:read chat:write.
Press Save to store the values.

By this point, you’ll have every value from the checklist and your one-time Okta setup in place (AI Agent, owner, delegation, and resource connection), so we’ll add the values from Okta and the apps to walk through the flow step by step, one button per step.

Configure OIDC SSO

Press Start OIDC login at your IdP and complete the login in the pop-up.

When it closes, the step turns green and shows a ✓ Auto-discovered SSO endpoint, confirming that the tester resolved the real authorization and token endpoints from your org’s discovery document and returned an ID token and a refresh token.

Verify the refresh token exchange for an ID-JAG token

Press Exchange refresh token for ID-JAG. The tester posts the refresh token from sign-in to your IdP’s token endpoint and returns a decoded ID-JAG. Take a second to review it: aud should equal your resource authorization issuer, and sub should be the identifier for the user who logged in. A 200 OK indicates that the step succeeded.

Redeem the ID-JAG for an access token at the resource authorization server

Fill in your resource AS token endpoint
The client ID and secret you issued to the AI agent when you registered it as an OAuth client at your resource AS. This must be the same client ID you entered in the resource connection step, or redemption fails the client_id check

Press Redeem (grant_type=jwt-bearer). If the request succeeds, you’ll receive a 200 OK response with an access token. Inspect the token in the Token tab to verify that the iss, aud, and scope claims match the values configured in your resource authorization server. This validation confirms that the authorization server accepted the ID-JAG and issued its own access token.

Call the resource API with the access token

Select the request method and enter your API URL (xaa.dev adds the Authorization: Bearer header automatically, but you can add any other headers or a request body as needed), then press Send GET Request. A 200 response from your endpoint is the final proof: your API accepts the access token generated by the ID-JAG exchange.

Prove the XAA connection end-to-end

A green Conformance passed panel appears. Select Export conformance log (JSON) to download the test results. The export includes the signed ID-JAG, the access token returned by your resource authorization server, and the API response.

You can either download the log or have a URL to share with your IdP as proof that the Cross App Access integration works successfully.

Takeaways for implementors who also have SAML apps

If some of your enterprise customers federate over SAML instead, here’s what changes when you extend XAA to those connections:

The subject arrives in a sub_id claim using the saml-nameid format, rather than in sub
Match on every saml-nameid member (issuer + NameID + sp_name_qualifier), rather than on iss and sub
Everything else, including token issuance rules and redemption checks, remains as is

Learn more about Cross App Access, OIDC, and OAuth 2.0

If this guide helped you implement Cross App Access with OIDC, explore these resources:

📘 Cross App Access Documentation: Official guides for configuring and managing Cross App Access in production.
🎙️ Developer Podcast on MCP and Cross App Access: Hear the backstory, use cases, and why this matters for developers.
📋 How to Build and List Secure Cross App Access (XAA) Connections on Okta Integration Network (OIN)

Identity 101:

Add Cross App Access to Your OIDC Requesting Application

Fri, 21 Aug 2026 00:00:00 -0500

If you currently federate enterprise customers using OpenID Connect (OIDC) and want to connect with third-party applications, this Cross App Access (XAA) guide is for you.

The Identity Assertion Authorization Grant specification, the basis of XAA, was designed with OIDC in mind. Your app already holds an ID token after sign-in, but it’s the refresh token from that same sign-in that you exchange to reach a third-party app. This guide details what you need to support and how to make resource requests to a third-party app using XAA.

Table of Contents

How XAA in OIDC works
XAA implementation checklist for OIDC-federated applications
Making cross-application requests from your OIDC app securely
Configure your XAA OIDC requesting app in Okta
Learn more about Cross App Access, OIDC, and OAuth 2.0

How XAA in OIDC works

When an agent (like one running in Claude) needs API access, it presents an Identity Assertion Authorization Grant (ID-JAG). The ID-JAG is a short-lived JSON Web Token (JWT) issued by the Identity Provider (IdP) for your app’s user. You exchange the ID-JAG token for an access token to the resource application you’re connecting with.

The sequence diagram below describes the OIDC XAA flow and how your application fits into it. You’ll handle the flow in two parts: where your application requests the ID-JAG from the IdP using the refresh token, and where your app requests the access token from the ID-JAG from the third-party resource app’s authorization server.

XAA implementation checklist for OIDC-federated applications

Follow the guide in this section to support XAA in your OIDC application when your app connects to a third-party resource application. The XAA flow places the burden of token validation onto the IdP and the resource app’s authorization server. The initial sign-in step remains the same; however, you’ll add two requests before getting an access token to make the resource API call.

Once the user completes signing in, you’ll:

Request the ID-JAG token from Okta using the refresh token
Request the OAuth access token from the third-party resource app’s OAuth authorization server
Use the access token to make the API request to the resource app

Request the ID-JAG token

Your OIDC application runs the authorization code flow as usual, requesting the offline_access scope, and receives an ID token and a refresh token at the callback. The ID token is still there for your app’s session, but the refresh token is the credential for the exchange, so hold on to it for the session.

When your application needs resources from a third-party app, exchange the refresh token for an ID-JAG at Okta’s /token endpoint. This exchange follows the OAuth 2.0 Token Exchange (RFC 8693) mechanism. Authenticate the request with the client credentials from your OIDC app using client_secret_post.

POST /oauth2/v1/token HTTP/1.1
Host: your-okta-domain.okta.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=<the refresh token from sign-in>&
subject_token_type=urn:ietf:params:oauth:token-type:refresh_token&
requested_token_type=urn:ietf:params:oauth:token-type:id-jag&
audience=<the resource app's authorization server issuer URI>&
resource=<the resource app's API base URL>&
scope=<the resource app's required scopes>&
client_id=<your_client_id>&
client_secret=<your_client_secret>

The IdP responds with a short-lived, signed JSON Web Token (JWT), the ID-JAG, as the value in the access_token property within the payload.

Request the access token

Redeem the ID-JAG at the resource app’s authorization server’s token endpoint. The resource app’s authorization server handles the redemption request, not the IdP. This request uses the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523). The ID-JAG is the assertion now, and you include the scopes required for the resource request. The scope matches the scopes requested in the ID-JAG request. The HTTP request looks something like:

POST /token HTTP/1.1
Host: the-resource-server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(resource_as_client_id:resource_as_client_secret)>

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=<ID-JAG token>&
scope=todos.read

In the example HTTP request, the Authorization header uses the Basic scheme as a demo. Use the authorization scheme required by the resource application.

The response payload contains the access_token property, whose value is the access token.

Call the resource API

Use the access token to make the API resource request by using the value in the Authorization header. For example:

GET /api/todos/ HTTP/1.1
Host: the-resource-server.example.com
Authorization: Bearer <access_token>
Accept: application/json

Handle token expiration

ID-JAG tokens have a short timeline by design. When it expires, request a new ID-JAG using the same refresh token. Refresh tokens are long-lived, so you don’t need to send the user back to sign in again for every ID-JAG. Refresh tokens eventually expire or get revoked, too. If the IdP rejects it (you’ll see an invalid_grant error), send the user through sign-in again to get a fresh one.

Making cross-application requests from your OIDC app securely

With these steps complete, you’ve configured your OIDC application for Cross App Access. Your app can now obtain access tokens for third-party resource apps, using the federation you already run.

You can now use Okta to make cross-application requests from your OIDC app to third-party resource apps.

Before you configure anything, here’s who runs what in this walkthrough:

Component	Role
Your requesting app and its code	Runs on your infrastructure. The application XAA let’s reach third-party resource apps
Your Okta org	The IdP. Authenticates your users and issues the ID-JAG
The Okta app integration representing your requesting app	A registration in Okta, not a running service. Let’s your users sign in and let’s Okta issue ID-JAGs on your app’s behalf
The Okta app integration representing the test resource app	A registration in Okta, not a running service. Holds the XAA configuration Okta uses to mint ID-JAGs for xaa.dev’s resource authorization server
xaa.dev’s resource authorization server	Runs on xaa.dev’s infrastructure, not yours. Mints and validates the access tokens the test resource app accepts
xaa.dev’s resource API server	Plays the test resource app for this walkthrough, running against your requesting app

xaa.dev stands in for the third-party resource app so you can verify the requesting side, which is the only side you’re actually building. Ownership here is the reverse of the companion resource-app post: there, xaa.dev played the requesting side while you built the resource side; here, xaa.dev plays the resource side while you build the requesting side.

Configure your XAA OIDC requesting app in Okta

Let’s configure your OIDC requester application in Okta. Before you begin, you’ll need:

Values from your app (we’ll walk through the values needed below)
An Okta Integrator Free Plan account. Sign up for a new account to test out the XAA feature
xaa.dev for testing your requesting app

Register the requesting app in Okta

Create the Okta app integration representing your requesting app by following the guide’s OIDC app creation steps, using these tutorial-specific values:

App integration name: “Requesting App”
Grant type: Authorization Code, plus Refresh Token under Core Grants. You’ll need a Refresh Token to request the ID-JAG
Sign-in redirect URIs: the callback URL of your requesting app, e.g., “https://requester-app-uri/callback”
Sign-out redirect URIs: the sign-out URL of your requesting app
Assignments: keep Skip group assignments for now

After creating the app integration, copy the Client ID and Client secret from the General tab and add them to your requesting app. Your app uses these same credentials for sign-in and for the ID-JAG token exchange.

Assign your test user to the requesting app integration. See Assign an app integration to a user.

With your requesting app integration registered, you’ll need an Okta app integration representing the test resource app next.

Register the test resource app in Okta

Create the Okta app integration representing the test resource app by following the guide’s OIDC app creation steps, using these tutorial-specific values:

App integration name: “Resource App for Testing”
Sign-in redirect URIs: https://idp.xaa.dev/oidc-resource/callback
Assignments: keep Skip group assignments for now

⚠️ Note: These values are for setup only; they don’t constitute a working single sign-on (SSO) connection to the test resource app.

Assign your test user to this app integration the same way you did for the requesting app integration above.

Resource Server extra configuration

Enable Cross App Access (XAA) on this app integration from the Resource Server tab, and configure:

Issuer URL: Use https://auth.resource.xaa.dev. This is xaa.dev’s resource authorization server, not yours. Entering it here tells Okta which external server to mint ID-JAGs for
Audience/tenant ID: This is optional and not needed for this walkthrough

⚠️ Note: Use Audience/tenant ID when you have multiple tenants in your organization.

With the test resource app integration configured in Okta, register your requesting app at xaa.dev next.

Register your requesting app at xaa.dev

Go to Test your requesting app. Add your IdP issuer URL as your Okta Integrator account ID (i.e., https://your-okta-domain.okta.com). Put your email into the Test user identifier, for example, name1234…@okta.com. After you enter all values, click Register.

Registering here registers your requesting app as an OAuth client at xaa.dev’s resource authorization server, and returns a Client ID and Client Secret. Save them. Use this Client ID in the AI agent’s resource connection in the next section.

When you get to the token exchange later in this walkthrough, substitute these values:

audience: https://auth.resource.xaa.dev, xaa.dev’s resource authorization server (AS) issuer URL
scope: todos.read, the scope required to call the test resource app’s API
resource: https://api.resource.xaa.dev, xaa.dev’s resource API base URL

Keep this site open; you’ll return to it to run the validation flow after the Okta configuration is complete.

Register and configure the AI Agent in Okta

With your requesting app integration and the test resource app integration configured, register a new AI Agent in Okta. During registration, you’ll link your requesting app integration under User access and authentication, register the agent’s own OAuth client, and then connect the test resource app integration as a Resource Connection.

Register the AI Agent and link your requesting app integration

Name: “Agent”
Allow users to access this agent: Select an existing app, then choose your requesting app integration (e.g., “Requesting App”)
Add owners: assign your test user as an individual owner

This linked app integration is what your users sign in through to reach the agent: they authenticate against it, and the agent then acts on their behalf.

Open the AI Agent you created, then go to the Client registration tab: you’ll see the agent uses the same credentials as the linked requesting app integration. You’ll use this client ID and secret to request an ID-JAG from the IdP.

Connect the test resource app integration

Add a resource connection to the AI agent. Use these tutorial-specific values:

Application instance: “Resource App for Testing”
AI agent’s client ID registered in this app: the Client ID from xaa.dev (it should look similar to byora...)
Scopes: Allow any scope

Activate the AI Agent

Activating the linked requesting app integration usually activates the AI Agent. If the agent’s status is STAGED, activate it manually.

Once the AI Agent is active, the configuration is complete. Except for Machine access, all checkmarks on the agent configuration page must be green.

Validate the XAA connection end-to-end

Once the Okta setup is complete, sign in to your requesting app and trigger whatever action in your code path calls the test resource app, for example, a button that fetches its data. That single action should exercise all three checklist requests in sequence: your app requests the ID-JAG, redeems it for an access token at xaa.dev’s resource authorization server, and calls the test resource app’s API with that token.

Then return to xaa.dev and open the Live verification tab. A green Conformance passed panel appears. This confirms all steps:

Auth Server accepted your ID-JAG
An access token was issued
Resource Server accepted your access token
The API call to /api/todos/ was successful

In the companion resource-app post, xaa.dev acts as the client, and you observe the result. Here, your requesting app acts as the client, and xaa.dev observes it.

At this stage, the JSON conformance log has the complete details of the XAA flow. You can either download the log or share a URL with your IdP.

Learn more about Cross App Access, OIDC, and OAuth 2.0

If this guide helped you implement Cross App Access with OIDC, explore these resources:

📘 Cross App Access Documentation: Official guides for configuring and managing Cross App Access in production
🎙️ Developer Podcast on MCP and Cross App Access: Hear the backstory, use cases, and why this matters for developers
📋 How to Build and List Secure Cross App Access (XAA) Connections on Okta Integration Network (OIN)

Identity 101:

I Found My Coordinates: Code, Community, and Okta

Thu, 20 Aug 2026 00:00:00 -0500

It all started with a phone call from an institute that reached out to recruit me for its campus ambassador program. I was navigating my first year of college, figuring things out. It was all new for me, a new city, far from home, and a hostel room. I was not aware of anything except books and lectures.

A senior at my campus ambassador program advised me to create a LinkedIn account and start looking for opportunities from day one. As they say, “You don’t have to be great to start, but you have to start to be great.” So I started applying for random internships. Soon, I received my first offer, where I discovered the power of networking and community.

“No one can whistle a symphony. It takes a whole orchestra to play it.” – H.E. Luccock

Community has always been the best part of my life. The love and support we receive from each other are invaluable. I have always given to the community and gained far more in return.

I attended an institution that wasn’t particularly well-known. There weren’t many communities, so why not do something about it? Through professional platforms, I discovered Google Developer Student Clubs (GDSC), researched the opportunity, and applied. I became the pioneer GDSC Lead at my institution, and one of 280 leads across India.

We built the community from scratch, organizing meetups, workshops, and hackathons that delivered real value to students. These experiences sparked curiosity and helped students find their voice. When I stumbled across the Developer Advocate role, I was very happy and curious, so I started digging into it.

My journey into advocacy

“What you seek is seeking you.” - Rumi

One day, I got an email from a founder who said he liked my LinkedIn profile and wanted me to join his organization as a Developer Advocate – that moment was surreal. That’s how I landed an internship as a Developer Advocate at Zuplo, where I learned something crucial: to understand developers’ pain points, I needed to walk in their shoes. To truly advocate for developers, I needed to be a developer myself.

Wanting to experience the world of technology from the inside led me to join JPMorgan as a Software Development Engineer, where I got to experience their work firsthand, hear about their challenges, and understand their breakthroughs and victories.

Each project and colleague shaped my perspective. By the end, I didn’t just understand developers, I was one of them.

Building impact and recognition

Over the past few years, I delivered various sessions at leading Indian colleges, mentored over 10,000 students, and built a community of more than 600,000 tech enthusiasts. Every session sparked curiosity, every mentorship helped shape someone’s path.

I collaborated with brands I admired, while enterprises, founders, and the Government of India recognized my work with a National Award. Magazines, articles, and podcasts also featured my efforts. At that moment, I knew this was my calling to make my professional life an extension of what I love doing.

I remember one time I went to a college for a session where I was the only woman on a panel speaking to nearly 3,000 students. Afterwards, several women approached me, nervous, excited, and full of questions. One said, “Seeing you on that stage inspired us. If you can do it, we can too.”

That moment stayed with me. I understand that this is the work that matters. These conversations remind me why I do this work every single day; it’s worth it.

The next chapter at Okta

When I saw that Okta – an organization I genuinely admired – was hiring, I applied immediately. I’m eternally grateful that I did.

There is something surreal about writing this: I am joining Okta as a Senior Builder Advocate. I am writing this sentence, and my brain is doing a thing where it’s not sure if this is real life.

Yes, Builder Advocate, because in today’s AI era, we don’t need to be traditional developers to create products and bring ideas to life. With the right tools and platforms, anyone can build and advocate not just for developers, but for builders of all kinds. Builders today aren’t just coders.

They’re AI builders, vibecoders, LLMs/agents, no-code and low-code builders, and developers, all creating real value. Okta is here for all of us.

This is the kind of role I once admired from the outside and thought, “This is where all my pieces fit.” I’m grateful to be here.

I’m excited for the journey ahead. Okta’s mission to secure every interaction deeply resonates with me. I’m committed to bringing my passion for community and advocacy to this role, listening to builders, understanding their challenges, and helping them succeed.

Let’s connect. Whether you are a developer, a builder, or curious about identity and access management, I’d love to build together. That’s what Okta is about. That’s what I’m here to do. Come talk to me on X, LinkedIn, or GitHub.

Here’s to new beginnings and the incredible community we’re building together at Okta.

Cheers!

Build a Flask App with Okta for Secure OIDC Login and Authorized API Calls

Tue, 28 Jul 2026 00:00:00 -0500

Python syntax and the flexibility of the Flask microframework make it a popular choice for quickly building web applications. While Flask provides the essentials to get you started, you’ll need to tackle two critical pieces yourself: secure user authentication and authorization for your backend services. After all, how do you securely sign users into your application? And once they’re signed in, how does your app fetch data from a backend service that only serves authorized requests?

This tutorial shows you how to solve both. You’ll build a Flask dashboard app that signs users in with Okta using OpenID Connect (OIDC). Once signed in, the app uses the resulting OAuth 2.0 access token to call a separate backend API that responds only to authorized requests. In this common pattern, a web app needs to fetch data from a protected backend service. You’ll use Authlib, an OIDC client library, to configure the Authorization Code flow with Proof Key for Code Exchange (PKCE) automatically. You’ll also learn how to add a custom scope to the access token and validate it on the backend to control what data the API returns.

Check out the complete source code on GitHub and get started without setting it up from scratch.

Table of Contents

Build a Flask app with OIDC authentication
Create an app integration in the Okta Admin Console
Enable self-service user registration
Add secure user login to a Flask application with Okta
Call a protected API with OAuth scoped tokens
Learn more about OAuth and OIDC

Build a Flask app with OIDC authentication

In this tutorial, you’ll build a simple dashboard application and learn how to:

Securely sign users in to view their profile information using Okta as the OpenID Connect identity provider
Use Authlib to configure the Authorization Code flow with PKCE automatically, following OAuth 2.1 security best practices
Add a feature for new users to self-register for an account directly from the sign-in page
Enable authenticated users to interact with a protected API using access tokens

Prerequisites

Python 3.14 or later and pip installed
An Okta Integrator Free Plan

Create an app integration in the Okta Admin Console

Go to Applications and Resources > Applications
Click Create App Integration
In the Sign in Method section, select OIDC - OpenID Connect
Select Web Application as the application type, then click Next
Enter an app integration name
Configure the redirect URIs:
- Sign-in redirect URIs: http://localhost:5000/authorization-code/callback
- Sign-out redirect URIs: http://localhost:5000
In the Assignments section, assign a group or keep the default Everyone group assigned for all
Click Save

Where are my new app's credentials?

Creating an OIDC Web App manually in the Admin Console configures your Okta Org with the application settings.

After creating the app, you can find the configuration details on the app’s General tab:

Client ID: Found in the Client Credentials section
Client Secret: Click Show in the Client Credentials section to reveal
Issuer: Found in the Issuer URI field for the authorization server that appears by selecting Security > API from the navigation pane.

You’ll need these values for your application configuration:

OKTA_OAUTH2_ISSUER="https://dev-133337.okta.com/oauth2/default"
OKTA_OAUTH2_CLIENT_ID="0oab8eb55Kb9jdMIr5d6"
OKTA_OAUTH2_CLIENT_SECRET="NEVER-SHOW-SECRETS"

Your Okta domain is the first part of your issuer, before /oauth2/default.

NOTE: You can also use the Okta CLI Client or Okta PowerShell Module to automate this process. See this guide for more information about setting up your app.

Enable self-service user registration

User registration is vital for any application, and Okta makes the process quick and hassle-free. See Self-Service Registration for an overview of how it works. Setting this up involves two main steps:

Create a user profile policy – This policy defines the attributes a user must provide when self-registering. See the Okta documentation for detailed instructions.
Assign your application to the policy – This step is required; without it, the self-service registration flow doesn’t activate for your app. See the product documentation for more details.

Now that you’ve configured your app integration in Okta and noted the required Okta application details, it’s time to create your Flask application.

Create a basic Flask web application

First, you’ll create a project folder and a Python virtual environment, then install the necessary dependencies.

Create a project folder named flask-web-app and a subfolder called venv.
Open a terminal window in the project folder and create a Python virtual environment
```
python -m venv venv
```
Activate the virtual environment. Use the command that corresponds to your operating system.
```
# On macOS/Linux
source venv/bin/activate

# On Windows
venv\Scripts\activate.bat
```

With your environment active, install the required libraries:

pip install Authlib==1.6.1 Flask[async]==3.1.1 python-dotenv==1.1.1 requests==2.32.4 okta-jwt-verifier==0.3.0

Configure Flask environment variables

To keep sensitive credentials out of source control, you’ll store them in a .env file and load them into the application’s configuration. This practice prevents hard-coding secrets directly into your source code. Make sure to add .env to your .gitignore file to prevent accidentally committing your credentials to source control.

Create a file named .env in the project root and add your Okta application’s configuration details. Replace the placeholders with your actual values.
```
OKTA_CLIENT_ID={yourClientId}
OKTA_CLIENT_SECRET={yourClientSecret}
OKTA_BASE_URL=https://{yourOktaDomain}
```

Create a config.py file in the project root. This file reads the values from .env and constructs the OIDC metadata URL, which the application uses to fetch endpoints from Okta.

import os

OKTA_CLIENT_ID = os.getenv('OKTA_CLIENT_ID')
OKTA_CLIENT_SECRET = os.getenv('OKTA_CLIENT_SECRET')
OKTA_BASE_URL = os.getenv("OKTA_BASE_URL")
OKTA_METADATA_URL = f"{OKTA_BASE_URL}/.well-known/openid-configuration"

Implement the OIDC authentication logic

Next, create the main application file, app.py, in your project’s root directory. This file holds the core logic for handling OIDC authentication. Paste the following code into it to configure the basic application.

from flask import Flask, render_template, url_for, redirect, session
from authlib.integrations.flask_client import OAuth
from dotenv import load_dotenv
import os
import requests

load_dotenv()

app = Flask(__name__)
app.secret_key = os.urandom(24)

app.config.from_object('config')

@app.route("/")
def index():
    return render_template('index.html')

if __name__ == "__main__":
    app.run(debug=True)

Initialize the Okta OIDC client

To set up the connection to Okta, add the following code to the bottom of your app.py file. This code initializes an OAuth object and registers the Okta application as a remote provider.

# Create a registry with an OAuth object
oauth = OAuth(app)

# Register a remote application
oauth.register(
    name='okta',
    client_id=app.config['OKTA_CLIENT_ID'],
    client_secret=app.config['OKTA_CLIENT_SECRET'],
    server_metadata_url=app.config['OKTA_METADATA_URL'],
    client_kwargs={
        'scope': 'openid profile email offline_access',
        'code_challenge_method': 'S256'
    }
)

The first parameter in the register() method (in this case, Okta) is the name of the remote application. You’ll later access the remote application with oauth.okta to handle all the OIDC-related functions.

The client_kwargs dictionary passes extra parameters to the authorization request. Because the code_challenge_method is present, the Authlib library automatically uses the PKCE flow, which enhances security.

Build Flask routes for OIDC authentication

The sign-in process begins when the user clicks the Login button, which redirects the browser to the Okta-hosted Sign-In page.

After the user signs in, Okta redirects the browser to the configured sign-in redirect URI with an authorization code. Authlib then exchanges that code for tokens and automatically calls Okta’s userinfo endpoint to retrieve the user’s profile. Similarly, after a user signs out, Okta redirects the browser to the sign-out redirect URI.

Let’s start by creating a simple HTML page that allows the user to log in. This page displays a sign-in button for signed-out users and a sign-out button for logged-in users, along with profile information.

Add the /login route to your app.py file. This endpoint serves as the entry point for the authentication flow. It constructs the authorization redirect URI and sends the user’s browser to the Okta-hosted Sign-In page to begin the OIDC process.
```
@app.route('/login')
def login():
    redirect_uri = url_for('authorization_code_callback', _external=True)
    return oauth.okta.authorize_redirect(redirect_uri)
```
Next, implement the callback handler for the Redirect URI you configured in your Okta application (http://localhost:5000/authorization-code/callback). This handler processes the authorization code returned by Okta. Calling authorize_access_token() triggers Authlib to exchange the code for tokens and automatically call Okta’s userinfo endpoint. The callback then stores both the userinfo and the full token in Flask’s session for use across requests.
```
@app.route('/authorization-code/callback')
def authorization_code_callback():
    token = oauth.okta.authorize_access_token()
    session['loggedInUser'] = token['userinfo']
    session['token'] = token

    return redirect('/')
```

Add the /logout route. This endpoint clears the local user session, signing the user out of the Flask application. It then constructs a redirect URL to Okta’s logout_endpoint, which terminates the user’s session with Okta, ensuring a complete and secure sign-out.

@app.route('/logout')
def logout():
    token = session.get('token')

    id_token_hint = None
    if token:
        id_token_hint = token.get('id_token')

    conf = oauth.okta.server_metadata
    logout_endpoint = conf.get('end_session_endpoint')

    session.pop('loggedInUser', None)
    session.pop('token', None)

    if logout_endpoint:
        logout_url = (
            f'{logout_endpoint}?'
            f'id_token_hint={id_token_hint}&'
            f'post_logout_redirect_uri={url_for("index", _external=True)}'
        )
        return redirect(logout_url)

    return redirect('/')

Finally, update the root route (/). This route now checks the session for a signed-in user and passes that information to the template.

@app.route("/")
def index():
    loggedInUser = session.get('loggedInUser')
    return render_template('index.html', user=loggedInUser)

With the back-end routes in place, you can now create the HTML template files to provide a user interface for signing in, signing out, and displaying profile data.

Step 1: Create a templates directory in your project root. Inside it, create an index.html file. This page displays a Login button for signed-out users and, for signed-in users, profile information with a Logout button.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Home</title>
    <link rel="stylesheet" href="{{ url_for('static', filename='css/index.css') }}" />
  </head>
  <body>
    <div class="wrapper">
      <nav class="main-nav" role="navigation" aria-label="Primary navigation">
        <div class="nav-left">
          <a href="/">Flask Web App</a>
        </div>
        <div class="nav-right">
          {% if user %}
          <a href="/fetch-users">Fetch Users</a>
          <a href="/logout">Logout</a>
          {% else %}
          <a href="/login">Login</a>
          {% endif %}
        </div>
      </nav>

      <main class="container">
        {% if user %}
        <section aria-label="User welcome" class="user-info">
          <h1>Welcome, {{ user.name or user.preferred_username or 'User' }}!</h1>
          <p>You have successfully logged in. You can now fetch and view user details.</p>
          <p>Click the button below to load the list of users.</p>
          <button onclick="location.href='/fetch-users'">Fetch Users</button>
        </section>

        {% else %}
        <section aria-label="Login prompt" class="user-info">
          <h1>Welcome to the Flask Web App</h1>
          <p>If you are seeing this, you are not logged in yet.</p>
          <p>This app uses OpenID Connect (OIDC) for secure login. After logging in, you can access user-specific data.</p>
          <p>Click the login button below to get started.</p>
          <a href="/login" class="button-link">Login / Register</a>
        </section>
        {% endif %}
      </main>
    </div>
  </body>
</html>

Step 2: For styling, create a static/css directory in your project root. Inside it, create index.css and add the following code.

body,
html {
  height: 100%;
  margin: 0;
  padding: 0;
  font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
  line-height: 1.5;
  overflow-y: hidden;
}

nav.main-nav {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  background-color: #2f2f2f;
  color: #f0f0f0;
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem 2rem;
  z-index: 1000;
}

nav.main-nav a {
  color: #f0f0f0;
  text-decoration: none;
  margin-left: 1.5rem;
  font-weight: 600;
}

nav.main-nav a:hover {
  color: #bfbfbf;
  text-decoration: underline;
}

.wrapper {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
  max-width: 1000px;
  margin: 0 auto;
  padding: 5rem 2rem 0;
}

main.container {
  flex: 1 1 auto;
  padding: 2rem 0;
  display: flex;
  flex-direction: column;
}

section.user-info {
  background: transparent;
  padding: 1.5rem 0;
  margin-bottom: 2rem;
  color: #222222;
}

button,
a.button-link {
  background-color: #1a73e8;
  color: #fff;
  border: none;
  padding: 0.6rem 1.3rem;
  border-radius: 5px;
  cursor: pointer;
  font-size: 1rem;
  text-decoration: none;
  display: inline-block;
  margin-top: 1rem;
  font-weight: 600;
}

button:hover,
a.button-link:hover {
  background-color: #155ab6;
  color: #fff;
}

Run the Flask OAuth web app

You’re ready to test the sign-in and sign-out functionality.

Start the application with the Flask server.

flask run

Open a new terminal window and start the resource server.

flask --app resource-server.py run --port 5001

Open a browser and go to http://localhost:5000.
Click Login. The browser redirects you to the Okta Sign-In Widget.
After you sign in, Okta redirects you back to your application, and the page displays the signed-in user’s details.

Click Logout. The browser clears your session and returns you to the home page.

You’ve successfully added a secure authentication flow to your Flask app. Next, you’ll extend it to call a protected API using scoped tokens.

Call a protected API with OAuth scoped tokens

Using OAuth for API authorization is a modern security best practice. It allows you to use access tokens to interact with APIs to fetch and manage data securely. This section walks you through how to use a scoped access token to fetch data from your own resource server.

Every action on an endpoint that supports OAuth 2.0 requires a specific scope. In this example, your endpoint requires the specific scope api:read-users to return a list of sample users.

To include this scope in the tokens minted from Okta, follow these steps:

In your Okta Admin Console, navigate to Security > API
Select your Authorization Server and go to the Scopes tab
Click the Add Scope button and enter api:read-users in the Name field
Optionally, enter the Description and the Display Phrase
Click Create

Now, when your app requests this scope, Okta includes it in the tokens it issues.

Before creating the resource server, add an extra layer of security. You want your endpoint only to consume tokens intended for your server, preventing attackers from replaying or misusing tokens issued for other services.

To do this, restrict the aud claim that Okta returns in the access token to your resource server. To achieve this:

In your Okta Admin Console, navigate to Security > API
Select your Authorization Server. In the Settings tab, click Edit.
Change the Audience field to http://localhost:5001 – this is where your resource server runs

Build a protected users API

For this demo app, you’ll create a minimal resource server with a single route called fetch-users that returns a list of sample users.

Start by modifying the .env file. Add the variable that stores the domain of your resource server (in this case, http://localhost:5001):

OKTA_CLIENT_ID={yourClientId}
OKTA_CLIENT_SECRET={yourClientSecret}
OKTA_BASE_URL=https://{yourOktaDomain}
RESOURCE_SERVER_BASE_URL=http://localhost:5001

Now, modify the config.py file to include the resource server URL and the list of sample users. Replace the existing code with the following:

import os

OKTA_CLIENT_ID = os.getenv('OKTA_CLIENT_ID')
OKTA_CLIENT_SECRET = os.getenv('OKTA_CLIENT_SECRET')
OKTA_BASE_URL = os.getenv("OKTA_BASE_URL")
OKTA_METADATA_URL = f"{OKTA_BASE_URL}/.well-known/openid-configuration"
RESOURCE_SERVER_BASE_URL = os.getenv("RESOURCE_SERVER_BASE_URL")

SAMPLE_USERS = [
    {
        "id": 1,
        "name": "Alice Johnson",
        "firstName": "Alice",
        "lastName": "Johnson",
        "email": "alice.johnson@example.com"
    },
    {
        "id": 2,
        "name": "Bob Smith",
        "firstName": "Bob",
        "lastName": "Smith",
        "email": "bob.smith@example.com"
    },
    {
        "id": 3,
        "name": "Nina Patel",
        "firstName": "Nina",
        "lastName": "Patel",
        "email": "nina.patel@example.com"
    }
]

Create a resource-server.py file in the project directory and add the following code:

from flask import Flask, request, jsonify
from okta_jwt_verifier import BaseJWTVerifier

app = Flask(__name__)

app.config.from_object('config')

ISSUER = app.config['OKTA_BASE_URL']
CLIENT_ID = app.config['OKTA_CLIENT_ID']
AUDIENCE = app.config['RESOURCE_SERVER_BASE_URL']
REQUIRED_SCOPES = {"api:read-users"}

async def verify_token():
    pass

@app.get('/fetch-users')
async def get_users():
    is_valid, error_response = await verify_token()

    if not is_valid:
        return error_response

    return jsonify(app.config['SAMPLE_USERS'])


if __name__ == "__main__":
    app.run(port=5001)

The endpoint returns sample users if the token is valid. Next, you’ll add token validation.

Now write the logic for token validation. You’ll validate the token’s issuer, audience, and client ID against your authorization server URL, resource server domain, and client ID. You’ll also verify that the api:read-users scope is present in the token’s scp claim.

Start with the verify_token function. First, check if the Authorization header is of type Bearer:

auth_header = request.headers.get("Authorization")

if not auth_header:
    return None, (jsonify({"error": "No token provided"}), 401)

parts = auth_header.split()
if parts[0].lower() != "bearer" or len(parts) != 2:
    return None, (jsonify({"error": "Authorization header must be Bearer token"}), 401)

Next, use Okta’s package to verify that the audience, issuer, and client ID in the token match your configuration:

token = parts[1]

try:
    jwt_verifier = BaseJWTVerifier(issuer=ISSUER, client_id=CLIENT_ID, audience=AUDIENCE)
    await jwt_verifier.verify_access_token(token)

    return True, None
except Exception as e:
    print(f"Token verification failed: {e}")
    return None, (jsonify({"error": "Invalid or Expired Token"}), 401)

Now add scope validation. Extract the claims from the token and check that the custom scope api:read-users is present in the scp claim. If the token doesn’t contain this scope, reject it and return an error. In the try block, before the return statement, add the following code:

_, claims, _, _ = jwt_verifier.parse_token(token)
token_scopes = set(claims.get("scp", []))
if not REQUIRED_SCOPES.issubset(token_scopes):
    return False, (jsonify({"error": "Insufficient Scope"}), 403)

print("Token is Valid!")

Once everything is done, your verify_token function looks like this:

async def verify_token():
    auth_header = request.headers.get("Authorization")

    if not auth_header:
        return None, (jsonify({"error": "No token provided"}), 401)

    parts = auth_header.split()
    if parts[0].lower() != "bearer" or len(parts) != 2:
        return None, (jsonify({"error": "Authorization header must be Bearer token"}), 401)

    token = parts[1]

    try:
        jwt_verifier = BaseJWTVerifier(issuer=ISSUER, client_id=CLIENT_ID, audience=AUDIENCE)
        await jwt_verifier.verify_access_token(token)

        _, claims, _, _ = jwt_verifier.parse_token(token)
        token_scopes = set(claims.get("scp", []))
        if not REQUIRED_SCOPES.issubset(token_scopes):
            return False, (jsonify({"error": "Insufficient Scope"}), 403)

        print("Token is Valid!")
        return True, None

    except Exception as e:
        print(f"Token verification failed: {e}")
        return False, (jsonify({"error": "Invalid or Expired Token"}), 401)

Extend the Flask app to interact with the resource server

With the Okta configuration complete, the next step is to update your Flask application to request this scope. This ensures that the access token issued to the user includes the necessary permission to call the protected endpoint.

In your app.py file, find the oauth.register block and add api:read-users to the scope string within the client_kwargs dictionary.

 oauth.register(
     # ... other parameters
     client_kwargs={
         'scope': 'openid profile email offline_access api:read-users',
         'code_challenge_method': 'S256'
     }
 )

Add a new route, /fetch-users, to your app.py file. This endpoint uses the stored access token from the user’s session to make a secure GET request to the protected endpoint in the resource server. If successful, it passes the returned list of users to the index.html template for display.

@app.route('/fetch-users')
def fetchUsers():
    token = session.get('token')
    loggedInUser= session.get('loggedInUser')

    if not (token or loggedInUser):
        return redirect(url_for('login'))

    access_token = token.get('access_token')
       
    RESOURCE_SERVER_BASE_URL = app.config['RESOURCE_SERVER_BASE_URL']

    headers = {"Authorization": f"Bearer {access_token}"}
    resp = requests.get(f"{RESOURCE_SERVER_BASE_URL}/fetch-users", headers=headers)

    if resp.ok:
        data = resp.json()
        return render_template('index.html', user=loggedInUser, userList=data)

    else:
        return f"API request failed: {resp.status_code} {resp.text}", resp.status_code

Update the root route (/) to initialize the userList variable in the template. This prevents errors when the page first loads before any data is fetched. Replace the existing index function with the following code.
```
 @app.route("/")
 def index():
     loggedInUser = session.get('loggedInUser')
     return render_template('index.html', user=loggedInUser, userList=None)
```

Update the Flask UI to display protected data

Now, let’s modify the front end to add a button that triggers the API call and a table to display the returned user data.

Step 1: Open the templates/index.html file and replace its entire contents with the updated code below. This version adds a Fetch Users button for signed-in users and a table to display the user list when available.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Home</title>
    <link rel="stylesheet" href="{{ url_for('static', filename='css/index.css') }}" />
  </head>
  <body>
    <div class="wrapper">
      <nav class="main-nav" role="navigation" aria-label="Primary navigation">
        <div class="nav-left">
          <a href="/">Flask Web App</a>
        </div>
        <div class="nav-right">
          {% if user %}
          <a href="/fetch-users">Fetch Users</a>
          <a href="/logout">Logout</a>
          {% else %}
          <a href="/login">Login</a>
          {% endif %}
        </div>
      </nav>

      <main class="container">
        {% if user %}
        <section aria-label="User welcome" class="user-info">
          <h1>Welcome, {{ user.name or 'User' }}!</h1>
          <p>You have successfully logged in. You can now fetch and view user details.</p>
          <p>Click the button below to load the list of users.</p>
          <button onclick="location.href='/fetch-users'">Fetch Users</button>
        </section>

        {% if userList %}
        <section aria-label="Users table">
          <h2>Users List</h2>
          <div class="table-wrapper">
            <table>
              <thead>
                <tr>
                  <th>Email</th>
                  <th>First Name</th>
                  <th>Last Name</th>
                </tr>
              </thead>
            </table>
            <div class="table-body-scroll">
              <table>
                <tbody>
                  {% for user in userList %}
                  <tr>
                    <td>{{ user.email }}</td>
                    <td>{{ user.firstName }}</td>
                    <td>{{ user.lastName }}</td>
                  </tr>
                  {% endfor %}
                </tbody>
              </table>
            </div>
          </div>
        </section>
        {% endif %} {% else %}
        <section aria-label="Login prompt" class="user-info">
          <h1>Welcome to the Flask Web App</h1>
          <p>If you are seeing this, you are not logged in yet.</p>
          <p>This app uses OpenID Connect (OIDC) for secure login. After logging in, you can access user-specific data.</p>
          <p>Click the login button below to get started.</p>
          <a href="/login" class="button-link">Login / Register</a>
        </section>
        {% endif %}
      </main>
    </div>
  </body>
</html>

Step 2: To style the new user table, open static/css/index.css file and add the following CSS at the end of the file.

.table-body-scroll {
    max-height: 300px;
    overflow-y: auto;
    border-radius: 8px;
    border: 1px solid #d1d9e6;
    box-shadow: 0 0 6px rgba(0, 0, 0, 0.05);
  }
 
  table {
    border-collapse: collapse;
    width: 100%;
    background-color: #fff;
    color: #2c3e50;
    border-radius: 8px 8px 0 0;
    table-layout: fixed;
  }
 
  thead th {
    text-align: center;
    background-color: #e9f0fb;
    color: #1a3c72;
    font-weight: 700;
    padding: 0.75rem 1rem;
    border-bottom: 1px solid #d1d9e6;
    position: sticky;
    top: 0;
    z-index: 1;
  }
 
  td {
    text-align: center;
    padding: 0.75rem 1rem;
    border-bottom: 1px solid #e2e8f0;
    font-size: 1rem;
    word-wrap: break-word;
  }

Test the protected API integration

Ready to see it all work? Make sure both servers are running: the Flask app (flask run) and the resource server (flask --app resource-server.py run --port 5001). Open a browser, go to http://localhost:5000, sign in, and then click Fetch Users. A table appears, listing sample users returned from your resource server. If you see the user data, your integration is a success!

Your Flask application now has secure user authentication and can use an access token to interact with a protected API.

Learn more about OAuth and OIDC

If you’d like to learn more about the concepts covered in this tutorial, explore these official Okta resources:

Enable Your SAML Requesting App for Cross App Access

Fri, 17 Jul 2026 00:00:00 -0500

If you currently federate enterprise customers using Security Assertion Markup Language (SAML) and want to connect with third-party applications without migrating to OpenID Connect (OIDC), this Cross App Access (XAA) guide is for you.

The Identity Assertion Authorization Grant specification, the basis of XAA, was originally designed with OIDC in mind. To use it in SAML applications, you must accommodate specific security and uniqueness requirements. This guide details what you need to support and how to make resource requests to a third-party app using XAA.

Table of Contents

How XAA in SAML works
XAA implementation checklist for SAML-federated applications
Making cross-application requests from your SAML app securely
Configure your XAA SAML Requesting App in Okta
Learn more about Cross App Access, SAML, and OAuth 2.0

How XAA in SAML works

When an agent (like one running in Claude) needs API access, it presents an Identity Assertion Authorization Grant (ID-JAG). The ID-JAG is a short-lived JSON Web Token (JWT) issued by the Identity Provider (IdP) for your app’s user. You exchange the ID-JAG token for an access token to the resource application you’re connecting with.

The sequence diagram shown below describes the SAML XAA flow and how your application fits in. You’ll handle the flow in two parts: where your application requests the ID-JAG from the IdP using a refresh token, and where your app requests the access token from the ID-JAG from the third-party resource app’s authorization server.

XAA implementation checklist for SAML-federated applications

Follow the guide in this section to support XAA in your SAML application when your app connects to a third-party resource application. The XAA flow places the burden of token validation onto the IdP and the resource app’s authorization server. The initial SSO step remains the same; however, you’ll add three requests before getting an access token to make the resource API call.

Once the user completes signing in, you’ll:

Request an OAuth refresh token from Okta
Request the ID-JAG token from Okta
Request the OAuth access token from the third-party resource app’s OAuth authorization server

Request the refresh token

Your SAML application makes the initial SSO handshake and handles the SAMLResponse as usual. The ACS handler verifies the incoming payload and its digital signature, then extracts the underlying XML assertion. This assertion serves as the required credential for the subsequent exchange.

Immediately after validating the SAML response, in the same ACS request before redirecting the user onward, you’ll perform the first exchange. Base64-encode the assertion you extracted, then exchange it for a refresh token using Okta’s token endpoint. This exchange follows the OAuth 2.0 Token Exchange (RFC 8693) mechanism.

This step requires a credential in the request. Because you’re making a sensitive resource request, Okta requires a JWT signed with an asymmetric key pair as the credential – a private key JWT.

Follow the instructions in the Build a JWT for Client Authentication for your tech stack. The signed JWT becomes a client assertion in the request.

The refresh token HTTP request looks like this:

POST /oauth2/v1/token HTTP/1.1
Host: your-okta-domain.okta.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=<base64url-encoded SAML assertion XML>&
subject_token_type=urn:ietf:params:oauth:token-type:saml2&
requested_token_type=urn:ietf:params:oauth:token-type:refresh_token&
scope=openid+offline_access&
client_id=<your_client_id>&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=<your signed JWT>

The IdP (Okta) responds with the refresh token. The refresh token is opaque and long-lived. Persist the refresh token for the session; never persist or use the SAML assertion past this exchange.

Request the ID-JAG token

With the refresh token in hand, you have the credentials to request the ID-JAG token when your application needs resources from a third-party app. This exchange uses the same OAuth token exchange mechanism as the first step. You make the POST request to the same endpoint, Okta IdP, using the refresh token, and request the ID-JAG token type.

This request also requires a signed JWT as it’s requesting a sensitive resource.

The HTTP request looks like this:

POST /oauth2/v1/token HTTP/1.1
Host: your-okta-domain.okta.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=<the refresh_token from prior step>&
subject_token_type=urn:ietf:params:oauth:token-type:refresh_token&
requested_token_type=urn:ietf:params:oauth:token-type:id-jag&
audience=<the resource app's authorization server issuer URI>&
resource=<the resource app's API base URL>&
scope=<the resource app's required scopes>&
client_id=<your_client_id>&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=<your signed JWT>

The IdP responds with a short-lived, signed JSON Web Token (JWT), the ID-JAG, as the value in the access_token property within the payload.

Request the access token

POST /token HTTP/1.1
Host: the-resource-server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(resource_as_client_id:resource_as_client_secret)>

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=<ID-JAG token>&
scope=todos.read

In the example HTTP request, the Authorization header uses the Basic scheme as a demo. Use the authorization scheme required by the resource application.

The response payload contains the access_token property, whose value is the access token. Use the access token to make the API resource request by using the value in the Authorization header. For example:

Authorization: Bearer <access_token>

Handle token expiration

ID-JAG tokens have a short timeline by design. When it expires, request a shiny new ID-JAG from the refresh token. Refresh tokens also have a lifespan. If the IdP rejects the refresh token due to expiration (you’ll see an invalid_grant error), then you need to obtain a new refresh token by having the user sign in via SSO again.

Making cross-application requests from your SAML app securely

With these steps complete, your SAML application is configured for Cross App Access. Agents can now authorize requests against your API while maintaining your existing production federation, eliminating the need for protocol migration.

You can now use Okta to make cross-application requests with your SAML app.

Configure your XAA SAML Requesting App in Okta

Let’s configure your SAML requester application in Okta. Before you begin, you’ll need:

Values from your app (we’ll walk through the values needed below)
An Okta Integrator Free Plan account. Sign up for a new account to test out the XAA feature
xaa.dev for testing your requesting app

Cross App Access is an early access feature in Okta. New Integrator Free Plan account types include XAA support. If you have a paid Okta org plan and the following options are missing, contact your representative.

Create a custom SAML app integration representing your requesting app, using these values:

In General Settings:

App name: “Requesting App”

In Configure SAML:

Single sign-on URL: the ACS URL of your requester app, e.g., “https://requester-app-uri/saml/acs”
Audience URI (SP Entity ID): the SP Entity of your requester, e.g., “https://requester-app-uri/saml/metadata”
Name ID format: select EmailAddress
Application username: select Email
Update application username on: select Create and update

After creating the app, you’ll see more configuration options for your Okta SAML 2.0 requesting app. You’ll make changes in more than one tab.

Sign On configuration

On the Sign On tab, retrieve your SAML setup details: under View SAML setup instructions, copy the Identity Provider Single Sign-On URL and Identity Provider Issuer, and download the X.509 certificate as idp-cert.pem. You’ll need all three in your requesting app setup.

Assignments configuration

Assign your test user to the app on the Assignments tab.

Now that we have the requesting app registered, it’s time to create a custom SAML app integration representing the resource app, using these values:

In General Settings:

App name: “Resource App for Testing”

In Configure SAML:

Single sign-on URL: “https://idp.xaa.dev/saml-resource/acs”
Audience URI (SP Entity ID): “https://idp.xaa.dev/saml-resource/metadata”
Name ID format: select EmailAddress
Application username: select Email
Update application username on: select Create and update

⚠️ Note

Please note that we’re providing these for setup; they don’t constitute a working SSO connection to the resource app. Also, don’t assume the NameID is an email address; it is whatever the customer’s SSO emits. Your matching set must remain consistent across your deployment.

After creating the app, you’ll see more configuration options for your Okta SAML 2.0 app. You’ll make changes in the resource server tab.

Resource Server extra configuration

Enable Cross App Access (XAA) on the resource app integration from the Resource Server tab, and configure:

Issuer URL: https://auth.resource.xaa.dev

Assignments configuration

Assign your test user to the app on the Assignments tab.

The next step is to set up xaa.dev for the resource app.

Go to Test your requesting app and use these values:

IdP issuer URL: your Okta Integrator account ID (i.e., https://your-okta-domain.okta.com)
Test user identifier: your email, e.g., name1234…@okta.com
SAML IdP entityID: from the requesting app’s Sign On tab > SAML Setup > View SAML setup instructions, the Identity Provider Issuer value (i.e., http://www.okta.com/)

After all values are entered, click Register.

Register and configure the AI Agent in Okta

With your Okta SAML 2.0 requesting app and the resource app configured, register a new AI Agent in Okta. The AI Agent configuration defines the relationship between the Okta SAML 2.0 requesting app you created and the resource application, which in this case is xaa.dev. You configure credentials, link your requesting app during registration, and connect the resource app as a Resource Connection.

In the Okta Admin Console, register the AI Agent and link your requesting app:

Navigate to Directory > AI Agents
Select Register AI Agent > Register Manually
Under Profile, enter a Name, e.g., “Agent”, and an optional description, then press Next
Under User access and authentication > Allow users to access this agent, select Select an existing app, then choose the Okta SAML requesting app you created earlier (e.g., “Requesting App”). This app acts as the requesting app for the XAA flow: your users sign in to the agentic app through it, and the agent then acts on their behalf. Press Next.
Under owners: assign your test user as an individual owner

Select the AI Agent you just created to open its configuration. Configure the agent across the following tabs:

On the Client registration tab, choose a client registration method:
1. Select the Public/private key section
2. In the Define where keys are managed section, choose Okta
3. Under the Add and manage keys section, select Add public key, then Generate new key. Under PEM, copy the private key into the Private key (PKCS8 PEM or private JWK) field in your requesting app
4. Copy the KEY ID and add it back to your requesting app
5. In the Provide Client ID to AI agent builder or developer step, copy the Client ID, and add it back to your requesting app
On the User access tab
1. In the App used for access configuration, select Select an existing SAML app, then your SAML Application, e.g., “Requesting App”
On the Resource connections tab, add a resource connection to the AI Agent. Use these values:
1. Application instance: your resource app (e.g., “Resource App for Testing”)
2. AI agent’s client ID registered in this app: the Client ID from xaa.dev (it should look similar to byora...)
3. Scopes: Allow any scope
Activate the AI Agent: activating the linked requesting app integration usually activates the AI Agent. If the agent’s status is STAGED, go to the Actions drop-down menu at the top and select Activate.

Once the AI Agent is active, the configuration is complete. All checkmarks on the agent configuration page must be green.

Test the SAML 2.0 app

At this stage, you are all set to run the requesting app and verify the complete XAA flow it is supposed to perform.

Validate the XAA connection end-to-end

Once the flow is complete in the SAML 2.0 application, return to xaa.dev. In the Live verification tab, a green Conformance passed panel appears. This confirms all steps:

Auth Server Accepted your ID-JAG
Access token was issued
Resource Server accepted your access token
API call to the /api/todos/ was a success.

At this stage, the JSON conformance log will have the complete details of the XAA flow.

Learn more about Cross App Access, SAML, and OAuth 2.0

If this guide helped you implement Cross App Access with SAML, explore these resources:

📘 Cross App Access Documentation: Official guides for configuring and managing Cross App Access in production
🎙️ Developer Podcast on MCP and Cross App Access: Hear the backstory, use cases, and why this matters for developers
📋 How to Build and List Secure Cross App Access (XAA) Connections on Okta Integration Network (OIN)

Identity 101:

Okta Developer

Build a Secure TypeScript MCP Client with Cross App Access (XAA)

What you’ll build: a TypeScript MCP requesting app

Register your requesting app on xaa.dev

Set up the TypeScript project

Run your TypeScript MCP app with xaa.dev

The four-step XAA flow

Inspect the tokens in the dashboard

ID-JAG: the token that carries identity across apps

Why Cross App Access matters for AI agents

The Model Context Protocol and its TypeScript SDK

Inside the MCP TS SDK’s crossAppAccess module

Walk through the XAA flow in TypeScript

Sign the user in with OpenID Connect and PKCE

Exchange the ID token for an ID-JAG

Exchange the ID-JAG for an access token

Fetch data from the MCP server

CrossAppAccessProvider runs the whole flow

Where XAA fits in your real architecture

Learn more about Cross App Access, ID-JAG, and MCP

Classic Engine Feature EOL: SSR, Desktop SSO, Device Trust

What’s changing in Okta Classic Engine

Why upgrade to Okta Identity Engine

Okta Identity Engine elevates identity capabilities

Planning your migration to Okta Identity Engine

Key timeline for Classic Engine capabilities sunsetting

Best practices after your Okta Identity Engine upgrade

Plan your migration now!

Resources to aid your Okta Identity Engine migration

Supercharge Auth with Signals and the New Okta Angular SDK

Get the starting Angular project

Secure the Angular app with OAuth 2.1 and OpenID Connect (OIDC) using Okta

Grant API scopes to read users and groups

Allow cross-origin requests and protect the access token

Add authentication with the standalone Okta Angular provider

Protect routes with functional route guards

Add users to your Okta org

Display users and review Angular’s rxResource API

Load a user’s groups with rxResource and a signal input

Display group details using signal inputs

Load your Okta configuration at runtime

Learn more about Angular signals, standalone APIs, and OIDC

Add Cross App Access to Your OIDC Resource Application

How XAA in OIDC works

Analyzing the ID-JAG claims

XAA implementation checklist for OIDC-federated applications

Mapping user identity from iss and sub

Validating the ID-JAG and resolving the user

Issuing the access token

Updating authorization server metadata

Making cross-application requests from your OIDC app securely

Configure your XAA OIDC Resource app in Okta

Create the OIDC requesting app for testing

Create the OIDC resource app in Okta

Register and configure the AI Agent in Okta

Verify your Okta XAA setup on xaa.dev

Configure OIDC SSO

Verify the refresh token exchange for an ID-JAG token

Redeem the ID-JAG for an access token at the resource authorization server

Call the resource API with the access token

Prove the XAA connection end-to-end

Takeaways for implementors who also have SAML apps

Learn more about Cross App Access, OIDC, and OAuth 2.0

Add Cross App Access to Your OIDC Requesting Application

How XAA in OIDC works

XAA implementation checklist for OIDC-federated applications

Request the ID-JAG token

Request the access token

Call the resource API

Handle token expiration

Making cross-application requests from your OIDC app securely

Configure your XAA OIDC requesting app in Okta

Register the requesting app in Okta

Register the test resource app in Okta

Register your requesting app at xaa.dev

Register and configure the AI Agent in Okta

Validate the XAA connection end-to-end

Learn more about Cross App Access, OIDC, and OAuth 2.0

I Found My Coordinates: Code, Community, and Okta

My journey into advocacy

Inside the MCP TS SDK’s `crossAppAccess` module

Display users and review Angular’s `rxResource` API

Load a user’s groups with `rxResource` and a signal input

Mapping user identity from `iss` and `sub`