Okta Developer

Okta Developer Connect San Francisco 2026 Recap

Tue, 09 Jun 2026 00:00:00 -0500

“Building an agent is only half the battle. Governing it is where we get stuck.”

That question came up in nearly every conversation we had with engineering managers leading up to Okta Developer Connect San Francisco. The second edition of our flagship developer event series brought more than 100 developers, architects, founders, platform engineers, and security leaders to Okta HQ on April 30 for an afternoon of technical sessions, hands-on labs, and community conversations on one theme: securing identity in the age of AI.

Unlocking AI in the enterprise: Okta for AI Agents is GA

The opening keynote made a point most enterprise teams are now grappling with. Identity has always been a security control. With AI agents in the picture, identity also becomes the governance layer for a class of workloads that didn’t exist a year ago: non-human, autonomous, and increasingly trusted to act on behalf of users.

The keynote also marked the general availability of Okta for AI Agents. The announcement framed the problem in terms that every security leader recognizes: once an agent ships, three questions arise almost immediately, and the product answers each.

Where are my agents? Discovery and onboarding work across frameworks, clouds, and SaaS environments, with shadow AI detection for the agents nobody officially registers.

What can they connect to? Protection rests on short-lived credentials, scoped tokens, vaulted secrets, and access controls that extend to Model Context Protocol (MCP) servers.

What can they do? Governance covers the full lifecycle: access requests, certification, audit logs that stream to Security Information and Event Management (SIEM) platforms, and a kill switch that deactivates an agent that goes off-script.

For the developers and architects in the room, the announcement set the tone for the rest of the day. Every session that followed answered one of those three questions in some way. You can dig deeper on the Okta for AI Agents product page or in the documentation.

Why this conversation matters now

Across the sessions and the AI Interview activation we ran throughout the event, one theme kept coming up: agents are arriving in production faster than most teams can govern them.

Developers told us they have shifted from writing every line of code to reviewing, guiding, and orchestrating AI-generated work. Engineering teams are connecting agents to internal APIs, retrieval-augmented generation (RAG) pipelines, MCP servers, and third-party tools. Security and IAM leaders are watching it happen and asking how to apply the principles they already trust (least privilege, scoped access, auditability) to identities they didn’t anticipate when they built those controls.

A few patterns stood out from those conversations.

Agents are outpacing governance. Many teams ship an agent in days. Wrapping it in policy, access reviews, and lifecycle controls takes weeks or months. The gap between “it works” and “it’s safe to leave running” is where most of the risk lives.

Static credentials are the new shadow IT. Hardcoded keys, long-lived tokens, and shared service accounts are how a lot of agents reach data today. They make the demo work. They also make incidents harder to scope when something goes wrong.

RAG has a permissions problem. Retrieval-augmented generation is now the default pattern for enterprise AI. The hard part is making sure an agent retrieving documents on behalf of a user only sees what that user can access at the data layer, and not just the prompt.

Non-human identity is a real category. Teams that already invested in human identity governance now realize they need an equivalent practice for agents, bots, and workloads. Naming them, owning them, and decommissioning them are no longer optional.

Cross App Access and the protocol behind it

Cross App Access (XAA) drew one of the most-attended sessions of the day, and for good reason. As agents move between applications, the consent model designed for users clicking buttons doesn’t hold up. Repeated prompts get fatigue clicks. Unmanaged app-to-app connections become invisible to security teams. Long-lived tokens leak.

XAA introduces a model in which the enterprise identity provider mediates access between applications based on policy, rather than relying on per-user consent or app-to-app integrations. The session grounded the protocol in the OAuth context most developers already know, which made the new pieces (identity assertion and token exchange across app boundaries) easier to place.

For developers, the practical takeaway is clear. If you’re building an application that needs to act on behalf of a user inside another application, the question is no longer “how do I get a token?” It’s “how does my organization want to govern this access, and how does my app respect that policy?”

A hands-on walkthrough of xaa.dev gave attendees a chance to step through the Cross App Access flow on their own laptops. Watching identity assertion and token exchange move across a requesting app, an identity provider, and a resource app turned an otherwise dense protocol into something concrete. It gave the room a working mental model to take back to their own architectures.

Securing AI agents with Auth0

A dedicated session walked through the identity patterns developers can adopt today when building AI applications. The framing stayed deliberately practical, organized around the four risks that show up most often when an agent starts touching real data: authenticating the user the agent acts for so context stays in the chain; using a Token Vault so agents don’t handle long-lived third-party credentials directly; asynchronous authorization so users can approve sensitive actions out of band; and fine-grained authorization so an agent only retrieves the data and triggers the actions a user can access.

The session landed because these patterns map naturally to OAuth concepts most developers already know. The work isn’t learning a new identity model from scratch. It’s applying delegation, scoped tokens, and policy-driven authorization to a new kind of caller, one that doesn’t have a browser, doesn’t click “allow,” and doesn’t stop to think before acting. Explore the patterns and SDKs in Auth0 for AI Agents.

The panel: What teams are actually asking about AI agents

The panel pulled the conversation out of theory and into the questions teams are wrestling with right now. An opening icebreaker about what an unsecured personal AI agent might buy if it went rogue set the tone: practical, direct, and sometimes intentionally playful.

When applications already have their own access controls, does identity get the final say, or does the application remain the real gatekeeper? How do you stop MCP servers from quietly becoming a backdoor into enterprise data? Which authentication mistakes do developers most often make when they build their first agent? How do teams move from identity as an audit log they review after the fact to identity as a guardrail that enforces decisions in real time?

The panel didn’t offer easy answers, and that was the point. Securing AI agents isn’t a feature you add at the end of a build. It’s a set of decisions about delegation, consent, and least privilege you need to make early, before you connect the agent to anything that matters.

What this means for builders

A few takeaways from the day are worth carrying forward:

Treat agents as identities, not features. The moment an agent can act on data or trigger workflows, it needs the same lifecycle treatment as a user account: ownership, scope, review, and revocation. Naming it after the application isn’t enough.

Design the consent model before the integration. It’s much easier to decide who can delegate what, and how that delegation expires, before you connect an agent to a calendar, a CRM, or a document store. Once the integration goes live, every change becomes a migration.

Push authorization closer to the data. Fine-grained authorization works best at the layer where decisions actually happen: the database, the vector store, the API. Token-level scopes alone don’t stop a RAG pipeline from surfacing documents outside the user’s permissions.

Plan for the agent you haven’t built yet. Most teams plan to deploy more agents next year than they did this year. The patterns that feel optional today - discovery, governance, scoped credentials become foundational the moment you have a fleet to manage.

Community, Conversations, and the AI interview activation

Beyond the sessions, the energy in the room was the hardest part to put on a slide. Attendees stayed for the hands-on lab, joined the AI Interview activation, asked sharp questions during the panel, and kept the conversation going with Okta and Auth0 engineers, product leaders, and developer advocates well past the formal close.

The AI Interview activation in particular created a useful feedback loop. Developers told us how AI is reshaping their day, not in marketing terms, but in the specifics of how they review pull requests, find documentation, and decide when to trust an AI-generated answer. Those conversations are already shaping what we build and what we write next.

What comes next

Okta Developer Connect started as a forum for the conversations that are harder to have on a webinar, the ones where developers and architects can push back, ask the awkward question, and leave with something they can actually use. The San Francisco edition continued that mission with a sharper focus on AI agents, OAuth, Cross App Access, and the identity patterns shaping the next generation of applications.

If a single thread ran through the day, it was this: the teams that treat identity as part of the agent, not a wrapper around it, ship at the speed the business asks for, without trading away the controls that keep them safe.

Thank you to everyone who joined us in San Francisco, asked the harder questions, and shared what you’re building. We’re looking forward to the next edition.

Stay tuned for upcoming Okta Developer Connect events, and follow OktaDev on LinkedIn, X, and YouTube for new tutorials, videos, and announcements.

The One Where I Found My Way to DevRel

Fri, 05 Jun 2026 00:00:00 -0500

If you’ve watched Friends, you’ll know that life rarely goes according to plan. One day, you’re helping a friend move a couch while yelling “Pivot!”, and the next, you’re wondering how you ended up there in the first place.

My career has felt a little like that.

Growing up, I was always drawn to creative pursuits. You could usually find me with a book in hand, experimenting with calligraphy, sketching something random, writing poetry, baking a new dessert, or trying out a recipe I found somewhere online. Technology wasn’t the obvious destination (even though I love building!), storytelling was.

That love for explaining things eventually led me into technical writing.

Building docs for developers

I started working with startups, creating everything from API documentation and user guides to onboarding content and developer-facing resources. I loved the challenge of taking something complex and making it easier to understand. There was something deeply satisfying about helping someone go from “What does this even mean?” to “Oh, now I get it.”

For a while, I thought documentation was the destination. Plot twist! It wasn’t.

When I joined JDoodle (a web-based IDE), I found myself spending more time talking to developers. I wasn’t just writing for them anymore. I was listening to them, learning how they built things, understanding their frustrations, and seeing firsthand what made them excited about technology.

The more conversations I had, the more I realized something. The thing I enjoyed most wasn’t just creating documentation. It was connecting with people.

Finding my place in devrel

I started attending developer events and conferences. Then came product demos. Then booth duty. Then community conversations. Then hackathons. Then organizing internal events.

Somewhere along the way, what started as “I need to understand developers better so I can write better documentation” turned into “I genuinely love being part of developer communities.”

I discovered that my favorite moments weren’t necessarily publishing a new document or updating an API reference.

They were moments like:

Watching a developer finally solve a problem after a conversation.
Seeing people get excited during a product demo.
Helping organize hackathons where creativity and technology collide.
Meeting builders who were passionate about bringing their ideas to life.
Learning something new from every event I attended.

As it turns out, the skills that drew me to writing in the first place translated surprisingly well into developer advocacy.

At their core, documentation and developer advocacy are both about empathy. They require understanding your audience, telling clear stories, and helping people succeed.

Joining the Okta community

Looking back, it makes perfect sense. The person who loved books, writing, art, and storytelling didn’t leave those interests behind when entering tech. She simply found a new audience.

Today, I’m incredibly excited to continue that journey at Okta.

I’ll be working alongside developers, creators, builders, and community members who are shaping the future of identity and security. I’m looking forward to learning, sharing, creating content, attending events, and most importantly, connecting with the people who make this community so special.

As Phil Dunphy said, “When life gives you lemonade, make lemons. Life will be all like, ‘What?!’” My career may not have followed a traditional path, but somehow it led me exactly where I wanted to be.

I’m excited to meet all of you. If you see me at an event, or find me on socials, come say hello. I’d love to hear what you’re building.

How to Build Low-Code API Integrations for Enterprise Apps Using Okta

Tue, 12 May 2026 00:00:00 -0500

API Integration Actions are now available in Okta Integration Network (OIN) for Integrator Free Trial Orgs to build Provisioning, Entitlements, and Universal Logout applications.

What are API Integration Actions?

API Integration Actions are a feature that uses Workflows, Okta’s low-code builder, to enable independent software vendors (ISVs) to build Okta Integrations (Provisioning, Entitlements, Universal Logout) that are seamlessly invoked by Okta services — for example, retrieving and updating entitlements or triggering risk-based logout flows.

You can just skip the complexity of building and maintaining a System for Cross-domain Identity Management (SCIM) server. API Integration Actions allow you to use your existing APIs as-is by mapping them directly to Okta action contracts. By using our low-code builder, you no longer need in-depth knowledge of protocols, making it faster and easier to build, test, and deliver enterprise-grade Secure Identity Integrations. This leads to a fast time-to-value for customers leveraging ISV data for connector-heavy Okta Identity Governance (OIG) use cases.

Benefits of low-code API integration for ISVs

For the ISV application developer:

Built on Workflows: use the low-code builder instead of writing and maintaining complex code
Translates your API calls into formats consumable by Okta: bring your APIs as they are, without having to make any changes
No need for in-depth knowledge of protocols: Workflows makes mapping your API to Okta’s format simple
No need to invest in costly infrastructure: don’t worry about managing a SCIM server
It’s not just secure — it’s fast and easy!

How to build low-code API integrations with Okta Workflows

If you don’t already have an account, sign up for an Okta Integrator Free Plan first. Once created, log in and follow these steps.

Step 1: Create your OIN integration

Click Applications > Your OIN Integrations
Click Build new OIN integration
Choose the single sign-on (SSO) type
If you are building an integration that uses Universal Logout, choose that option. If you are building an integration using provisioning and entitlements, choose those options
Select View integration details

Add the integration details
If you are a customer creating an integration for your orgs during the EA period, put “Customer-created integration - not for the public catalog” in the description field. Then provide a list of your org tenant IDs and subdomains. After submission, you will need to email your account manager to ensure this integration is deployed to your orgs.

Step 2: Configure authentication and API Integration Actions

Tenant settings refer to subdomains or additional information needed for the SSO components
Authentication settings include all of the allowed integration types. Choose the one used by the API and provide the information
Click Save and start building

This will send you to Integration Builder within the Okta Workflows product, where you build out the flows that connect to the API
Validate that the information is correct — it should match what was provided in OIN Wizard

Click on the Authentication tab and add the authentication information. Make sure it matches what is in the OIN Wizard
Fill out the Authentication Mapping section to map the OIN Wizard auth parameters to the Workflows auth parameters

Click on New Component and choose Add Action
Choose the API Integration Action component from the list, and click save

Step 3: Build your low-code workflow flows

Click on New Flow
Create the workflow and repeat as necessary
Once your flows are created, you can create test flows in the test folder to validate that the API calls are being made correctly

After testing, click on Validate and Submit
Click on Validate flows and fix any errors that may exist

Click on Continue submission in OIN
Back in the OIN Wizard, choose the correct flows for each of the API Integration Actions that have been created
Click on Get started with testing

How to test your API integration before publishing to the OIN

Before submitting your integration for review and publication, you must test it in your Okta org. Your integration will only be available on your Okta org. Okta admins will see the same authorization experience.

Provide the testing information needed for Okta to review the submission
Once finished, click on Test your integration

Create a test instance

Fill out the information, including the test account and any SSO testing features on the Test your integration section of the OIN Wizard
Click Test your integration
Follow the instructions in the Test integration section to generate a test instance and complete all of the testing
Validate your flows by clicking the button — take action on any failures that occur

Update a test instance

When you make an update to your submission in the OIN Manager (for example, modifying the scopes or name of the integration), the update will not automatically be reflected in your test instance for security reasons.

To update a test instance, repeat the procedure above for creating a test instance.

Once finished, click the last checkbox to enable submitting your integration for review. This process is similar to the existing OIN Catalog process.

Get started with low-code API integration using Okta

If you’re ready to build an integration between your APIs and Okta’s, start by exploring how to build and publish an application using API Integration Actions to the OIN by reading our product documentation Build and publish API Integration Actions.

Remember to follow us on Twitter 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!

Develop a XAA-Enabled Resource Application and Test with Okta

Tue, 17 Feb 2026 00:00:00 -0500

From an enterprise resource app owner’s perspective, Cross App Access (XAA) is a game-changer because it allows their resources to be “AI-ready” without compromising on security. In the XAA model, resource apps rely on the enterprise’s Identity Provider (IdP) to manage access. Instead of building out interactive OAuth flows, they defer to the IdP to check enterprise policies and user groups, assign AI agent permissions, and log and audit AI agent requests as they occur. In return, the app’s OAuth server needs only to perform a few checks:

When the app’s OAuth server receives a POST request to its token endpoint from an AI agent, the app fetches the IdP’s public keys (via the JWKS endpoint) to ensure the ID-JAG token attached to the request was actually minted by the trusted company IdP.
It confirms the token was intended for this app specifically. If the aud claim doesn’t match the app’s own identifier, it rejects the request.
Finally, it checks the end user ID in the token’s sub claim to know whose data to look up in your database. It must map to the same IdP identity. It will reject the request if the user isn’t recognized.

You can read in depth about XAA to better understand how this works and examine the token exchange flow.

Integrate Your Enterprise AI Tools with Cross-App Access

Manage user and non-human identities, including AI in the enterprise with Cross App Access

Semona Igama

Or watch the video about Cross App Access:

In this tutorial, we’ll demonstrate how to test that an XAA-enabled resource app you have created (TaskFlow) is correctly using Okta as an enterprise Identity Provider (IdP) to sign users in, and we’ll demonstrate how a sample AI app (Agent0) uses XAA to get access to TaskFlow. To do this, you’ll:

Enable Cross App Access in your Okta org
Register and configure the resource app (TaskFlow) in your org
Register the requesting app (Agent0) in your org as a known XAA app and connect it to TaskFlow.
Test that the XAA flow is working correctly when Agent0 requests access to TaskFlow.

Note that the apps (TaskFlow or Agent0) do not use Okta as their authorization server.

Enable Cross App Access in your Okta org

To register your resource app with Okta, and set up secure agent-to-app connections, you’ll need an Okta Developer org enabled with XAA:

If you don’t already have an account, sign up for a new one here: Okta Integrator Free Plan
Once created, sign in to your new Integrator Free Plan org
In the Okta Admin Console, select Settings > Features
Navigate to Early access
Find Cross App Access and select Turn on (enable the toggle)
Refresh the Admin Console

Note: Cross App Access is currently a self-service Early Access (EA) feature. You must enable it through the Admin Console before the apps appear in the catalog. If you don’t see the option right away, refresh and confirm you have the necessary admin permissions. Learn more in the Okta documentation on managing EA and beta features.

Register your requesting app (Agent0)

To test whether your resource app is working correctly, Okta provides a placeholder entry in the Okta Integration Network catalog. It is called Agent0 - Cross App Access (XAA) Sample Requesting App. Add this to your org’s integrations.

Still in Admin Console, go to Applications > Applications
Select Browse App Catalog
Search for “Agent0 - Cross App Access (XAA) Sample Requesting App”, and select it
Select Add Integration

Now to configure it correctly. First, assign user access to Agent0.

Change the Application label if required, and select Done,
Select the Assignments tab
- To assign it to a single user, select Assign > Assign to People and choose your user
- To assign it to a user group, select Assign > Assign to Groups and choose your user group
Click Done

Finally, configure Agent0 with the redirect URI you will use to test Agent0

Select the Sign On tab
Select Edit, and locate the Advanced Sign-on Settings section.
Set the Redirect URI to the URL that your app will use. For example, http://localhost:8080/redirect
Click Save.
Locate and copy the Client ID and Client secret in the Sign-On methods section. Your app must use these when signing users in through Okta.

Note: Only the org authorization server can be used to exchange ID-JAG tokens. Ensure you are using the org authorization server and not an Okta “custom authorization server”.

Get a (XAA) Client ID for Agent0 from the Resource app’s Auth Server

To allow the exchange of an ID-JAG token between Agent0 and your resource app, Agent0 must be registered as an OAuth client in your resource app’s OAuth server.

Register your requesting app (Agent0) as an OAuth client in your resource app’s OAuth server.
Make a note of the Client ID for your requesting app (Agent0). You’ll need this as you set up your resource app.

Note: The process for registering a client ID from your resource app’s OAuth server will vary depending on the product.

Set up your resource app (TaskFlow)

To set up your resource app in your org, you can use the placeholder integration in the OIN catalog called Todo0 - Cross App Access (XAA) Sample Resource App and configure it as your resource app.

Still in Admin Console, navigate to Applications > Applications
Select Browse App Catalog
Search for Todo0 - Cross App Access (XAA) Sample Resource App, and select it
Select Add Integration

Now give it a helpful name and assign user access to TaskFlow.

Set the Application label to TaskFlow, and click Done.
Select the Assignments tab
- To assign it to a single user, select Assign > Assign to People and choose your user
- To assign it to a user group, select Assign > Assign to Groups and choose your user group
Click Done

Update the audience value of your Resource app’s auth server

By default, Okta will issue an ID-JAG token for Agent0 with the audience (aud) value set to that of the sample resource app (Todo0): http://localhost:5001/. You must change this so the ID-JAG token includes an audience value that identifies your actual resource app’s authorization server.

To do this, contact the Okta XAA team to replace your app’s audience value in Okta by sending an email to xaa@okta.com. Provide the following information to the Okta XAA team:

Okta Integrator Org URL: ‘https://{yourOktaDomain}’
Audience: ‘http://yourresourceapps.authserver.org’ Client ID from your own OAuth server: [Agent0’s XAA client ID you created earlier]

Please note that the Client ID you provide must be the client ID from your own OAuth server that was created earlier.

Establish Connections between Agent0 and your resource app

Now that you have set up both requesting and resource apps, you need to establish that Agent0 can be trusted to make requests to your resource app.

Still in Admin Console, navigate to Applications > Applications > Agent0
Go to the Manage Connections tab
Under Apps providing consent, select Add resource apps, select TaskFlow, then Save
Confirm that your resource app appears under Apps providing consent

Now Agent0 and TaskFlow are connected.

Validate that your Resource App and Auth Server work as intended

Once the Okta XAA team confirms that your app’s audience value has been updated in Okta, Agent0 can make a Token Exchange request to Okta and will receive an ID-JAG with the correct audience.

To test the end-to-end XAA flow with Agent0 to your authorization server, create a testing client that completes the following steps:

Agent0 signs the user in with OIDC.
Agent0 exchanges the ID token for an ID-JAG at Okta
Agent0 makes a token request with the ID-JAG at your authorization server

If you need support with taking the steps above, contact xaa@okta.com.

With testing complete, consider publicizing your resource app on the Okta Integration Network (OIN) catalog. Adding it to the catalog makes it easy for Okta’s roughly 18000 enterprise customers to learn about and add it to the suite of tools on their Okta dashboards.

Learn more about Cross App Access, OAuth 2.0, and securing your applications

If this walkthrough helped you understand more about how Cross App Access works in practice, consider learning more about

📘 xaa.dev - a free, open sandbox that lets you explore Cross App Access end-to-end. No local setup. No infrastructure to provision. Just a working environment where you can see the protocol in action.
📘 Okta’s Cross App Access Documentation – official guides and admin docs to configure and manage Cross App Access in production
🎙️ Okta Developer Podcast on MCP and Cross App Access – hear the backstory, use cases, and why this matters for developers
📄 OAuth Identity Assertion Authorization Grant (IETF Draft) – the emerging standard that powers this flow

Make Secure App-to-App Connections Using Cross App Access

Tue, 10 Feb 2026 00:00:00 -0500

Imagine you built a note-taking app. It’s so successful that LargeCorp, an aptly named large enterprise corporation, signed on as a customer. To make it a power tool for your enterprise customers, you need to allow your app to integrate with other productivity tools, such as turning a note into a task in a to-do app.

While common integration patterns work well for individual users, these patterns create security and compliance hurdles for large organizations.

Limitations of API keys and OAuth in enterprise app-to-app connectivity

Connecting independent apps usually involves one of two common strategies. Both have significant drawbacks when used in a corporate environment:

API keys and service accounts These lack user context. They often lead to over-privileged access and create challenging rotation requirements.
Standard OAuth 2.0 A much better, industry-standard best practice over API keys and service accounts, but this relies on individual user consent. IT admins cannot see or control which apps employees connect to, creating shadow IT risks and compliance and security concerns.

Cross App Access (XAA) extends OAuth flows to manage application access

Cross App Access is an OAuth extension based on the Identity Assertion Authorization Grant. It addresses these challenges by using the Enterprise Identity Provider (IdP) as a central broker and was proposed by a collaborative group of organizations and interested individuals.

With XAA, the Identity Provider (IdP) facilitates a secure token exchange. This provides three main benefits.

IT Governance - Admins centrally manage and approve app-to-app connections
Reduced friction - Users avoid repeated and confusing consent prompts
Granular security - Access is limited to specific users and specific tasks.

You can read in depth about XAA in Integrate Your Enterprise AI Tools with Cross App Access to better understand how this works and to look at the token exchange flow

Integrate Your Enterprise AI Tools with Cross-App Access

Manage user and non-human identities, including AI in the enterprise with Cross App Access

Semona Igama

In this tutorial, we’ll add XAA to connect a note-taking app to a to-do app using xaa.dev as our testing ground.

Table of Contents

Limitations of API keys and OAuth in enterprise app-to-app connectivity
Cross App Access (XAA) extends OAuth flows to manage application access
Make app-to-app requests using Cross App Access
Bring your own requestor app to the xaa.dev testing site
Get the NestJS project with OAuth and OpenID Connect (OIDC) started
Exchanging an ID token for an access token for another app
- Exchange the ID token for an intermediary ID-JAG token type
- Use the ID-JAG token to request an access token for a separate app
Inspecting the XAA token exchange
Learn more about XAA and elevating identity security using OAuth

Make app-to-app requests using Cross App Access

We’re using NestJS in this project. The tech stack relies on TypeScript, and we’ll use an OpenID Connect (OIDC) client library to communicate with the IdP and the to-do app’s OAuth Authorization server. Using a well-maintained OIDC client library is a best practice when creating apps that use OAuth flows, as it helps ensure you don’t make subtle errors in OAuth handshakes that compromise security.

For this workshop, you need the following required tooling:

Required tools

Node.js LTS version (v22 or higher at the time of this post)
Command-line terminal application
A code editor/Integrated development environment (IDE), such as Visual Studio Code (VS Code)
Git

Note

This code project is best for developers with web development and TypeScript experience and familiarity with OAuth and OpenID Connect (OIDC) flows at a high level.

If you want to skip directly to the working project, you can find it in the GitHub repo.

Bring your own requestor app to the xaa.dev testing site

The xaa.dev testing site supports testing local client apps. It’s IdP-agnostic, meaning it’s focused on the spec and education, not on a specific company’s product line. In this scenario, we can verify whether our client app, the note-taking app, handles the token exchange with an IdP and the resource app’s authorization server. The best part about this testing site is that it’s self-contained and works out of the box. So you don’t need to create an account with an IdP, nor do you have a resource app with a conformant OAuth authorization server! We just have to bring our client code for testing! Yay for simplicity!

You can read more about the site here:

Introducing xaa.dev: A Playground for Cross App Access

Explore Cross App Access end-to-end with xaa.dev, a free, open playground that lets you test the XAA protocol without any local setup or infrastructure.

Sohail Pathan

Let’s register our note-taking app now.

In your browser, navigate to xaa.dev. The main site provides information about the players in this flow, and you can test the XAA flow step by step there. Please take a moment to step through the flow to get a better sense of the code we’ll build.

When you’re ready, navigate to Developer > Register Client. Add a totally made-up email for more fun when registering.

Select + Register New Client and fill out the required information:

Application Name - I used “Notes App”
Redirect URIs - Enter http://localhost:3000/auth/callback
Post-Logout Redirect URIs - Enter http://localhost:3000
Resource Connections > Add Resource - Choose “Todo0 Resource App” and mark “todos.read” as your allowed scopes before clicking the Add Connection button.

Once all necessary fields have been filled select Register App.

You’ll see a modal with the Client ID and Client Secret. The xaa.dev testing site also provides credentials for the resource app’s authorization server - the Resource Client ID and Resource Client Secret. Copy all four values. We need to add these to our project.

Get the NestJS project with OAuth and OpenID Connect (OIDC) started

You’ll use a starter note-taking app project written in NestJS. Before you get too excited, remember this is a demo app. While the note-taking features are minimal, it does include built-in authentication.

Open a terminal window and run the following commands to get a local copy of the project in a directory named okta-xaa-project and install dependencies. Feel free to fork the repo to track your changes.

git clone -b starter https://github.com/oktadev/okta-js-xaa-requestor-example.git okta-xaa-project
cd okta-xaa-project
npm ci

Open the project in your IDE. Let’s go over the main components and framework choices so you don’t have to discover everything on your own:

The NestJS project depends on Express as the base engine and uses TypeScript.
Views for the landing page and the notes interface use Nunjucks as the templating engine.
Relies on the openid-client to handle all OAuth handshakes. It’s an OIDC client library for JavaScript runtimes.
There’s a basic interceptor implementation that logs HTTP requests and responses to the console. This way, we can see the token exchange flow.

The app requires a client ID, client secret, resource client ID, and resource client secret to run. Let’s add those to the project.

Rename the .env.example file to .env. It already has variables defined and values added to match the URI of the XAA testing site components. Replace the CLIENT_ID, CLIENT_SECRET, RESOURCE_CLIENT_ID, and RESOURCE_CLIENT_SECRET values with the values from the XAA testing site.

The app should now run, but it still won’t make a successful cross-app access request. Serve the app using the command shown:

npm start

Navigate to http://localhost:3000. You should see a landing page that looks like this:

Feel free to sign in. You’re redirected to the XAA testing site’s IdP for the user challenge. Enter the email address and any combination of numbers for the one-time password. You’ll redirect to the notes view and see something like this:

There are no todos yet, and in the IDE’s console we see logging and errors. Each request and response to the XAA testing site’s components has a corresponding log entry. We see the IdP’s redirect with the authorization code, the POST to get tokens along with the request params, and a request to the todo API, which returns a 401 Unauthorized HTTP status code. We need to add the code for the XAA token exchange. Stop serving the app by entering Ctrl+C in the terminal.

Exchanging an ID token for an access token for another app

When you sign in to the note-taking app, the IdP issues an ID token. From here, the XAA token flow is a two-step process:

The note-taking app requests the IDP’s OAuth authorization server to exchange the ID token for a trustworthy intermediary token type, an Identity Assertion JSON Web Token (JWT) also known as ID-JAG, that the todo app recognizes and supports.
The todo app’s OAuth authorization server exchanges the intermediary token and issues an access token.

With the access token in hand, the note-taking app can make resource requests to the todo app’s resource server.

First, we request the trustworthy intermediary token type, the ID-JAG token.

Exchange the ID token for an intermediary ID-JAG token type

In the IDE, open the src/auth/auth.service.ts file. This file contains code for authentication and the OAuth exchange, along with some utility functions. You already have the code to sign in and have the ID token. We’ll continue using the openid-client library for the XAA token exchanges. Find the private helper method exchangeIdTokenForIdJag(). The body of the method has a comment:

// add logic to return an ID-JAG token given the user's ID token

We need to replace the inner workings of this method to return the ID-JAG token instead of an empty promise. No empty promises for us! Our promises are as good as tokens. 👻

Replace the code within the method as shown, then I’ll walk through each code block.

/**
 * Exchange ID token for ID-JAG token (step 1 of ID-JAG flow)
 */
private async exchangeIdTokenForIdJag(
  config: openidClient.Configuration,
  idToken: string,
  authServerUrl: string,
  resourceUrl: string,
  scope: string[],
): Promise<string> {
  const tokenExchangeParams = {
    requested_token_type: 'urn:ietf:params:oauth:token-type:id-jag',
    audience: authServerUrl,
    resource: resourceUrl,
    subject_token: idToken,
    subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
    scope: scope.join(' '),
  };

  const tokenExchangeResponse = await openidClient.genericGrantRequest(
    config,
    'urn:ietf:params:oauth:grant-type:token-exchange',
    tokenExchangeParams,
  );

  return tokenExchangeResponse.access_token;
}

In this first exchange, we call the IdP. The IdP acts as the broker between the two apps as it’s the trusted source.

Let’s step through the key parts of the first code block where we set the token exchange parameters:

requested_token_type - we’re asking the IDP for the ID-JAG token
audience and resource - the authorization server and the todo API we’re requesting resources from
subject_token - the token we’re using for this exchange
subject_token_type - the type of the token we’re using for the exchange
scopes - the requested scopes, such as reading todos

Once we have all these parameters set, we can call the IdP. The openid-client library has a function for making generic grant requests. We can use it to request the token exchange grant type. While the return value is not an access token, the grant request relies on existing OAuth models that defined the access_token response parameter.

Let’s call the method so we can test it out. Find the comment:

// Step 1: Exchange ID token for ID-JAG token

in the exchangeIdTokenForAccessToken() method.

Add the call to the method like this:

// Step 1: Exchange ID token for ID-JAG token
const idJagToken = await this.exchangeIdTokenForIdJag(
  idpConfig,
  idToken,
  authServerUrl,
  resourceUrl,
  scope,
);

We’re adding configuration information, including the IdP, client ID, and client secret. And we have some other required configuration values pulled from the .env file, such as the servers for the todo app and the scopes.

We’ll get the signed Identity Assertion JWT Authorization grant when the call succeeds. This is a signed token from the IdP, so whenever we exchange it in the next step, the recipient knows it’s trustworthy. Step one complete. ✅

Feel free to start the app and check the console log for your first exchange request. You should see the call to LOG [OAuth HTTP] → POST idp.xaa.dev/token in the console. Below that, you’ll see the token exchange parameters that look something like this:

DEBUG [OAuth HTTP]   body:
    requested_token_type=urn:ietf:params:oauth:token-type:id-jag
    audience=https://auth.resource.xaa.dev
    resource=https://api.resource.xaa.dev
    subject_token=eyJhbGc...IdoRppJyZmV9Q
    subject_token_type=urn:ietf:params:oauth:token-type:id_token
    scope=todos.read
    grant_type=urn:ietf:params:oauth:grant-type:token-exchange

The call to get todos will still fail, but you can see the first exchange request in action! 🚀

Use the ID-JAG token to request an access token for a separate app

With the ID-JAG token in hand, we can now move on to the second exchange, exchanging the ID-JAG intermediary token for an access token to the todo app. We make this exchange with the todo app’s OAuth authorization server. The IdP oversees both the note-taking app and the todo app, and trust domains between the two apps facilitate this flow. Remember, in our first exchange, we had to specify the audience for the ID-JAG token in our request - the todo app.

Back in src/auth/auth.service.ts, find the comment:

// add logic to return an access token given the ID-JAG token

This comment is in the placeholder code for the exchangeIdJagForAccessToken() method.

Replace the placeholder code to make the exchange. Your code will look like this:

/**
  * Exchange ID-JAG token for access token (step 2 of ID-JAG flow)
  */
private async exchangeIdJagForAccessToken(
  config: openidClient.Configuration,
  idJagToken: string,
  scope: string[],
): Promise<string> {
  const jwtBearerParams = {
    assertion: idJagToken,
    scope: scope.join(' '),
  };

  const resourceTokenResponse = await openidClient.genericGrantRequest(
    config,
    'urn:ietf:params:oauth:grant-type:jwt-bearer',
    jwtBearerParams,
  );

  return resourceTokenResponse.access_token;
}

We’re following a similar pattern to the first exchange, with a difference in the grant request. This time, the parameters include an assertion, the ID-JAG token. And we make the grant request to the todo app’s OAuth authorization server with the urn:ietf:params:oauth:grant-type:jwt-bearer grant type. This exchange relies upon a pre-existing spec where one can use a bearer JWT for as a grant type to request an access token. That’s what we’re doing in this step.

Next, we’ll call this method in exchangeIdTokenForAccessToken().

Find the comment:

// Step 2: Exchange ID-JAG token for access token

Because we’re calling a new authorization server, the todo app’s OAuth authorization server, we first need to read the well-known discovery docs. The discovery docs include information about the authorization server, such as the server’s capabilities and endpoints, including the token endpoint. Since we’re authenticating with the todo app’s authorization server, not the IdP, we use the resource app’s credentials here. The todo app’s authorization server recognizes RESOURCE_CLIENT_ID and RESOURCE_CLIENT_SECRET, not your notes app’s credentials. We’ve been using a custom fetch implementation to capture the logging you see, so we must include that implementation in openid-client too. Then make the call to the exchangeIdJagForAccessToken() helper method. Your code will look like this:

// Step 2: Exchange ID-JAG token for access token
const resourceAuthConfig = await openidClient.discovery(
  new URL(authServerUrl),
  resourceClientId,
  resourceClientSecret,
  openidClient.ClientSecretPost(resourceClientSecret ?? ''),
);
resourceAuthConfig[openidClient.customFetch] = loggedFetch;

return this.exchangeIdJagForAccessToken(
  resourceAuthConfig,
  idJagToken,
  scope,
);

Make sure to remove any placeholder implementation. Step two complete. ✅

The code to make a request to the todo API using the bearer token already exists in the project. Let’s try running the app now using npm start.

Inspecting the XAA token exchange

After you authenticate, you’ll see the notes and the todos! 🎉

In the terminal console, you’ll see each step of the handshake and requests:

Authentication in the notes app with the IdP returning the ID token
Exchanging the ID token for an ID-JAG token with the IDP’s OAuth authorization server
Exchanging the ID-JAG token for an access token with the todo app’s OAuth authorization server
Call the todo app’s resource server (the API)

Feel free to inspect each step of this flow, the request parameters, and the responses.

These steps allow an app to make requests to a third-party app within enterprise systems securely. You can find the completed project in the GitHub repo with instructions to also test on GitHub Codespaces.

Learn more about XAA and elevating identity security using OAuth

I hope you enjoyed this post on making secure cross-app requests for enterprise use cases. If you found this post interesting, I encourage you to check out these links:

Take User Provisioning to the Next Level with Entitlements

Wed, 21 Jan 2026 00:00:00 -0500

When you work on B2B SaaS apps used by large customer organizations, synchronizing those customers’ users within your software system is tricky! You must synchronize user profile information and the user attributes required for access control management. Customers with large workforces may have thousands of users to manage. They demand a speedy onboarding process, including automated user provisioning from their identity provider!

Managing users across domains is critical to making B2B apps enterprise-scalable. In the Enterprise-Ready and Enterprise-Maturity on-demand workshop series, we tackle the dilemmas faced by developers of SaaS products wanting to scale their apps to enterprise customers. We iterate on a fictitious B2B Todo app more secure and capable for enterprise customers using industry-recognized standards such as OpenID Connect (OIDC) authentication and System for Cross-Domain Identity Management (SCIM) for user provisioning. In this workshop, you build upon a previous workshop introducing automated user provisioning to add support for users’ access management and permissions attributes—their entitlements.

️ℹ️	Note This post requires Okta Identity Governance (OIG) features in your Okta org. Sign up for a new Integrator Free plan to continue.

Posts in the on-demand workshop series
1. How to Get Going with the On-Demand SaaS Apps Workshops
2. Enterprise-Ready Workshop: Authenticate with OpenID Connect
3. Enterprise-Ready Workshop: Manage Users with SCIM
4. Enterprise Maturity Workshop: Terraform
5. Enterprise Maturity Workshop: Automate with no-code Okta Workflows
6. How to Instantly Sign a User Out across All Your Apps
7. Take User Provisioning to the Next Level with Entitlements

This workshop walks you through adding the code to support entitlements in a sample application with three broad sections:

Introduction to the base application, tools, and the development process
See your application’s user and entitlements information in Okta
Use Okta to manage user roles and custom entitlements

If you want to skip to the completed code project for this workshop, you can find it in the entitlements-completed branch on the GitHub repo.

Table of Contents

Manage users at scale using System for Cross-domain Identity Management (SCIM)
- Prepare the Express.js API project
- Serve the Express.js API and test the /Roles SCIM endpoint
Support user roles in the database
Connect Okta to the SCIM server
Create an Okta SCIM application for entitlements governance
SCIM schemas and resources
SCIM resource types
Add roles to the SCIM Users endpoints
Entitlements discovery in Okta
- Syncing user entitlements
- Schema discovery for custom entitlements
Multi-tenant use cases for entitlements
Use SCIM to manage user provisioning and entitlements

Manage users at scale using System for Cross-domain Identity Management (SCIM)

The Todo app tech stack uses a React frontend and an Express API backend. For this workshop, you need the following required tooling:

Required tools

Node.js v18 or higher
Command-line terminal application
A code editor/Integrated development environment (IDE), such as Visual Studio Code (VS Code)
An HTTP client testing tool, such as Postman or the HTTP Client VS Code extension

VS Code has integrated terminals and HTTP client extensions that allow you to work out of this one application for almost everything required in this workshop. The IDE also supports TypeScript, so you’ll get quicker responses on type errors and help with importing modules.

Follow the instructions in the getting started guide for installing the required tools and serving the Todo application.

How to Get Going with the On-Demand SaaS Apps Workshops

Start your journey to identity maturity for your SaaS applications in the enterprise-ready workshops! This post covers installing and running the base application in preparation for the upcoming workshops.

Alisa Duncan

You’ll build upon a prior workshop introducing syncing users across systems using the System for Cross-domain Identity Management (SCIM) protocol.

In this workshop, you’ll dive deeper into automated user provisioning by adding the user attributes required for access management, such as user roles, licensing, permissions, or something else you use to denote what actions a user has access to. The access management attributes of users are known by the generic term, user entitlements. Then, we will continue diving deeper into supporting customized user entitlements using the SCIM protocol.

Before we get going with user entitlements, you’ll first step through the interactive and fun Enterprise-Ready Workshop: Manage Users with SCIM workshop to get the SCIM overview, set up the code and your Okta account, and see how the protocol works. I’ll settle down with a cup of tea and a good book and wait while you learn about SCIM and are ready to continue! 🫖🍵📚

Enterprise-Ready Workshop: Manage users with SCIM

In this workshop, you will add SCIM support to a sample application, so that user changes made in your app can sync to your customer's Identity Provider!

Semona Igama

Prepare the Express.js API project

Start from a clean code project by using the SCIM workshop’s completed project code from the scim-workshop-complete branch. I’ll post the instructions using Git, but you can download the code as a zip file if you prefer and skip the Git command.

Get a local copy of the completed SCIM workshop code and install dependencies by running the following commands in your terminal:

git clone -b scim-workshop-complete https://github.com/oktadev/okta-enterprise-ready-workshops.git
cd okta-enterprise-ready-workshops
npm ci

Open the code project in your IDE. We’ll work exclusively within the Express.js API for this project, and the code files for the API are in the okta-enterprise-ready-workshops/apps/api/src directory.

Create a file named entitlements.ts. We’ll define the API routes for user entitlements in the okta-enterprise-ready-workshops/apps/api/src/entitlements.ts file.

Let’s start by hard-coding an API endpoint for /Roles that returns a list of roles. In the entitlements.ts file, add the following code:

import { Router } from 'express';

export const rolesRoute = Router();

rolesRoute.route('/')
.get(async (req, res) => {
  const roles = [
    'Todo-er',
    'Admin'
  ];

  return res.json(roles);
});

Open okta-enterprise-ready-workshops/apps/api/src/scim.ts. We need to register the endpoint in the Express app by including it as part of the SCIM routes.

At the top of the file, import rolesRoutes

import { rolesRoute } from './entitlements';

At the bottom of the file below the existing code, add

scimRoute.use('/Roles', rolesRoute);

to register the endpoint. Let’s make sure everything works!

Serve the Express.js API and test the `/Roles` SCIM endpoint

In the terminal, start the API by running

npm run serve-api

This command serves the API on port 3333. Launch your HTTP client and call the /Roles endpoint:

GET http://localhost:3333/scim/v2/Roles HTTP/1.1

Do you see a successful response with a list of roles?

HTTP/1.1 200 OK

[
  "Todo-er",
  "Admin"
]

Take a look at the terminal output. You’ll see output recording the GET request!

The project uses Morgan, a library that automatically adds HTTP logging to the Express API. The terminal output includes POST and PUT request payloads, so it’s an excellent way to track the SCIM calls as you work through the workshop.

The npm run serve-api process watches for changes and automatically updates the API, so we don’t need to stop and restart it constantly. But we’re about to make some significant changes. Stop serving the API by entering Ctrl+c in the terminal so we can prepare the database.

Support user roles in the database

The Todo app database needs to support roles; we’ve hardcoded roles so far. It’s time to bring the database to the party. A fancier SaaS app might allow each customer to define their roles. We’ll skip that level of customizability for now and focus on the simplest case. For this workshop, we’ll define supported roles for all Todo app customers instead of allowing role configurations per organization. Taking the position of application roles instead of organization roles makes our database modeling easier. I’ll discuss ways to add per-organization configurability later in the post.

Open okta-enterprise-ready-workshops/prisma/schema.prisma. Add the role model at the end of the file.

model Role {
  id Int @id @default(autoincrement())
  name String
  users User[]
}

A user may have zero or more roles. Update the user model to add roles so that the user model looks like this:

model User {
  id         Int    @id @default(autoincrement())
  email      String
  password   String?
  name       String
  Todo       Todo[]
  org        Org?    @relation(fields: [orgId], references: [id])
  orgId      Int?
  externalId String?
  active     Boolean?
  roles      Role[]
  @@unique([orgId, externalId])
}

With the roles model defined, it’s time to update the database to match the model. We’ll start with a fresh, clean database for this project. In the terminal run

npx prisma migrate reset -f

It helps to have some seed data so we can get going. Here, we’ll define roles available within the Todo app. A user can be a “Todo-er,” “Todo Auditor,” and “Manager.” Open okta-enterprise-ready-workshops/prisma/seed_script.ts and replace the entire file with the code below:

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function main() {
  const org = await prisma.org.create({
    data: {
      domain: 'gridco.example',
      apikey: '123123'
    }
  });
  console.log('Created org Portal', org);

  // Roles defined by the Todo app
  const roles = [
    { name: 'Todo-er' },
    { name: 'Todo Auditor' },
    { name: 'Manager'}
  ];

  const createdRoles = await Promise.all(
    roles.map(data => prisma.role.create({data}))
  );

  for (const role of createdRoles) {
    console.log('Created role ', role);
  }

  const somnusUser = await prisma.user.create({
    data: {
      name: 'Somnus Henderson',
      email: 'somnus.henderson@gridco.example',
      password: 'correct horse battery staple',
      orgId: org.id,
      externalId: '31',
      active: true
    }
  });
  console.log('Created user Somnus', somnusUser)

 const trinityUser = await prisma.user.create({
    data: {
      name: 'Trinity JustTrinity',
      email: 'trinity@gridco.example',
      password: 'Zion',
      orgId: org.id,
      externalId: '32',
      active: true,
      roles: {
        connect: {
          id: createdRoles.find(r => r.name === 'Todo-er')?.id
        }
      }
    },
  })
  console.log('Created user Trinity', trinityUser)
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

Save the file and run the npm script in the terminal to seed the database.

npm run init-db

You’ll see console output for each newly created database record. 🎉

Inspect the database records

You can inspect the database records using Prisma Studio. In a separate terminal, run

npx prisma studio

which launches a web interface to view the database. The site URL is usually http://localhost:5555, shown in the terminal output. Open the site in your browser to view the database tables, records, and relationships.

Connect Okta to the SCIM server

The SCIM Client (the identity provider, Okta) makes requests upon objects held by the SCIM Server (the Todo app).

First, we need to serve the API so Okta can access it. You’ll use a temporary tunnel for local development that makes localhost:3333 publicly accessible so that Okta, the SCIM client, can call your API, the SCIM server. I’ll include the instructions using an NPM library that we don’t have to install or sign up for, but feel free to use your favorite tunneling system if you have one.

You need two terminal sessions.

In one terminal, serve the API using the command:

npm run serve-api

In the second terminal, you’ll run the local tunnel. Run the command:

npx localtunnel --port 3333

This creates a tunnel for the application serving on port 3333. The console output displays the tunnel URL in the format https://{yourTunnelSubdomain}.loca.lt, such as:

your URL is: https://awesome-devs-club.loca.lt

You’ll need this tunnel URL to configure the Okta application.

Create an Okta SCIM application for entitlements governance

In the prerequisite SCIM workshop, you added a SCIM application in Okta to connect to the Todo app. We must do something similar to connect SCIM with entitlements support.

Sign into your Okta Integrator Free account. In the Admin Console, navigate to Applications > Applications. Press the Browse App Catalog button to create a new Okta SCIM application.

In the search bar, search for “(Header Auth) Governance with SCIM 2.0” and select the app. Press Add Integration.

You’ll see a configuration view with two tabs. Press Next on the General settings tab. Leave default settings on the Sign-On Options tab and press Done.

You’ll navigate to your newly created Okta application to add specific configurations about the Todo app.

First, you need to enable Identity Governance. Navigate to the General tab and find the Identity Governance section. Press Edit to select Enabled for Governance Engine. Remember to Save your change.

Navigate to the Provisioning tab and press the Configure API Integration button. Check the Enable API integration checkbox—two more form fields display.

In Base URL field, enter https://{yourTunnelSubdomain}.loca.lt/scim/v2.

It will look like https://awesome-devs-club.loca.lt/scim/v2
In the API Token field, enter Bearer 123123

press Save.

The Provisioning tab has more options to configure within the Settings side nav.

Navigate to the To App option and press Edit.

Enable Create Users
Enable Update User Attributes
Enable Deactivate Users

Press Save.

Import users from the todo app into Okta. Navigate to the Import tab and press the Import Now button. Okta discovers users in your app and tries to match them with users already defined in Okta. A dialog shows Okta discovered the two users you added using the DB script. Select both users and press the Confirm Assignments to confirm the assignments.

You’ll see the imported users in the Assignments tab. But what about entitlements? They’re coming right up!

Stop the tunnel and the API using the Ctrl+c command in the terminal windows. We’ll make some changes to the API that won’t automatically reflect in the local tunnel, so we’ll get all our entitlements changes made and resynchronize with Okta.

SCIM schemas and resources

In the first SCIM workshop, you learned about SCIM’s User resource and built out operations around the user. You updated only a handful of user properties in the workshop, but SCIM is way more powerful thanks to its superpower – extensibility. ✨ User is not the only resource type defined in SCIM.

A Resource represents an object SCIM operates on, such as a user or group. SCIM identified core properties each Resource must define, such as id and a link to the resource’s schema definition. From there, a user extends from the core properties and adds attributes specific to the object, such as adding userName and their emails. A standard published schema exists for all those user-specific attributes within the SCIM spec. You can continue extending resources as needed to represent new resources, such as another SCIM standard-defined schema for Enterprise User.

What’s an example resource other than a user or group? If you said “role” or an “entitlement,” you’re correct! Those resource types must have an id and schemas. Here, Okta used SCIM’s extensibility to define a new resource type.

Okta defines a schema for the Role representation. We can use the schema to ensure we conform to the definition.

Harness TypeScript to conform to SCIM schemas

We can define an interface to model the Role representation. Add a new file to the project named okta-enterprise-ready-workshops/apps/api/src/scim-types.ts and open it up in the IDE. This file will contain the SCIM schema definitions, such as the SCIM core Resource. Each interface defines required and optional properties and the property’s type.

Copy and paste the first interface for the SCIM resource into the scim-types.ts file.

export interface IScimResource {
  id: string;
  schemas: string[];
  meta?: IMetadata;
}

A SCIM resource has an optional meta property containing the resource’s metadata. Your IDE shows errors, so we can fix this by adding the IMetadata definition to the file below the IScimResource:

export interface IMetadata {
  resourceType: RESOURCE_TYPES;
  location?: string;
}

You’ll have a new error for RESOURCE_TYPES. We’ll fix it soon.

Now, on to the Okta Role representation. The role representation extends from the core SCIM resource and adds extra properties. Okta’s schema overlaps with the SCIM standard User roles field, which includes a property for display text. Define the interface and add it to IMetadata below.

export interface IOktaRole extends IScimResource{
  displayName: string;
}

The IOktaRole extends from the core IScimResource interface and adds a new required property, displayName. Each resource requires a schema, a Uniform Resource Namespace (URN) string. Instead of repeatedly typing the string for each role resource, define it below the IOktaRole interface for reusability

export const SCHEMA_OKTA_ROLE = 'urn:okta:scim:schemas:core:1.0:Role';

Let’s fix the RESOURCE_TYPES error. Below the SCHEMA_OKTA_ROLE constant, add the following:

export type RESOURCE_TYPES = 'Role';

You can use the IOktaRole interface in the /Roles endpoint to ensure the response matches the expected structure. Open okta-enterprise-ready-workshops/apps/api/src/entitlements.ts, and update the code to use the interface.

import { Router } from 'express';
import { IOktaRole, SCHEMA_OKTA_ROLE } from './scim-types';

export const rolesRoute = Router();

rolesRoute.route('/')
.get(async (req, res) => {
  const roles: IOktaRole[] = [{
    schemas: [SCHEMA_OKTA_ROLE],
    id: 'one',
    displayName: 'Todo-er'
  }];

  return res.json(roles);
});

Why use TypeScript and interfaces?

TypeScript, a superset of JavaScript, supports type safety. Type safety means we’ll catch errors within the IDE or at build time instead of getting caught by surprise with a runtime error. Here, we state the roles array is of type IOktaRole[]. Try commenting out the required schemas property. You’ll see an error in an IDE that supports TypeScript or when you try to serve the API as console output. We can use type safety to ensure we meet the expectations of required SCIM properties in our calls.

Every code change deserves a quick check. Serve the API and double check everything still works for you when you make the HTTP call to

GET http://localhost:3333/scim/v2/Roles HTTP/1.1

Do you see the one ‘Todo-er’ role in the response? ✅

SCIM list response

We return the array of Okta roles directly in the API response, but this format doesn’t match SCIM list responses. SCIM has a structured response format for lists and a defined schema. This way, SCIM structures all communication between the client and the server so each side knows how to format and parse data.

Let’s define the ListResponse interface. Open okta-enterprise-ready-workshops/apps/api/src/scim-types.ts. The list response contains standard information supporting pagination, the schema for the list response, and the list of objects. Add the interface to the file. I like to organize my definitions, so I added the code between the IOktaRole interface and SCHEMA_OKTA_ROLE string constant.

export interface IListResponse {
  schemas: string[];
  totalResults: number;
  startIndex: number;
  itemsPerPage: number;
  Resources: IOktaRole[];
}

The list response also has a schema URN. Create a constant for this string as you did for the Okta role and add it after the role schema string.

export const SCHEMA_LIST_RESPONSE = 'urn:ietf:params:scim:api:messages:2.0:ListResponse';

The API response must match the list format. Open okta-enterprise-ready-workshops/apps/api/src/entitlements.ts and add IListResponse and SCHEMA_LIST_RESPONSE to the imports from the scim-types file:

import { IListResponse, IOktaRole, SCHEMA_LIST_RESPONSE, SCHEMA_OKTA_ROLE } from './scim-types';

Change rolesRoute response to use the list response:

rolesRoute.route('/')
.get(async (req, res) => {
  const roles: IOktaRole[] = [{
    schemas: [SCHEMA_OKTA_ROLE],
    id: 'one',
    displayName: 'Todo-er'
  }];

  const listResponse: IListResponse = {
    schemas: [SCHEMA_LIST_RESPONSE],
    totalResults: roles.length,
    itemsPerPage: roles.length,
    startIndex: 1,
    Resources: roles
  };

  return res.json(listResponse);
});

Double-check everything still works. Send the HTTP request to your API. ✅

GET http://localhost:3333/scim/v2/Roles HTTP/1.1

Return database-defined roles in the SCIM `/Roles` endpoint

Each role has an ID and a name. We can retrieve the roles from the database and populate the /Roles response.

Open okta-enterprise-ready-workshops/apps/api/src/entitlements.ts and make the changes to retrieve the roles from the database and map the database results to the IOktaRole properties. You’ll need to import some dependencies, so ensure the import statements match. The SCIM ListResponse supports pagination, so we’ll add the required code to consider the query parameters.

import { Router } from 'express';
import { PrismaClient } from '@prisma/client';
import { IListResponse, IOktaRole, SCHEMA_LIST_RESPONSE, SCHEMA_OKTA_ROLE } from './scim-types';

const prisma = new PrismaClient();

export const rolesRoute = Router();

rolesRoute.route('/')
.get(async (req, res) => {
  const startIndex = parseInt(req.query.startIndex as string ?? '1');
  const recordLimit = parseInt(req.query.recordLimit as string ?? '100');

  const roles = await prisma.role.findMany({
    take: recordLimit,
    skip: startIndex - 1
  });

const listResponse: IListResponse = {
    schemas: [SCHEMA_LIST_RESPONSE],
    totalResults: roles.length,
    startIndex,
    itemsPerPage: recordLimit,
    Resources: roles.map(role => ({
      schemas: [SCHEMA_OKTA_ROLE],
      id: role.id.toString(),
      displayName: role.name
    }))
  };

  return res.json(listResponse);
});

Run a quick check to ensure everything still works. Serve the API and call the /Roles endpoint using your HTTP client. ✅

You should see three roles matching the roles in the database. 🎉

SCIM resource types

We implemented the /Roles endpoint and discussed how SCIM defines a resource. But how would the SCIM client know about this Okta Role type? Enter discovery—learning about a SCIM server’s capabilities and supported objects such as resources!

SCIM clients and servers communicate about the types of resources through a standard endpoint, the/ResourceType endpoint. SCIM clients call the endpoint to discover what resources they can expect. The endpoint returns a SCIM list response outlining resources. You can add every resource type used, including the standard User and EnterpriseUser resources, but Okta expects resource definitions only for custom types.

First, we’ll create the interface for the ResourceType and define some strings. Open okta-enterprise-ready-workshops/apps/api/src/scim-types.ts. Add the interface for IResourceType above the IListResponse interface.

export interface IResourceType {
  id?: string;
  schemas: string[];
  name: string; 
  description?: string;
  endpoint: string;
  schema: string; 
  meta: IMetadata;
}

Notice the IResourceType doesn’t extend from the IScimResource interface. For example, the SCIM standard doesn’t require id for a resource type. Since the SCIM standard treats ResourceType as an exception case of Resource, we defined it separately without the relation instead of extending from IScimResource.

When following the SCIM protocol, responses that list values, such as the list of roles or resource types, use the SCIM list response format.

The IListResource interface must support IOktaRole and IResourceType. Using generics and union types, we can support different list response objects . Update the IListResource to match the code below.

export interface IListResponse<T extends IScimResource | IResourceType> {
  schemas: string[];
  totalResults: number;
  startIndex: number;
  itemsPerPage: number;
  Resources: T[];
}

You’ll see errors in the IDE and, if you’re running the API, within the console output. No worries; we’ll fix those errors soon!

Resource types have a schema URN and use “ResourceType” as the resourceType string in the metadata. Add SCHEMA_RESOURCE_TYPE and edit RESOURCE_TYPES so your string constants section looks like the code below.

export const SCHEMA_OKTA_ROLE = 'urn:okta:scim:schemas:core:1.0:Role';
export const SCHEMA_LIST_RESPONSE = 'urn:ietf:params:scim:api:messages:2.0:ListResponse';
export const SCHEMA_RESOURCE_TYPE = 'urn:ietf:params:scim:schemas:core:2.0:ResourceType';
export type RESOURCE_TYPES = 'Role' | 'ResourceType';

Open okta-enterprise-ready-workshops/apps/api/src/entitlements.ts. Let’s fix the IListResponse error for the /Roles endpoint and specify the object type in the list, the IOktaRole type. The code building out the list changes to

  const listResponse: IListResponse<IOktaRole> = {
    schemas: [SCHEMA_LIST_RESPONSE],
    totalResults: roles.length,
    startIndex,
    itemsPerPage: recordLimit,
    Resources: roles.map(role => ({
      schemas: [SCHEMA_OKTA_ROLE],
      id: role.id.toString(),
      displayName: role.name
    }))
  };

You shouldn’t see errors anymore! 🎉

We have a new endpoint to add. Update the imports from the ./scim-types file and declare a new route for resource types.

import { Router } from 'express';
import { PrismaClient } from '@prisma/client';
import {
  IListResponse, IOktaRole, IResourceType, SCHEMA_LIST_RESPONSE, SCHEMA_OKTA_ROLE, SCHEMA_RESOURCE_TYPE
} from './scim-types';

const prisma = new PrismaClient();
export const rolesRoute = Router();
export const resourceTypesRoute = Router();


// existing rolesRoute code below

Then create the /ResourceTypes route by adding the code below the rolesRoute

resourceTypesRoute.route('/')
.get((req, res) => {
  const resourceTypes: IResourceType[] = [{
    schemas: [SCHEMA_RESOURCE_TYPE],
    id: 'Role',
    name: 'Role',
    endpoint: '/Roles',
    description: 'Roles you can set on users of Todo App',
    schema: SCHEMA_OKTA_ROLE,
    meta: {
      resourceType: 'ResourceType'
    }
  }];

  const resourceTypesListResponse: IListResponse<IResourceType> = {
    schemas: [SCHEMA_LIST_RESPONSE],
    totalResults: resourceTypes.length,
    startIndex: 1,
    itemsPerPage: resourceTypes.length,
    Resources: resourceTypes
  };

  return res.json(resourceTypesListResponse);
});

Next, you must register the /ResourceTypes route in the API. Open okta-enterprise-ready-workshops/apps/api/src/scim.ts.

Update the import to include resourceTypesRoute

import { resourceTypesRoute, rolesRoute } from './entitlements';

Add the /ResourceTypes endpoint to the end of the file. You should have two routes defined.

scimRoute.use('/Roles', rolesRoute );
scimRoute.use('/ResourceTypes', resourceTypesRoute);

Double-check your new route by starting the API if it’s not running. Use your HTTP client to make the call

GET http://localhost:3333/scim/v2/ResourceTypes HTTP/1.1

If you see a response with the Okta role resource type, the API call works as expected! ✅

Add roles to the SCIM Users endpoints

Let’s add roles to the existing user calls. We want to reflect a user’s roles in Okta within the Todo app, so the GET and POST /Users calls must support roles. Near the top of the scim.ts file, find IUserSchema interface.

Update the interface to add the roles property:

interface IUserSchema {
  schemas: string[];
  userName?: string;
  id?: string;
  name?: {
    givenName: string;
    familyName: string;
  };
  emails?: {primary: boolean, value: string, type: string}[];
  displayName?: string;
  locale?: string;
  meta?: {
    resourceType: string;
  }
  externalId?: string;
  groups?: [];
  password?: string;
  active?: boolean;
  detail?: string;
  status?: number;
  roles?: {value: string, display: string}[];
}

The User SCIM schema defines roles property as a list of objects that may contain properties named value and display, among others. Okta uses these properties for role data.

Update the SCIM add users call to include roles

The first route defined is the POST /Users route definition. You need to add roles when saving to the database. Find the comment

// Create the User in the database

and update the database command and the as shown.

// Create the User in the database
const user = await prisma.user.create({
  data: {
    org : { connect: {id: ORG_ID}},
    name,
    email,
    password,
    externalId,
    active,
    roles: {
      connect: newUser.roles?.map(role => ({id: parseInt(role.value)})) || []
    }
  },
  include: {
    roles: true
  }
});

console.log('Account Created ID: ', user.id);

One more place to update in the POST /Users call. We need to return the roles in the response. Right below the console.log() update the userResponse to

userResponse = { ...defaultUserSchema,
  id: `${user.id}`,
  userName: user.email,
  name: {
    givenName,
    familyName
  },
  emails: [{
    primary: true,
    value: user.email,
    type: "work"
  }],
  displayName: name,
  externalId: user.externalId,
  active: user.active,
  roles: user.roles.map(role => ({display: role.name, value: role.id.toString()}))
};

Add roles when getting a list of users in SCIM

Continuing to the GET /Users call, search for the code to find users in the database

await prisma.user.findMany({...});

to add roles to the select argument.

const users = await prisma.user.findMany({
  take: recordLimit,
  skip: startIndex,
  select: {
    id: true,
    email: true,
    name: true,
    externalId: true,
    active: true,
    roles: true
  },
  where
});

The GET /Users response also needs roles, so update the

usersResponse['Resources'] = users.map(user => {...});

like this.

usersResponse['Resources'] = users.map(user => {
  const [givenName, familyName] = user.name.split(" ");
  return {
    ...defaultUserSchema,
    id: user.id.toString(),
    userName: user.email,
    name: {
      givenName,
      familyName
    },
    emails: [{
      primary: true,
      value: user.email,
      type: 'work'
    }],
    displayName: user.name,
    externalId: user.externalId,
    active: user.active,
    roles: user.roles.map(role => ({display: role.name, value: role.id.toString()}))
  }
});

Update the response for an individual user

On to the next call, GET /Users/:userId. We need to add roles to the

const user = await prisma.user.findFirst({...});

database command. Update it to match the code below.

const user = await prisma.user.findFirst({
  select: {
    id: true,
    email: true,
    name: true,
    externalId: true,
    active: true,
    roles: true
  },
  where: {
    id,
    org: {id: ORG_ID},
  }
});

Then, find the comment

// If no response from DB, return 404

to update the userResponse object inside the if statement. Update the userResponse to match the code shown.

userResponse = {
  ...defaultUserSchema,
  id: id.toString(),
  userName: email,
  name: {
    givenName,
    familyName
  },
  emails: [{
    primary: true,
    value: email,
    type: 'work'
  }],
  displayName: name,
  externalId: user.externalId,
  active: user.active,
  roles: user.roles.map(role => ({display: role.name, value: role.id.toString()}))
} satisfies IUserSchema;

Update the `/Users` call so SCIM clients can set their roles

Another endpoint down, but there’s one more left, the PUT /Users/:userId.

Find the code

const { name, emails } = updatedUserRequest;

and change it to the following code so we can work with the user’s updated roles and save the changes in the database.

const { name, emails, roles } = updatedUserRequest;

const updatedUser = await prisma.user.update({
  data: {
    email: emails.find(email => email.primary).value,
    name: `${name.givenName} ${name.familyName}`,
    roles: {
      set: roles?.map(role => ({id: parseInt(role.value)})) || []
    }
  },
  where : {
    id
  },
  include: {
    roles: true
  }
});

Lastly, we need to update the response from the PUT /Users/:userId call. Update the userResponse object to look like this.

userResponse = {
  ...defaultUserSchema,
  id: id.toString(),
  userName: updatedUser.email,
  name: {
    givenName,
    familyName
  },
  emails: [{
    primary: true,
    value: updatedUser.email,
    type: 'work'
  }],
  displayName: updatedUser.name,
  externalId: updatedUser.externalId,
  active: updatedUser.active,
  roles: updatedUser.roles?.map(role => ({display: role.name, value: role.id.toString()}))
} satisfies IUserSchema;

Serve the API if you aren’t running it using npm run serve-api. Let’s make an HTTP call to get all users to double-check our work.

GET http://localhost:3333/scim/v2/Users
Authorization: Bearer 123123

You will see the list of users. Each user object has a roles and entitlements property. ✅

Entitlements discovery in Okta

What can Okta do with user entitlements? Okta can discover defined entitlements, such as the roles you define for the Todo app, and applies existing roles on users. Now that you have all the endpoints needed for a SCIM client to discover resources held by a SCIM server, you can see this in action on Okta.

You’ll need to serve the API and create a local tunnel. Serve the API using the npm run serve-api command. In a second terminal window, run npx localtunnel --port 3333. Take note of your tunnel URL.

Sign into your Okta Developer Edition account. Navigate to Applications > Applications and select the “(Header Auth) Governance with SCIM 2.0” app. Navigate to the Provisioning tab and select Integration. Press Edit.

Update the Base URL field by replacing the tunnel URL with your new tunnel URL. Make sure you keep the /scim/v2 path. Your base URL might look something like https://beep-bop-boop.loca.lt/scim/v2. Press Save.

Updating the API integration kicks off a discovery process. Okta automatically looks for roles as a possible entitlement type. It then matches the roles it discovers for the Todo application and matches them again with roles defined on the users. You can see Okta working by looking at the terminal window serving the API. You can see the calls Okta makes by inspecting the HTTP requests and their payloads written to the console. 🔍

Make sure to keep the API running! There’s more work to do here!

Navigate to the Governance tab. The tab you see is Entitlements. Do you see Role in the sidenav below the Search input? If not, hang tight. Because an app may have many defined entitlements, Okta starts a background job to discover roles asynchronously. It could take up to 10 minutes for the roles to populate.

Eventually, you’ll see Role; when you select it, you’ll see metadata about it, such as the variable name, data type, and description. We also see the values: “Manager,” “Todo Auditor,” and “Todo-er.”

You can define policies for users that automatically assign their entitlements when adding them to this integration app. While that’s pretty nifty, this post focuses on building out the SCIM endpoints for entitlements, so I’ll include links to resources that explain this feature in more detail at the end of the post.

Press < Back to application to return to the SCIM Okta app.

Syncing user entitlements

When you use an identity provider, you want that system to be the source of truth for managing the users’ identities and access levels. You want to set the roles you defined for the Todo app onto users within Okta. That would be pretty sweet, right?

Since we last ran our user import with hardcoded roles, let’s ensure we’ve synchronized everything from the starting state of the application before we start managing with Okta.

Within the SCIM application tab, navigate to Import and press the Import Now button. Okta scans the users in the todo app, but since there are no new users, there’s no confirmation process. The user scan synced the existing users and the roles!

Navigate to Assignments. Each user has a vertical 3-dot menu icon to display a context menu allowing you to Edit user assignment, View access details **, and **Unassign. Find “Trinity” and **View access details ** on them. A panel shows you Trinity’s role pre-assigned in the Todo app. 🎉 Exit the side panel by clicking outside the side panel.

Let’s assign a new role to “Somnus” using Okta. Open the context menu for “Somnus” and View access details. Press the Edit access button. You’ll see a page titled Edit access. Press the Customize entitlements button. You’ll see a warning followed by a section called Custom Entitlements.

You’ll see Role and a dropdown list with values. Select a role, such as “Todo-er,” and press Save to add the role to the user.

But how about the Todo app? Take a look at the terminal output where you’re serving the API. The HTTP call tracing shows a PUT request on the user adding the role. Can you see the role of the user in the database? You can check it out by opening another terminal window, running npx prisma studio, and navigating to the website. ✅

You can now use Okta to manage user roles centrally and automatically update the user’s grants!

Stop serving the local tunnel and API for this next section.

Schema discovery for custom entitlements

What if we have something other than roles in the application? Can SCIM support custom entitlement strategies? SCIM is extensible, meaning it has the structure for custom schemas and extends beyond the core resources. A SCIM server can publish a custom schema if it defines custom resource types.

Let’s say you have user roles but want to add a custom entitlement, such as licenses, profiles, or something else. Let’s walk through the example where we want to add a custom entitlement. We will call this “Characteristic,” such as whether the user is tall. We know Trinity is tall, so it’s logical to note their tallness as part of their user attributes.

SCIM clients must discover resources through schemas. So, we first need to define the schema describing “Characteristics.” Note that I came up with “Characteristics” as the name of this attribute, but you will need to change it for your user entitlements model, whether it be some sort of permissions system or something else. Custom schemas can extend from an existing schema, such as Okta’s entitlement schema, which tracks data as a key-value pair, and add our own flavoring to it.

In the IDE, open okta-enterprise-ready-workshops/apps/api/src/scim-types.ts.

Add new schema URNs after the SCHEMA_OKTA_ROLE definition towards the end of the file:

export const SCHEMA_OKTA_ENTITLEMENT = 'urn:okta:scim:schemas:core:1.0:Entitlement';
export const SCHEMA_CHARACTERISTIC = 'urn:bestapps:scim:schemas:extension:todoapp:1.0:Characteristic';

We defined a new schema URN for the characteristic SCIM resource. Following naming conventions for extension schemas, we substituted our company name (Best Apps) and added the app’s name (Todo app). The format looks like this

urn:<Company name>:scim:schemas:extension:<App name>:1.0:<Custom entitlement>

Right now, there’s a custom TypeScript type for RESOURCE_TYPES. Since we’ll have custom schemas as a resource type, update the code.

export type RESOURCE_TYPES = 'Role' | 'ResourceType' | 'Schema';

SCIM defines required and optional attributes to describe a schema resource. We’ll define the interfaces for a schema resource. Add the following interfaces to the scim-types.ts file. I added mine after the other interfaces and before the URNs.

export interface ISchema {
  id: string;
  name?: string;
  description?: string;
  attributes: IAttribute[];
  meta: IMetadata;
}

export interface IAttribute {
  name: string;
  description: string;
  type: string;
  multiValued: boolean;
  required: boolean;
  caseExact: boolean;
  mutability: string;
  returned: string;
  uniqueness: string;
}

Characteristic is a unique resource type because it’s a new, custom type extending from an existing schema. We must explicitly show this relationship for consuming SCIM clients, like Okta. Find the IResourceType interface. We’ll add a new optional property, schemaExtensions and inline the type definition.

export interface IResourceType {
  id?: string;
  schemas: string[];
  name: string;
  description?: string;
  endpoint: string;
  schema: string;
  schemaExtensions?: {schema: string, required: boolean}[];
  meta: IMetadata;
}

SCIM clients expect a list of schemas that you offer in the SCIM server. You might’ve guessed what that means. You must wrap all the schemas in a SCIM ListResponse. Find IListResponse and add ISchema as a supported type. The IListResponse interface changes to:

export interface IListResponse<T extends IScimResource | IResourceType | ISchema> {
  schemas: string[];
  totalResults: number;
  startIndex: number;
  itemsPerPage: number;
  Resources: T[];
}

Finally, we define what a characteristic attribute looks like by adding the interface shown below.

export interface ICharacteristic extends IScimResource {
  type: string;
  displayName: string;
}

With all the types and interfaces defined, it’s time to write the code for the route. Open okta-enterprise-ready-workshops/apps/api/src/entitlements.ts.

Update the import array from ./scim-types.ts:

import {
  ICharacteristic,
  IListResponse,
  IOktaRole,
  IResourceType,
  ISchema,
  SCHEMA_CHARACTERISTIC,
  SCHEMA_LIST_RESPONSE,
  SCHEMA_OKTA_ENTITLEMENT,
  SCHEMA_OKTA_ROLE,
  SCHEMA_RESOURCE_TYPE
} from './scim-types';

Below the other route definitions, add two new route definitions.

export const schemasRoute = Router();
export const characteristicsRoute = Router();

Now, it’s time to define the /Schemas route. The /Schemas endpoint returns a list of schemas. You can return schemas for all the resources you use, even for User, but Okta allows us to skip the strict SCIM requirements and only return custom schemas. The custom schema we’ll return has metadata about a user characteristic, specifically whether the user is tall. Add the following code at the end of the file.

schemasRoute.route('/')
  .get((_, res) => {
    const characteristic: ISchema = {
      id: SCHEMA_CHARACTERISTIC,
      name: 'Characteristic',
      description: 'User characteristics for entitlements',
      attributes: [{
        name: 'is_tall',
        description: 'Profile entitlement extension for tallness factor',
        type: 'string',
        multiValued: false,
        required: false,
        mutability: 'readWrite',
        returned: 'default',
        caseExact: false,
        uniqueness: 'none'
      }],
      meta: {
        resourceType: 'Schema',
        location: `/v2/Schemas/${SCHEMA_CHARACTERISTIC}`
      }
    };

    const schemas = {
      schemas: [SCHEMA_LIST_RESPONSE],
      totalResults: 1,
      startIndex: 1,
      itemsPerPage: 1,
      Resources: [
        characteristic
      ]
    };

    return res.json(schemas);
  });

And we must define a route for /Characteristics, in the same way one exists for /Roles. We won’t worry about updating the database for this as I don’t want to detract from the SCIM concepts. We’ll hardcode the characteristic for now so you can see what this looks like within Okta. Feel free to add the required code to connect it to the database as homework. 🏆 Add the following code below the schemas route:

characteristicsRoute.route('/')
  .get((_, res) => {
    const characteristicsListResponse: IListResponse<ICharacteristic> = {
      schemas: [
        SCHEMA_OKTA_ENTITLEMENT,
        SCHEMA_CHARACTERISTIC
      ],
      totalResults: 1,
      startIndex: 1,
      itemsPerPage: 1,
      Resources: [{
        schemas: [SCHEMA_CHARACTERISTIC],
        type: "Characteristic",
        id: "is_tall",
        displayName: "This user is so tall"
      }]
    };

    return res.json(characteristicsListResponse);
  });

Notice the ID is the string “is_tall”. I modeled it to look like an enum here so that it’s distinct from roles, but IDs in your system may be a UUID or an integer.

Lastly, we must add the new characteristic resource type to the /ResourceTypes response so that Okta knows the resource exists. Find the resourceTypes.route('/') definition and update the resourceTypes array to include both roles and characteristics.

  const resourceTypes: IResourceType[] = [{
    schemas: [SCHEMA_RESOURCE_TYPE],
    id: 'Role',
    name: 'Role',
    endpoint: '/Roles',
    description: 'Roles you can set on users of Todo App',
    schema: SCHEMA_OKTA_ROLE,
    meta: {
      resourceType: 'ResourceType'
    }
  },
  {
    schemas: [SCHEMA_RESOURCE_TYPE],
    id: 'Characteristic',
    name: 'Characteristic',
    endpoint: '/Characteristics',
    description: 'This resource type is user characteristics',
    schema: 'urn:okta:scim:schemas:core:1.0:Entitlement',
    schemaExtensions: [
      {
        schema: SCHEMA_CHARACTERISTIC,
        required: true
      }
    ],
    meta: {
      resourceType: 'ResourceType'
    }
  }
];

Now, we must register the routes in the API. Open okta-enterprise-ready-workshops/apps/api/src/scim.ts. At the top of the file, update the imports from ./entitlements to

import { characteristicsRoute, resourceTypesRoute, rolesRoute, schemasRoute } from './entitlements';

At the end of the file, add the code to register the /Schemas and /Charactertistics routes to the API.

scimRoute.use('/Schemas', schemasRoute);
scimRoute.use('/Characteristics', characteristicsRoute);

Serve the API by running npm run serve-api in a terminal window. In a second terminal window, run npx localtunnel --port 3333 to create a local tunnel for the API. Keep track of the tunnel URL.

Back in the Okta Admin console, navigate to Applications > Applications and open the SCIM with governance Okta app. Navigate to Provisioning > Integration. Press Edit and update the Base URL using the new tunnel URL. Don’t forget to keep the /scim/v2 at the end of the URL. The URL should look something like

https://{yourTunnelSubdomain}.loca.lt/scim/v2

Press Save.

Okta discovers schemas and resource types when updating the provisioning configuration. If you look at the HTTP call tracing in the terminal window serving the API, you’ll see that Okta made a GET request to both /Schemas and /Characteristics.

Navigate to the Governance. Characteristic may take 10-15 minutes to populate, but you’ll see the display name and value when it does. Go < Back to application and navigate to Assignments. Open the user context menu for “Trinity” by pressing the three vertical dots icon menu and opening View entitlements. Press Edit and Customize entitlements to add the is_tall user characteristic. Save the changes and navigate back to the Okta SCIM app.

Check out the terminal serving the API for the HTTP call tracing. You’ll see a PUT request on Trinity adding the new characteristic. The field goes into the core SCIM User entitlements property. Check it out by inspecting the HTTP tracing in the console output. ✅

Multi-tenant use cases for entitlements

In this workshop, we defined roles for the entire Todo app. But what if your SaaS app supports tenant-configurable roles? You must make structural changes to the Todo app database to support organization roles. Notice that an organization has a unique API key, and we included this API as a Bearer token value in the Authorization header. All the SCIM calls from Okta can target a specific organization in the Todo app, including the organization’s custom roles.

️ℹ️	Note We used an API key for demonstration purposes, but we recommend using OAuth to secure the calls from Okta to your API for production applications.

Use SCIM to manage user provisioning and entitlements

In this workshop, you dived deeper into SCIM and learned about resources and schemas. You also synced users and their pre-existing entitlements from the Todo app and provisioned users within Okta. I hope you enjoyed this workshop and have ideas for using it for your SaaS applications! Check out the Identity Governance help docs to learn about Okta Identity Governance.

You can find the completed code project in the entitlements-workshop-completed branch within the GitHub repo.

If you want to learn more about what it means to be enterprise-ready and to have enterprise maturity, check out the other workshops in this series

Posts in the on-demand workshop series
1. How to Get Going with the On-Demand SaaS Apps Workshops
2. Enterprise-Ready Workshop: Authenticate with OpenID Connect
3. Enterprise-Ready Workshop: Manage Users with SCIM
4. Enterprise Maturity Workshop: Terraform
5. Enterprise Maturity Workshop: Automate with no-code Okta Workflows
6. How to Instantly Sign a User Out across All Your Apps
7. Take User Provisioning to the Next Level with Entitlements

Want to learn about more exciting topics? Let us know by commenting below. To get notified about exciting new content, follow us on Twitter and subscribe to our YouTube channel.

Introducing xaa.dev: A Playground for Cross App Access

Tue, 20 Jan 2026 00:00:00 -0500

AI agents are quickly becoming part of everyday enterprise development. They summarize emails, coordinate calendars, query internal systems, and automate workflows across tools.

But once an AI agent needs to access an enterprise application on behalf of a user, things get complicated.

How do you securely let an AI-powered app act for a user without exposing credentials, spamming consent prompts, or losing administrative control?

This is the problem Cross App Access (XAA) is designed to solve.

Today, we’re introducing xaa.dev, a free, open playground that lets you explore Cross App Access end-to-end. No local setup. No infrastructure to provision. Just a working environment where you can see the protocol in action.

Note: xaa.dev is currently in beta. We’re actively developing new features for the next release, and your feedback helps shape what comes next.

Table of Contents

What is Cross App Access?
The problem: testing XAA is hard
What you can do on xaa.dev
How to get started
Why we built a testing site for cross app access
Inspect the XAA flow
Learn more

What is Cross App Access?

Cross App Access refers to a typical enterprise pattern: one application accesses another application’s resources on behalf of a user.

For example:

An internal AI assistant fetching updates from a project management system
A workflow engine booking meetings through a calendar API
An agent querying internal data sources to complete a task

Traditionally, OAuth consent flows handle this. That approach works well for consumer-based apps, but it creates friction in enterprise environments where organizations require workforce oversight:

Applications and their access levels are centrally managed
IT teams need visibility into trust relationships
Access must be revocable without user involvement

Cross App Access shifts responsibility from end users to the enterprise identity layer.

Instead of prompting users for consent, the Identity Provider (IdP) issues a signed identity assertion called an ID-JAG (Identity JWT Authorization Grant). This assertion cryptographically represents the user and the requesting application. Resource applications trust the IdP’s assertion and issue access accordingly.

The result:

No interactive consent screens making application access seamless for employees
Clear, auditable trust boundaries
Complete administrative control over app-to-app access

For a deeper dive into why this matters for enterprise AI, read more about Cross App Access in this post:

Integrate Your Enterprise AI Tools with Cross-App Access

Manage user and non-human identities, including AI in the enterprise with Cross App Access

Semona Igama

The problem: testing XAA is hard

XAA is built on an emerging OAuth extension called the Identity Assertion JWT Authorization Grant – an IETF draft that Okta, along with public and industry contributors, has been actively contributing to. It’s powerful, but it’s also new, and new protocols need experimentation.

Here’s the challenge: to test XAA locally, you’d need to spin up:

An Identity Provider (IdP)
An Authorization Server for the resource application
The resource API itself
A requesting application (the agent or client app)

That’s hours (or days) of configuration before you can even see a single token exchange. Most developers give up before getting to the interesting part.

xaa.dev changes that.

We pre-configured all the components so you can focus on understanding the flow, not debugging dev environments. Go from zero to a working XAA token exchange in under 60 seconds.

Launch the playground. It’s free and requires no signup.

What you can do on xaa.dev

The playground gives you hands-on access to every role in the Cross App Access flow:

Requesting App

Step into the shoes of an AI agent or client application. Authenticate a user, request an ID-JAG from the IdP, and exchange it for an access token at the resource server.

Resource App

See the other side of the transaction. Watch how a resource server validates the identity assertion, verifies the trust relationship, and issues scoped access tokens.

Identity Provider

We’ve built a simulated IdP with pre-configured test users. Log in, see how ID-JAGs are minted, and inspect the cryptographic claims that make XAA secure.

Resource MCP Server

Connect your AI agents using the Model Context Protocol (MCP). The playground provides a ready-to-use MCP server that acts as a resource application, letting you test how AI agents can securely access protected resources through the Cross App Access flow.

Bring your own Requesting App

The built-in Requesting App is great for learning, but the real power comes when you test with your own application, whether it’s a traditional app or an MCP client. Register a client on the playground, grab the configuration, and integrate it into your local app. This lets you validate your XAA implementation against a working IdP and Resource App without spinning up your own infrastructure. The playground documentation walks you through the setup step-by-step.

How to get started

Getting started with xaa.dev takes less than a minute:

Step 1: Open the playground

Visit xaa.dev. No account required.

Step 2: Explore the components

The playground has three components (Requesting App, Resource App, and Identity Provider), each with its own URL. Visit any component to see its configuration and understand how it participates in the XAA flow.

Step 3: Follow the guided flow

Walk through the four steps of the XAA flow: User Authentication (SSO), Token Exchange, Access Token Request, and Access Resource. Inspect the requests and responses at each step to see exactly how XAA works under the hood.

That’s it. No local tools installations, Docker containers, environment variables, or CORS headaches.

Watch this walkthrough video of the playground if you’d like a guided tour:

Why we built a testing site for cross app access

XAA is built on an emerging IETF specification, the Identity Assertion JWT Authorization Grant. As enterprise AI adoption accelerates, there’s a clear need: developers want to understand XAA, but the barrier to entry is too high.

xaa.dev lowers the barrier. It helps you:

Learn faster – See the protocol in action before writing any code
Build confidently – Understand exactly what tokens to expect and validate
Experiment safely – Test edge cases without affecting production systems

Inspect the XAA flow

XAA is how enterprise applications will securely connect in an AI-first world. Whether you’re building agents, integrating SaaS tools, or just curious about modern OAuth patterns, xaa.dev gives you a risk-free environment to learn. Check it out and let us know how it works for you!

Learn more

Ready to go deeper? Check out these resources:

Checkout Cross App Access Integration in Okta – Securing AI-driven access together
Build Secure Agent-to-App Connections with Cross App Access – Hands-on implementation guide
Identity Assertion JWT Authorization Grant (IETF Draft) – The specification behind XAA

Have questions or feedback? Reach out to us on Twitter, join the conversation on the Okta Developer Forums, or drop a comment below. We’re actively improving xaa.dev based on developer input – your feedback shapes what we build next.

Follow us on Twitter and subscribe to our YouTube channel for more content on identity, security, and building with Okta.

Okta Developer Connect Recap

Mon, 19 Jan 2026 00:00:00 -0500

Identity has become one of the most important control points in modern systems. As applications grow more distributed and AI-driven automation becomes part of everyday workflows, identity increasingly defines how secure, predictable, and trustworthy those systems are. Decisions about access, scope, and lifecycle now shape not only the user experience, but also how well security holds up as systems scale.

With this shift in mind, we hosted our first flagship Okta Developer Connect event in India, in Bengaluru. Led by the Okta Developer Advocacy team, the event brought together developers, architects, engineering managers, IAM practitioners, and technology leaders for a day of focused conversations on how identity needs to evolve as systems scale, and as AI agents begin to act alongside humans.

Where identity, security, and AI connect

Throughout the day, the theme stood out clearly: identity now sits at the intersection of application architecture, security decisions, and system behavior. As organizations integrate across ecosystems and introduce AI-driven workflows, identity increasingly determines how safely systems interact and how confidently access can be controlled.

Identity was discussed as foundational infrastructure, spanning users, applications, APIs, services, and AI agents. The conversations focused on how identity decisions ripple across systems as they become more interconnected, and why those decisions matter long after the first sign-in.

The sessions balanced identity fundamentals with how teams are applying them today. Core identity standards and practices were discussed as the foundation for building secure, interoperable systems that scale. From there, the conversations expanded into modern use cases across Okta’s platform, including identity for AI-driven systems using the Okta MCP Server, Cross App Access, secure integrations through the Okta Integration Network, automation with Okta Workflows, lifecycle management, and emerging capabilities such as Verifiable Digital Credentials.

A shared conversation with the community

Beyond the talks, Okta Developer Connect was intentionally designed to be interactive, with open discussions, audience Q&A, quizzes, interactive sessions, surveys, and a research panel created space for participation beyond listening. Attendees engaged directly with Okta engineers, product leaders, and advocates, exchanging perspectives shaped by the systems they build and operate. Those exchanges added important context to the day, grounding the conversations in real systems and practical implementations.

Looking ahead

Okta Developer Connect Bengaluru marked the beginning of an ongoing series focused on practical identity education and open technical dialogue. The series aims to help teams think more clearly about building enterprise-ready systems, how identity standards and practices are reflected across the stack, and how AI-driven systems impact access and security assumptions.

As identity continues to sit at the intersection of security, system architecture, and AI-driven automation, these conversations will only become more important.

We’re excited to continue building this forum with the developer community, grounded in standards, informed by real-world systems, and focused on designing identity that scales with what comes next.

Stay tuned for upcoming Okta Developer Connect events, and follow OktaDev on LinkedIn and Twitter for the latest updates.

Okta Developer

Okta Developer Connect San Francisco 2026 Recap

Unlocking AI in the enterprise: Okta for AI Agents is GA

Why this conversation matters now

Cross App Access and the protocol behind it

Securing AI agents with Auth0

The panel: What teams are actually asking about AI agents

What this means for builders

Community, Conversations, and the AI interview activation

What comes next

The One Where I Found My Way to DevRel

Building docs for developers

Finding my place in devrel

Joining the Okta community

How to Build Low-Code API Integrations for Enterprise Apps Using Okta

What are API Integration Actions?

Benefits of low-code API integration for ISVs

How to build low-code API integrations with Okta Workflows

Step 1: Create your OIN integration

Step 2: Configure authentication and API Integration Actions

Step 3: Build your low-code workflow flows

How to test your API integration before publishing to the OIN

Create a test instance

Update a test instance

Get started with low-code API integration using Okta

Develop a XAA-Enabled Resource Application and Test with Okta

Enable Cross App Access in your Okta org

Register your requesting app (Agent0)

Get a (XAA) Client ID for Agent0 from the Resource app’s Auth Server

Set up your resource app (TaskFlow)

Update the audience value of your Resource app’s auth server

Establish Connections between Agent0 and your resource app

Validate that your Resource App and Auth Server work as intended

Learn more about Cross App Access, OAuth 2.0, and securing your applications

Make Secure App-to-App Connections Using Cross App Access

Limitations of API keys and OAuth in enterprise app-to-app connectivity

Cross App Access (XAA) extends OAuth flows to manage application access

Make app-to-app requests using Cross App Access

Bring your own requestor app to the xaa.dev testing site

Get the NestJS project with OAuth and OpenID Connect (OIDC) started

Exchanging an ID token for an access token for another app

Exchange the ID token for an intermediary ID-JAG token type

Use the ID-JAG token to request an access token for a separate app

Inspecting the XAA token exchange

Learn more about XAA and elevating identity security using OAuth

Take User Provisioning to the Next Level with Entitlements

Manage users at scale using System for Cross-domain Identity Management (SCIM)

Prepare the Express.js API project

Serve the Express.js API and test the /Roles SCIM endpoint

Support user roles in the database

Connect Okta to the SCIM server

Create an Okta SCIM application for entitlements governance

SCIM schemas and resources

Harness TypeScript to conform to SCIM schemas

SCIM list response

Return database-defined roles in the SCIM /Roles endpoint

SCIM resource types

Add roles to the SCIM Users endpoints

Update the SCIM add users call to include roles

Add roles when getting a list of users in SCIM

Update the response for an individual user

Update the /Users call so SCIM clients can set their roles

Entitlements discovery in Okta

Syncing user entitlements

Schema discovery for custom entitlements

Multi-tenant use cases for entitlements

Use SCIM to manage user provisioning and entitlements

Introducing xaa.dev: A Playground for Cross App Access

What is Cross App Access?

The problem: testing XAA is hard

What you can do on xaa.dev

Requesting App

Resource App

Identity Provider

Resource MCP Server

Bring your own Requesting App

How to get started

Why we built a testing site for cross app access

Inspect the XAA flow

Learn more

Serve the Express.js API and test the `/Roles` SCIM endpoint

Return database-defined roles in the SCIM `/Roles` endpoint

Update the `/Users` call so SCIM clients can set their roles