From 0500909f8267b589e39b6e3b4903cc953c1295af Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Wed, 24 Jun 2026 14:49:18 -0700 Subject: [PATCH 1/2] feat: Scaffolding new AI docs IA --- main/config/nav.en.json | 20 ++++- main/config/navigation/ai.json | 18 ---- .../navigation/auth0-for-ai-agents.json | 87 +++++++++++++++++++ main/config/navigation/mcp.json | 55 ++++++++++++ .../ai-agents-mcp/auth0-for-ai-agents.mdx | 0 .../agent-as-principal.mdx | 4 + .../quickstarts/async-authorization.mdx | 0 .../quickstarts/authorization-for-rag.mdx | 0 .../call-others-apis-on-users-behalf.mdx | 0 .../call-your-apis-on-users-behalf.mdx | 0 main/docs/ai-agents-mcp/mcp.mdx | 4 + main/docs/ai.mdx | 16 ++-- 12 files changed, 174 insertions(+), 30 deletions(-) create mode 100644 main/config/navigation/auth0-for-ai-agents.json create mode 100644 main/config/navigation/mcp.json create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/agent-as-principal.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/async-authorization.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/authorization-for-rag.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-others-apis-on-users-behalf.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-your-apis-on-users-behalf.mdx create mode 100644 main/docs/ai-agents-mcp/mcp.mdx diff --git a/main/config/nav.en.json b/main/config/nav.en.json index e8d51e2ef1..970b42573f 100644 --- a/main/config/nav.en.json +++ b/main/config/nav.en.json @@ -38,9 +38,25 @@ "$ref": "./navigation/deploy-and-monitor.json" }, { - "tab": "Auth0 AI", + "tab": "AI Agents & MCP", "icon": "/icons/auth0-ai.svg", - "$ref": "./navigation/ai.json" + "menu": [ + { + "item": "Auth0 for AI Agents", + "icon": "/icons/sdks.svg", + "$ref": "./navigation/auth0-for-ai-agents.json" + }, + { + "item": "MCP", + "icon": "/icons/events-catalog.svg", + "$ref": "./navigation/mcp.json" + }, + { + "item": "AI Tools", + "icon": "/icons/universal-components.svg", + "$ref": "./navigation/ai.json" + } + ] }, { "tab": "Platform", diff --git a/main/config/navigation/ai.json b/main/config/navigation/ai.json index fa773c8e36..a9b27bcdb2 100644 --- a/main/config/navigation/ai.json +++ b/main/config/navigation/ai.json @@ -2,24 +2,6 @@ "pages": [ "docs/ai", "docs/get-started/auth0-guide", - "docs/get-started/auth0-for-ai-agents", - { - "group": "Auth0 Model Context Protocol (MCP) Server", - "root": "docs/get-started/auth0-mcp-server", - "pages": [ - "docs/get-started/auth0-mcp-server/getting-started-with-auth0-mcp-server", - { - "group": "Auth0 Model Context Protocol (MCP) Server Guides", - "pages": [ - "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides", - "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/streamline-api-authorization-flows-with-auth0-model-context-protocol-mcp", - "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/implement-advanced-security-monitoring-with-auth0-model-context-protocol-mcp", - "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/understanding-scopes" - ] - }, - "docs/get-started/auth0-mcp-server/auth0-mcp-tools-reference" - ] - }, "docs/get-started/build-with-ai-tools", "docs/get-started/auth0-agent-experience" ] diff --git a/main/config/navigation/auth0-for-ai-agents.json b/main/config/navigation/auth0-for-ai-agents.json new file mode 100644 index 0000000000..090a23f814 --- /dev/null +++ b/main/config/navigation/auth0-for-ai-agents.json @@ -0,0 +1,87 @@ +{ + "groups": [ + { + "group": " ", + "pages": [ + "docs/ai-agents-mcp/auth0-for-ai-agents" + ] + }, + { + "group": "Get Started", + "icon": "globe", + "pages": [ + "docs/ai-agents-mcp/auth0-for-ai-agents/agent-as-principal", + { + "group": "Concepts", + "pages": [ + "docs/ai-agents-mcp/auth0-for-ai-agents/concepts/user-agent-authentication", + "docs/ai-agents-mcp/auth0-for-ai-agents/concepts/delegated-authorization", + "docs/ai-agents-mcp/auth0-for-ai-agents/concepts/async-authorization-hitl", + "docs/ai-agents-mcp/auth0-for-ai-agents/concepts/fine-grained-authorization" + ] + }, + { + "group": "Quickstarts", + "pages": [ + "docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-your-apis-on-users-behalf", + "docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-others-apis-on-users-behalf", + "docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/async-authorization", + "docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/authorization-for-rag" + ] + } + ] + }, + { + "group": "Call APIs on User's Behalf", + "icon": "apple", + "pages": [ + "docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange", + { + "group": "Cross App Access (XAA)", + "pages": [ + "docs/secure/call-apis-on-users-behalf/xaa", + "docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment", + "docs/secure/call-apis-on-users-behalf/xaa/manage-xaa-in-okta", + "docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow" + ] + }, + { + "group": "Token Vault", + "pages": [ + "docs/secure/call-apis-on-users-behalf/token-vault", + "docs/secure/call-apis-on-users-behalf/token-vault/connected-accounts-for-token-vault", + "docs/secure/call-apis-on-users-behalf/token-vault/refresh-token-exchange-with-token-vault", + "docs/secure/call-apis-on-users-behalf/token-vault/access-token-exchange-with-token-vault", + "docs/secure/call-apis-on-users-behalf/token-vault/privileged-worker-token-exchange-with-token-vault", + "docs/secure/call-apis-on-users-behalf/token-vault/configure-token-vault" + ] + } + ] + }, + { + "group": "Integrations", + "icon": "android", + "pages": [ + "docs/ai-agents-mcp/integrations/social-integrations", + "docs/ai-agents-mcp/integrations/enterprise-integrations" + ] + }, + { + "group": "Resources", + "icon": "android", + "pages": [ + { + "group": "How-Tos", + "pages": [ + "docs/ai-agents-mcp/how-tos/check-google-calendar-availability", + "docs/ai-agents-mcp/how-tos/list-github-repos", + "docs/ai-agents-mcp/how-tos/list-slack-channels", + "docs/ai-agents-mcp/how-tos/get-salesforce-opportunities" + ] + }, + "docs/ai-agents-mcp/sample-apps", + "docs/ai-agents-mcp/sdks" + ] + } + ] +} diff --git a/main/config/navigation/mcp.json b/main/config/navigation/mcp.json new file mode 100644 index 0000000000..9fca5f238e --- /dev/null +++ b/main/config/navigation/mcp.json @@ -0,0 +1,55 @@ +{ + "groups": [ + { + "group": " ", + "pages": [ + "docs/ai-agents-mcp/mcp" + ] + }, + { + "group": "Auth for MCP", + "icon": "globe", + "pages": [ + { + "group": "Get Started", + "pages": [ + "docs/ai-agents-mcp/mcp/register-mcp-application", + "docs/ai-agents-mcp/mcp/enable-resource-parameter" + ] + }, + { + "group": "Secure MCP Servers", + "pages": [ + "docs/ai-agents-mcp/mcp/authorize-mcp-server", + "docs/ai-agents-mcp/mcp/call-your-apis-on-users-behalf", + "docs/ai-agents-mcp/mcp/control-access-to-mcp-tools" + ] + }, + { + "group": "Test", + "pages": [ + "docs/ai-agents-mcp/mcp/test-with-mcp-inspector" + ] + }, + "docs/ai-agents-mcp/mcp/sample-apps" + ] + }, + { + "group": "Auth0 Model Context Protocol (MCP) Server", + "icon": "globe", + "pages": [ + "docs/get-started/auth0-mcp-server/getting-started-with-auth0-mcp-server", + { + "group": "Auth0 Model Context Protocol (MCP) Server Guides", + "pages": [ + "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides", + "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/streamline-api-authorization-flows-with-auth0-model-context-protocol-mcp", + "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/implement-advanced-security-monitoring-with-auth0-model-context-protocol-mcp", + "docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/understanding-scopes" + ] + }, + "docs/get-started/auth0-mcp-server/auth0-mcp-tools-reference" + ] + } + ] +} diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/agent-as-principal.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/agent-as-principal.mdx new file mode 100644 index 0000000000..b2c6d24ddb --- /dev/null +++ b/main/docs/ai-agents-mcp/auth0-for-ai-agents/agent-as-principal.mdx @@ -0,0 +1,4 @@ +--- +description: Learn more about Agent as Principal +title: Agent as Principal +--- \ No newline at end of file diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/async-authorization.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/async-authorization.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/authorization-for-rag.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/authorization-for-rag.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-others-apis-on-users-behalf.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-others-apis-on-users-behalf.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-your-apis-on-users-behalf.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/quickstarts/call-your-apis-on-users-behalf.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/main/docs/ai-agents-mcp/mcp.mdx b/main/docs/ai-agents-mcp/mcp.mdx new file mode 100644 index 0000000000..58eb04d688 --- /dev/null +++ b/main/docs/ai-agents-mcp/mcp.mdx @@ -0,0 +1,4 @@ +--- +description: Learn about how Auth0 secures MCP servers. +title: MCP +--- \ No newline at end of file diff --git a/main/docs/ai.mdx b/main/docs/ai.mdx index 1501759468..66906443d5 100644 --- a/main/docs/ai.mdx +++ b/main/docs/ai.mdx @@ -3,18 +3,14 @@ title: Auth0 AI description: Use the Auth0 AI product suite to learn about Auth0, integrate with AI agents, and improve your tenant’s security posture. --- - -Learn about Auth0 Guide, an AI-powered chatbot that answers your questions about Auth0. - - - -Leverage Auth0 for AI Agents to secure every layer of your GenAI stack. + +Use the Docs MCP Server to search and index the Auth0 knowledge base. - -Integrate Auth0 with Model Context Protocol (MCP). + +Learn about Auth0 Guide, an AI-powered chatbot that answers your questions about Auth0. - -Use AI tools to search and index the Auth0 knowledge base. + +Learn how Auth0 scores AI agent performance across models and frameworks. From deceb3652892583ef2c4952c95587de0d98c6de2 Mon Sep 17 00:00:00 2001 From: Lucy Zhou Date: Mon, 29 Jun 2026 12:48:04 -0700 Subject: [PATCH 2/2] Refactor Cross App Access and create dummy articles --- main/config/nav.en.json | 12 +- .../config/navigation/agent-as-principal.json | 13 ++ .../navigation/auth0-for-ai-agents.json | 10 - main/config/navigation/cross-app-access.json | 13 ++ .../docs/ai-agents-mcp/agent-as-principal.mdx | 9 + .../agent-as-principal/get-started.mdx | 9 + .../manage-agent-permissions.mdx | 9 + .../agent-as-principal/register-agent.mdx | 9 + .../concepts/async-authorization-hitl.mdx | 9 + .../concepts/delegated-authorization.mdx | 9 + .../concepts/fine-grained-authorization.mdx | 9 + .../concepts/user-agent-authentication.mdx | 9 + .../check-google-calendar-availability.mdx | 9 + .../how-tos/get-salesforce-opportunities.mdx | 9 + .../how-tos/list-github-repos.mdx | 9 + .../how-tos/list-slack-channels.mdx | 9 + .../integrations/enterprise-integrations.mdx | 9 + .../integrations/social-integrations.mdx | 9 + main/docs/ai-agents-mcp/sample-apps.mdx | 9 + main/docs/ai-agents-mcp/sdks.mdx | 9 + main/docs/ai-agents-mcp/xaa.mdx | 89 ++++++++ .../ai-agents-mcp/xaa/manage-xaa-in-okta.mdx | 27 +++ .../xaa/set-up-xaa-test-environment.mdx | 216 ++++++++++++++++++ main/docs/ai-agents-mcp/xaa/test-xaa-flow.mdx | 94 ++++++++ 24 files changed, 607 insertions(+), 11 deletions(-) create mode 100644 main/config/navigation/agent-as-principal.json create mode 100644 main/config/navigation/cross-app-access.json create mode 100644 main/docs/ai-agents-mcp/agent-as-principal.mdx create mode 100644 main/docs/ai-agents-mcp/agent-as-principal/get-started.mdx create mode 100644 main/docs/ai-agents-mcp/agent-as-principal/manage-agent-permissions.mdx create mode 100644 main/docs/ai-agents-mcp/agent-as-principal/register-agent.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/async-authorization-hitl.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/delegated-authorization.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/fine-grained-authorization.mdx create mode 100644 main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/user-agent-authentication.mdx create mode 100644 main/docs/ai-agents-mcp/how-tos/check-google-calendar-availability.mdx create mode 100644 main/docs/ai-agents-mcp/how-tos/get-salesforce-opportunities.mdx create mode 100644 main/docs/ai-agents-mcp/how-tos/list-github-repos.mdx create mode 100644 main/docs/ai-agents-mcp/how-tos/list-slack-channels.mdx create mode 100644 main/docs/ai-agents-mcp/integrations/enterprise-integrations.mdx create mode 100644 main/docs/ai-agents-mcp/integrations/social-integrations.mdx create mode 100644 main/docs/ai-agents-mcp/sample-apps.mdx create mode 100644 main/docs/ai-agents-mcp/sdks.mdx create mode 100644 main/docs/ai-agents-mcp/xaa.mdx create mode 100644 main/docs/ai-agents-mcp/xaa/manage-xaa-in-okta.mdx create mode 100644 main/docs/ai-agents-mcp/xaa/set-up-xaa-test-environment.mdx create mode 100644 main/docs/ai-agents-mcp/xaa/test-xaa-flow.mdx diff --git a/main/config/nav.en.json b/main/config/nav.en.json index 970b42573f..557bf2e6bf 100644 --- a/main/config/nav.en.json +++ b/main/config/nav.en.json @@ -41,11 +41,21 @@ "tab": "AI Agents & MCP", "icon": "/icons/auth0-ai.svg", "menu": [ + { + "item": "Agent as Principal", + "icon": "/icons/sdks.svg", + "$ref": "./navigation/agent-as-principal.json" + }, { "item": "Auth0 for AI Agents", "icon": "/icons/sdks.svg", "$ref": "./navigation/auth0-for-ai-agents.json" }, + { + "item": "Cross App Access (XAA)", + "icon": "/icons/authenticate.svg", + "$ref": "./navigation/cross-app-access.json" + }, { "item": "MCP", "icon": "/icons/events-catalog.svg", @@ -55,7 +65,7 @@ "item": "AI Tools", "icon": "/icons/universal-components.svg", "$ref": "./navigation/ai.json" - } + } ] }, { diff --git a/main/config/navigation/agent-as-principal.json b/main/config/navigation/agent-as-principal.json new file mode 100644 index 0000000000..f07dc03bbf --- /dev/null +++ b/main/config/navigation/agent-as-principal.json @@ -0,0 +1,13 @@ +{ + "groups": [ + { + "group": "Agent as Principal", + "pages": [ + "docs/ai-agents-mcp/agent-as-principal", + "docs/ai-agents-mcp/agent-as-principal/get-started", + "docs/ai-agents-mcp/agent-as-principal/register-agent", + "docs/ai-agents-mcp/agent-as-principal/manage-agent-permissions" + ] + } + ] +} diff --git a/main/config/navigation/auth0-for-ai-agents.json b/main/config/navigation/auth0-for-ai-agents.json index 090a23f814..196372b1a8 100644 --- a/main/config/navigation/auth0-for-ai-agents.json +++ b/main/config/navigation/auth0-for-ai-agents.json @@ -10,7 +10,6 @@ "group": "Get Started", "icon": "globe", "pages": [ - "docs/ai-agents-mcp/auth0-for-ai-agents/agent-as-principal", { "group": "Concepts", "pages": [ @@ -36,15 +35,6 @@ "icon": "apple", "pages": [ "docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange", - { - "group": "Cross App Access (XAA)", - "pages": [ - "docs/secure/call-apis-on-users-behalf/xaa", - "docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment", - "docs/secure/call-apis-on-users-behalf/xaa/manage-xaa-in-okta", - "docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow" - ] - }, { "group": "Token Vault", "pages": [ diff --git a/main/config/navigation/cross-app-access.json b/main/config/navigation/cross-app-access.json new file mode 100644 index 0000000000..8df32b1a73 --- /dev/null +++ b/main/config/navigation/cross-app-access.json @@ -0,0 +1,13 @@ +{ + "groups": [ + { + "group": "Cross App Access (XAA)", + "pages": [ + "docs/ai-agents-mcp/xaa", + "docs/ai-agents-mcp/xaa/set-up-xaa-test-environment", + "docs/ai-agents-mcp/xaa/manage-xaa-in-okta", + "docs/ai-agents-mcp/xaa/test-xaa-flow" + ] + } + ] +} diff --git a/main/docs/ai-agents-mcp/agent-as-principal.mdx b/main/docs/ai-agents-mcp/agent-as-principal.mdx new file mode 100644 index 0000000000..55e904ebb6 --- /dev/null +++ b/main/docs/ai-agents-mcp/agent-as-principal.mdx @@ -0,0 +1,9 @@ +--- +title: Agent as Principal +description: Learn how to use Agent as Principal to grant AI agents their own identity and permissions. +sidebarTitle: Overview +--- + +# Agent as Principal + +Coming soon. diff --git a/main/docs/ai-agents-mcp/agent-as-principal/get-started.mdx b/main/docs/ai-agents-mcp/agent-as-principal/get-started.mdx new file mode 100644 index 0000000000..1d1ea597c3 --- /dev/null +++ b/main/docs/ai-agents-mcp/agent-as-principal/get-started.mdx @@ -0,0 +1,9 @@ +--- +title: Get Started with Agent as Principal +description: Learn how to set up Agent as Principal for your AI agents. +sidebarTitle: Get Started +--- + +# Get Started with Agent as Principal + +Coming soon. diff --git a/main/docs/ai-agents-mcp/agent-as-principal/manage-agent-permissions.mdx b/main/docs/ai-agents-mcp/agent-as-principal/manage-agent-permissions.mdx new file mode 100644 index 0000000000..5c08354a6e --- /dev/null +++ b/main/docs/ai-agents-mcp/agent-as-principal/manage-agent-permissions.mdx @@ -0,0 +1,9 @@ +--- +title: Manage Agent Permissions +description: Learn how to manage permissions for AI agents acting as principals. +sidebarTitle: Manage Agent Permissions +--- + +# Manage Agent Permissions + +Coming soon. diff --git a/main/docs/ai-agents-mcp/agent-as-principal/register-agent.mdx b/main/docs/ai-agents-mcp/agent-as-principal/register-agent.mdx new file mode 100644 index 0000000000..f81f5ed721 --- /dev/null +++ b/main/docs/ai-agents-mcp/agent-as-principal/register-agent.mdx @@ -0,0 +1,9 @@ +--- +title: Register an Agent +description: Learn how to register an AI agent as a principal in Auth0. +sidebarTitle: Register an Agent +--- + +# Register an Agent + +Coming soon. diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/async-authorization-hitl.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/async-authorization-hitl.mdx new file mode 100644 index 0000000000..15cd4eebe3 --- /dev/null +++ b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/async-authorization-hitl.mdx @@ -0,0 +1,9 @@ +--- +title: Async Authorization and Human-in-the-Loop +description: Learn how async authorization and human-in-the-loop patterns work for AI agents. +sidebarTitle: Async Authorization and HITL +--- + +# Async Authorization and Human-in-the-Loop + +Coming soon. diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/delegated-authorization.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/delegated-authorization.mdx new file mode 100644 index 0000000000..8fcc03f059 --- /dev/null +++ b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/delegated-authorization.mdx @@ -0,0 +1,9 @@ +--- +title: Delegated Authorization +description: Learn how delegated authorization allows AI agents to act on behalf of users. +sidebarTitle: Delegated Authorization +--- + +# Delegated Authorization + +Coming soon. diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/fine-grained-authorization.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/fine-grained-authorization.mdx new file mode 100644 index 0000000000..5eff820f57 --- /dev/null +++ b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/fine-grained-authorization.mdx @@ -0,0 +1,9 @@ +--- +title: Fine-Grained Authorization +description: Learn how to use fine-grained authorization to control what AI agents can access. +sidebarTitle: Fine-Grained Authorization +--- + +# Fine-Grained Authorization + +Coming soon. diff --git a/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/user-agent-authentication.mdx b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/user-agent-authentication.mdx new file mode 100644 index 0000000000..465543c395 --- /dev/null +++ b/main/docs/ai-agents-mcp/auth0-for-ai-agents/concepts/user-agent-authentication.mdx @@ -0,0 +1,9 @@ +--- +title: User and Agent Authentication +description: Learn how to authenticate both users and AI agents in your application. +sidebarTitle: User and Agent Authentication +--- + +# User and Agent Authentication + +Coming soon. diff --git a/main/docs/ai-agents-mcp/how-tos/check-google-calendar-availability.mdx b/main/docs/ai-agents-mcp/how-tos/check-google-calendar-availability.mdx new file mode 100644 index 0000000000..ec92fc4665 --- /dev/null +++ b/main/docs/ai-agents-mcp/how-tos/check-google-calendar-availability.mdx @@ -0,0 +1,9 @@ +--- +title: Check Google Calendar Availability +description: Learn how to use an AI agent to check Google Calendar availability on behalf of a user. +sidebarTitle: Check Google Calendar Availability +--- + +# Check Google Calendar Availability + +Coming soon. diff --git a/main/docs/ai-agents-mcp/how-tos/get-salesforce-opportunities.mdx b/main/docs/ai-agents-mcp/how-tos/get-salesforce-opportunities.mdx new file mode 100644 index 0000000000..23950b2d9c --- /dev/null +++ b/main/docs/ai-agents-mcp/how-tos/get-salesforce-opportunities.mdx @@ -0,0 +1,9 @@ +--- +title: Get Salesforce Opportunities +description: Learn how to use an AI agent to retrieve Salesforce opportunities on behalf of a user. +sidebarTitle: Get Salesforce Opportunities +--- + +# Get Salesforce Opportunities + +Coming soon. diff --git a/main/docs/ai-agents-mcp/how-tos/list-github-repos.mdx b/main/docs/ai-agents-mcp/how-tos/list-github-repos.mdx new file mode 100644 index 0000000000..3e45ed9202 --- /dev/null +++ b/main/docs/ai-agents-mcp/how-tos/list-github-repos.mdx @@ -0,0 +1,9 @@ +--- +title: List GitHub Repositories +description: Learn how to use an AI agent to list GitHub repositories on behalf of a user. +sidebarTitle: List GitHub Repositories +--- + +# List GitHub Repositories + +Coming soon. diff --git a/main/docs/ai-agents-mcp/how-tos/list-slack-channels.mdx b/main/docs/ai-agents-mcp/how-tos/list-slack-channels.mdx new file mode 100644 index 0000000000..c3199e5cb7 --- /dev/null +++ b/main/docs/ai-agents-mcp/how-tos/list-slack-channels.mdx @@ -0,0 +1,9 @@ +--- +title: List Slack Channels +description: Learn how to use an AI agent to list Slack channels on behalf of a user. +sidebarTitle: List Slack Channels +--- + +# List Slack Channels + +Coming soon. diff --git a/main/docs/ai-agents-mcp/integrations/enterprise-integrations.mdx b/main/docs/ai-agents-mcp/integrations/enterprise-integrations.mdx new file mode 100644 index 0000000000..2fc3c874e1 --- /dev/null +++ b/main/docs/ai-agents-mcp/integrations/enterprise-integrations.mdx @@ -0,0 +1,9 @@ +--- +title: Enterprise Integrations +description: Connect your AI agents to enterprise identity providers. +sidebarTitle: Enterprise Integrations +--- + +# Enterprise Integrations + +Coming soon. diff --git a/main/docs/ai-agents-mcp/integrations/social-integrations.mdx b/main/docs/ai-agents-mcp/integrations/social-integrations.mdx new file mode 100644 index 0000000000..1dcba708e0 --- /dev/null +++ b/main/docs/ai-agents-mcp/integrations/social-integrations.mdx @@ -0,0 +1,9 @@ +--- +title: Social Integrations +description: Connect your AI agents to social identity providers. +sidebarTitle: Social Integrations +--- + +# Social Integrations + +Coming soon. diff --git a/main/docs/ai-agents-mcp/sample-apps.mdx b/main/docs/ai-agents-mcp/sample-apps.mdx new file mode 100644 index 0000000000..997dfe2668 --- /dev/null +++ b/main/docs/ai-agents-mcp/sample-apps.mdx @@ -0,0 +1,9 @@ +--- +title: Sample Apps +description: Explore sample applications demonstrating Auth0 for AI Agents. +sidebarTitle: Sample Apps +--- + +# Sample Apps + +Coming soon. diff --git a/main/docs/ai-agents-mcp/sdks.mdx b/main/docs/ai-agents-mcp/sdks.mdx new file mode 100644 index 0000000000..cf02e67e49 --- /dev/null +++ b/main/docs/ai-agents-mcp/sdks.mdx @@ -0,0 +1,9 @@ +--- +title: SDKs +description: Explore SDKs for building AI agents with Auth0. +sidebarTitle: SDKs +--- + +# SDKs + +Coming soon. diff --git a/main/docs/ai-agents-mcp/xaa.mdx b/main/docs/ai-agents-mcp/xaa.mdx new file mode 100644 index 0000000000..84b01bea9c --- /dev/null +++ b/main/docs/ai-agents-mcp/xaa.mdx @@ -0,0 +1,89 @@ +--- +description: Learn how to leverage Cross App Access (XAA) to call APIs on the user's behalf. +sidebarTitle: Overview +title: Cross App Access (XAA) +--- + +import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx" + + + + + +This guide assumes you use Okta as your enterprise identity provider (IdP) and have administrative access to an Okta tenant you can use for testing. If you don’t have one, read [Create and configure your Okta tenant](/docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment#create-and-configure-your-okta-tenant). + + + +Connecting third-party apps and AI agents in an enterprise creates two key problems: poor IT visibility into data sharing and repetitive consent flows for users. + +Cross App Access (XAA) addresses these challenges by allowing IT admins to centrally define access controls for how SaaS applications, like AI agents, connect on a user's behalf. Admins manage these connections in a central dashboard, like the Okta Admin Console, which eliminates disruptive OAuth consent prompts for end-users. The result is improved organizational security, governance, and user experience. + +XAA implements the [Identity Assertion Authorization Grant](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/), an in-progress OAuth extension that allows an AI agent or application (Requesting App) to obtain a secure token through the enterprise IdP. This token enables the Requesting App to call the APIs of another application (Resource App) on the end-user’s behalf. To learn more, read [How it works](#how-it-works). + +## Key benefits + +XAA delivers key benefits for every role in your enterprise ecosystem: + +- For Enterprise IT administrators: Centralized control, visibility, and policy enforcement over application access to enterprise and user data. +- For SaaS providers and developers: Standardized and secure integration for enterprise AI to foster ecosystem growth. +- For end-users: Streamlined and frictionless connections between applications, eliminating complex OAuth consent flows. + +## Use cases + +Common use cases for XAA include: + +- Connect AI agents to enterprise applications: An employee uses an AI agent to read from their calendar app and post an update about their availability in the enterprise messaging app. Instead of requiring the employee to go through redirection flows and consent prompts, the AI agent uses XAA to obtain an access token from the enterprise IdP to securely call the APIs of both the calendar and messaging app, if approved by the enterprise access policy. +- Connect SaaS applications: In our previous example, the enterprise calendar and messaging app both support XAA. Employees can seamlessly connect the messaging app to access the calendar app’s API without user redirection or consent while following enterprise access policies. + +## How it works + +The XAA flow involves the following actors: + +- Requesting App: The application or AI agent that needs to access a resource. +- Resource App: The application that owns the protected resource and exposes it via an API +- Enterprise IdP: The IdP, such as Okta, that authenticates employees. + +After the end-user authenticates with the enterprise IdP, the Requesting App contacts the enterprise IdP to request access to the Resource App on the user's behalf. After applying its access policy to check if this cross-app connection is permitted, the enterprise IdP generates an assertion called an ID-JAG, which the Requesting App then presents to the Resource App to get an access token for API consumption.  + +In the following diagram, Acme is the enterprise customer whose employees authenticate with their enterprise IdP, such as Okta, to access the Requesting App (Agent0) and the Resource App (Todo0): + +![](/docs/images/xaa/xaa_high_level_diagram.png) + +- The Resource App (Todo0) Authorization Server is federated with the enterprise IdP through OIDC so that it can generate access tokens for end-users authenticated by that IdP. +- The Requesting App (Agent0) is registered with the Resource App Authorization Server as an OAuth 2.0 client with a valid client_id and credentials to request access tokens from the Resource App Authorization Server. +- The Acme IT admin has defined XAA access controls between Agent0 and Todo0. + +## End-to-end XAA flow + +With our Acme example in mind, the end-to-end XAA flow has the following steps: + +1. The Acme employee logs into the Requesting App (Agent0) using SSO with the enterprise IdP. The Requesting App obtains an ID token to verify the Acme employee’s identity. +2. The Requesting App makes a token exchange request to the IdP to exchange the ID token for a cross-domain Identity Assertion JWT Authorization Grant, also known as ID-JAG. The IdP validates the request and checks the XAA policy defined by the Acme IT Admin. +3. If the XAA policy allows for it, the IdP returns the ID-JAG to the Requesting App. +4. The Requesting App makes a token request using the ID-JAG to the Resource App (Todo0) Authorization Server. +5. The Resource App Authorization Server validates the ID-JAG using the public key it also uses for its OpenID Connect flow with the IdP. If valid, the authorization server returns an access token. +6. The Requesting App makes a request with the access token to the Resource App’s API. + +Leveraging the XAA flow, Acme’s IT admin policies govern access from Agent0 to Todo0, requiring no end-user redirection or interaction. + +## Beta limitations + +XAA Beta has the following limitations: + +- The Requesting App must be a confidential client and a first-party app in your Auth0 tenant. Public clients, such as SPAs and Native Apps, are not supported. +- Delegated administration is not supported. The enterprise customer cannot directly configure SSO connections on your Auth0 tenant. [Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-enterprise-configuration) support is planned for a later release. +- There can only be one XAA-enabled connection per upstream IdP issuer. The same Okta tenant can’t be used for more than one XAA-enabled enterprise connection. +- Organization support is limited: + - A connection has a 1:1 assignment with an Organization. Multiple Organizations cannot map to the same connection for XAA access. + - When the Requesting App is configured to require the use of Organizations, users must already be members of the target organization. +- If the `resource` parameter is not specified in the ID-JAG request, the target API is determined by the `tenant.default_audience`. +- No dynamic user creation: The user must have previously logged into your Resource App using the configured Okta connection. Otherwise, the request to exchange the ID-JAG assertion for an access token will fail with a `User not found error`. + +## Rate limits + +In XAA Beta, ID-JAG exchanges on the `/token` endpoint of your Auth0 tenant will be rate-limited to 5 RPS. diff --git a/main/docs/ai-agents-mcp/xaa/manage-xaa-in-okta.mdx b/main/docs/ai-agents-mcp/xaa/manage-xaa-in-okta.mdx new file mode 100644 index 0000000000..8f7d69b097 --- /dev/null +++ b/main/docs/ai-agents-mcp/xaa/manage-xaa-in-okta.mdx @@ -0,0 +1,27 @@ +--- +description: Learn how to manage XAA flows in the Okta Admin Console. +sidebarTitle: Manage XAA in Okta +title: Manage Cross App Access (XAA) in Okta +--- + +import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx" + + + +Once you've finished setting up your end-to-end test environment, you can manage how valid XAA applications can connect to each other in the Okta Admin Console. + +![](/docs/images/xaa/manage_xaa_in_okta.png) + +In the Okta Admin Console: + +1. Navigate to **Applications > Applications** and select your Resource App (e.g. Todo0). +2. Under the **Manage Connections** tab, add: + - Requesting Apps: applications that can connect to your SaaS application + - Resource Apps: applications your SaaS application can connect to + +For the end-to-end test environment, add Agent0, or the application you want to use for testing, as an authorized Requesting App. diff --git a/main/docs/ai-agents-mcp/xaa/set-up-xaa-test-environment.mdx b/main/docs/ai-agents-mcp/xaa/set-up-xaa-test-environment.mdx new file mode 100644 index 0000000000..fd5e00b9b0 --- /dev/null +++ b/main/docs/ai-agents-mcp/xaa/set-up-xaa-test-environment.mdx @@ -0,0 +1,216 @@ +--- +description: Learn how to set up the end-to-end test environment for the Resource App. +sidebarTitle: Set up XAA Test Environment +title: Set up Test Environment for Cross App Access (XAA) +--- + +import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx" + + + +This section explains how to set up the end-to-end test environment for the Resource App. By configuring your Auth0 tenant as the Resource App Authorization Server, your SaaS application can start accepting incoming ID-JAG requests without requiring any code changes. This enables your SaaS API to generate access tokens in response to these requests, allowing AI agents and other applications to seamlessly consume your API. + + + +This guide assumes you use Okta as your enterprise identity provider (IdP) and have administrative access to an Okta tenant you can use for testing. If you don’t have one, read [Create and configure your Okta tenant](#create-and-configure-your-okta-tenant). + + + +To set up your end-to-end test environment for the Resource App: + +- Configure and register your Resource App: This includes configuring your Auth0 tenant and registering your SaaS application as a Resource App with Okta. To learn more, read [Resource App setup](#resource-app-setup). +- Configure the Requesting App to test the end-to-end: This includes registering a test Requesting App in your Auth0 tenant and updating Okta to link it with your Resource App. To learn more, read [Requesting App setup](#requesting-app-setup). +- Configure how your Auth0 tenant federates with your customer’s enterprise IdP: In our test environment, the enterprise IdP will be your Okta test tenant, representing one of your enterprise customers. To learn more, read [Federate with the enterprise IdP and Organization configuration](#federate-with-the-enterprise-idp-and-organization-configuration). +- Manage Cross App Access in Okta: Configure agent-to-app and app-to-app connections in the Okta Admin Console. To learn more, read [Manage Cross App Access in Okta](/docs/secure/call-apis-on-users-behalf/xaa/manage-xaa-in-okta). + +The following image maps the responsibilities of the different personas in a production-ready XAA flow: + +![](/docs/images/xaa/xaa_persona_responsibilities.png) + +## Create and configure your Okta tenant + +To set up your end-to-end test environment for the Resource App, you need to create and configure your Okta tenant for Cross App Access. + +- On the [Okta Developer website](https://developer.okta.com/signup/), sign up for an Okta Integrator Free Plan. Once you sign up, you should be redirected to your new Okta tenant. +- In the Okta Admin Console, navigate to **Settings > Features**. Under Early access features, enable **Cross App Access**. + +![](/docs/images/xaa/okta_enable_xaa.png) + +## Resource App setup + +To set up your Resource App, you need to: + +- [Create the API in Auth0](#create-the-api-in-auth0) +- [Create the Resource App in Auth0](#create-the-resource-app-in-auth0) +- [Register the Resource App in Okta](#register-the-resource-app-in-okta) + +### Create the API in Auth0 + + + +If you have already created a custom API in your Auth0 tenant, you can skip this section. + + + +In the Auth0 Dashboard, [register a custom API](/docs/get-started/auth0-overview/set-up-apis) representing your SaaS API in your Auth0 tenant. + +![](/docs/images/xaa/xaa_register_api.png) + +After you’ve created the API, you can optionally set its audience as the **Default Audience** for your Auth0 tenant under [Tenant Settings](/docs/get-started/tenant-settings). + +You can also use [API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications) to granularly control which applications are granted access to your API for which scopes. + +### Create the Resource App in Auth0 + + + +If your Auth0 tenant already has one or several applications ready to log into your SaaS application, you can skip this section. + + + +In the Auth0 Dashboard, [create an application](/docs/get-started/auth0-overview/create-applications), such as a regular web app, SPA, or native app, that serves as the primary interface for end-users to access your SaaS application functionality. + +### Register the Resource App in Okta + +You must register your SaaS application in the Okta Integration Network (OIN) for it to be considered a valid Resource App. + +To register your SaaS application as a Resource App in Okta, you have two options: + +- For a quick test setup, we recommend using the Todo0 application that is already registered in the OIN. In the Okta Admin Console, go to **Applications > Applications > Browse App Catalog** and search for `Todo0`. Select it and add the integration. + +![](/docs/images/xaa/xaa_browse_todo0_in_oin.png) + +- You can also request the registration of a new application in the OIN from your Okta tenant. To learn more, read the [Submission process for SSO and SCIM integrations](https://developer.okta.com/docs/guides/submit-app-overview/#submission-process-for-sso-and-scim-integrations). To accelerate the registration process, contact your Auth0 or Okta representative. + + + +In a production environment, your enterprise customers will install your SaaS application from the OIN catalog during their IdP setup. + + + +Additionally, you must provide Okta with the issuer URL of your Auth0 tenant, which is associated with your Resource App. Requesting Apps use the issuer URL to request connecting to your Resource App. To learn more, read [Test the end-to-end XAA flow](/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow). + +## Requesting App setup + + + +In a production environment, you configure each Requesting App once to enable its connection with your Resource App. + + + +To set up your Requesting App, you need to: + +- [Create the Requesting App in Auth0](#create-the-requesting-app-in-auth0) +- [Register the Requesting App in Okta](#register-the-requesting-app-in-okta) + +### Create the Requesting App in Auth0 + +To test the end-to-end environment, create and register an application that behaves as the Requesting App. The application should be a confidential client that can store client secrets, such as a web application. + +To [create an application](/docs/get-started/auth0-overview/create-applications) representing the Requesting App in your Auth0 tenant: + +- Navigate to **Applications > Applications** and select **Create Application**. +- Enter a name and select **Regular Web Application**. + +![](/docs/images/xaa/xaa_create_regular_web_app.png) + +- Once you’ve created the application, scroll to **Settings** and enable the **Cross App Access** toggle. + +![](/docs/images/xaa/allow_xaa_auth0_app.png) + +Once you’ve created and configured your application, you must provide Okta with the application’s `client_id` and the issuer URL of your Auth0 tenant. This enables the connection between the Requesting App, identified by the `client_id`, and the Resource App, identified by the issuer URL. To learn more, read [Test the end-to-end XAA flow](/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow). + +### Register the Requesting App in Okta + + + +In a production environment, the Requesting App developer registers the Requesting App in the Okta Integration Network (OIN). Enterprise customers will install the Requesting App from the OIN catalog during their IdP setup. + + + +You must register the application in the Okta Integration Network (OIN) for it to be considered a valid XAA Requesting App when using Okta as the enterprise IdP. + +To register the Requesting App in Okta, you have two options: + +- For a quick test setup, we recommend using the Agent0 application that is already registered in the OIN. In the Okta Admin Console, go to **Applications > Applications > Browse App Catalog** and search for `Agent0`. Select it and add the integration. + +![](/docs/images/xaa/xaa_select_agent0_in_oin.png) + +- You can also request the registration of a new application in the OIN. To learn more, read the [Submission process for SSO and SCIM integrations](https://developer.okta.com/docs/guides/submit-app-overview/#submission-process-for-sso-and-scim-integrations). To accelerate the registration process, contact your Auth0 or Okta representative. + +Since the Requesting App authenticates enterprise employees with Okta, you need to configure the application’s [sign-on policy](https://help.okta.com/en-us/content/topics/security/policies/policies-home.htm) in Okta. + +1. Go to **Applications > Applications** and select the application (e.g. Agent0). +2. Under **Sign On**, select **Edit** and add the Requesting App’s callback URL in the **Redirect URI** field. Adjust the Redirect URI’s value depending on the testing application you want to use. To learn more, read [Test the end-to-end XAA flow](/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow). +3. Select **Save**. + +![](/docs/images/xaa/agent0_sign_on_policy.png) + +Finally, allow your test user to log into the Requesting App in Okta. + +In the Okta Admin Console: + +1. Navigate to **Applications** and select the application (e.g. Agent0). +2. Select **Assign > Assign to People** and select your test user. +3. Select **Save**. + +## Federate with the enterprise IdP and Organization configuration + + + +In a production environment, you configure each of your enterprise customers once to federate it with your Auth0 tenant. Auth0 will add support for [Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-enterprise-configuration) in later versions, enabling you to delegate XAA configuration to your enterprise customers as part of SSO setup. + + + +You must federate your Auth0 tenant, acting as the authorization server for your Resource App, with your enterprise customer's Okta tenant. This federation establishes cryptographic trust, allowing your application to validate and accept signed assertions (ID-JAGs) issued by the customer's IdP. + +To test the end-to-end XAA flow for multiple enterprise customers connected to your Resource App, you can repeat the steps in this section for multiple Okta Workforce Enterprise connections in your Auth0 tenant. Each connection maps to a different Okta test tenant, where each tenant represents a different enterprise customer. + +### Configure an Okta Workforce Enterprise connection + +Use your Resource App’s `client_id` and `client_secret` to [create an Okta Workforce Enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) in your Auth0 tenant. + +When creating the Okta Workforce Enterprise connection, activate the **Cross App Access - Resource Application** role. This enables your Resource App to accept ID-JAGs issued by the enterprise IdP associated with that connection, in this case, your Okta tenant. + +![](/docs/images/xaa/xaa_new_okta_workforce_connection.png) + +After creating the Okta Workforce Enterprise connection, copy the callback URL provided by Auth0 in the connection's settings. You need the callback URL to configure the sign-on policies of the Resource App in your Okta tenant. + +In the Okta Admin Console: + +1. Navigate to **Applications > Applications** and select the application (e.g. Todo0). +2. Under **Sign On** settings, select **Edit** and add the callback URL in the **Redirect URI** field. +3. Select **Save**. + +![](/docs/images/xaa/xaa_advanced_sign_on_settings.png) + +To test the Okta Workforce Enterprise connection, create a test user and give it permission to log into the Requesting App. + +In the Okta Admin Console: + +- Navigate to **Applications** and select the application (e.g. Agent0). +- Select **Assign > Assign to People** and select your test user. +- Select **Save**. + +In the Auth0 Dashboard: + +- Navigate to **Authentication > Enterprise > Okta Workforce**: + - Enter the Okta Workforce Enterprise connection you created and select the **Applications** tab. Then, enable the Requesting App you created for the connection. + - Go back to the list of Okta Workforce connections. Select the three dots on the right for your connection and select **Try**. You will be redirected to authenticate in your Okta tenant to complete the login with your test user. + +![](/docs/images/xaa/xaa_create_okta_workforce_connection.png) + +### Configure an Organization + +Optionally, if you want an enterprise customer to use Organizations, [create an Organization](/docs/manage-users/organizations/configure-organizations/create-organizations) and [enable the Okta Workforce Enterprise connection](/docs/manage-users/organizations/configure-organizations/enable-connections) for that Organization. This automatically associates access tokens generated using XAA, in the scope of this connection, to the corresponding `org_id` if the target user is a member of the Organization. + +![](/docs/images/xaa/xaa_enable_connection.png) + +You can also configure the Requesting App’s [Organization behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior) to set whether it is required or allowed to use Organizations. We recommend that you start testing with **Both**, which allows users to log in as an Organization member or sign up with a personal account. + +![](/docs/images/xaa/xaa_organizations_both.png) diff --git a/main/docs/ai-agents-mcp/xaa/test-xaa-flow.mdx b/main/docs/ai-agents-mcp/xaa/test-xaa-flow.mdx new file mode 100644 index 0000000000..8aae2b4031 --- /dev/null +++ b/main/docs/ai-agents-mcp/xaa/test-xaa-flow.mdx @@ -0,0 +1,94 @@ +--- +description: Learn how to test the end-to-end XAA flow. +sidebarTitle: Test XAA Flow +title: Test Cross App Access (XAA) Flow +--- + +import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx" + + + +To test the end-to-end XAA flow, you need to verify that your Auth0 tenant can accept the JWT-Bearer requests sent by the Requesting App. Auth0 handles that for you out of the box. + +Before you can test the end-to-end XAA flow, make sure you: + +- Update the **Redirect URI** field to the callback URL of your testing application that acts as your Requesting App in your Okta tenant, as explained in [Register the Requesting App in Okta](/docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment#register-the-requesting-app-in-okta). +- Provide your Okta representative with the following information: + - The issuer URL of your Auth0 tenant. Your Resource App is associated with the issuer URL in the Okta Integration Network (OIN), enabling Requesting Apps to refer to it when requesting ID-JAGs. + - The Auth0 `client_id` that maps to each Requesting App in the OIN. + +To get the issuer URL and the client ID within your Auth0 tenant, navigate to **Applications**, select your application, and select **Settings**: + +| __Field__ | __Instructions__ | __Example__ | +|-----------|-----------------|-------------| +| Issuer URL | Copy your Auth0 domain, prefix it with `https://`, and add a trailing slash. | `https://tenant.region.auth0.com/` or if your customers are using a custom domain, `https://custom-domain.com/`. +| `client_id` | Copy the application's client ID. | `ovBLQycaVq6I0Xyuhq84pwDVyJeXWLyx` | + + +### Exchange the ID token for an ID-JAG + +First, you need to log in to your Requesting App with your Okta test tenant. When you successfully log in and grant consent, Okta redirects the browser back to your Requesting App with an authorization code. Your Requesting App then securely exchanges the authorization code for an Okta access token and ID token. + +To exchange the Okta ID token for an ID-JAG, the Requesting App makes a [token exchange request](https://www.ietf.org/archive/id/draft-parecki-oauth-identity-assertion-authz-grant-05.html#name-token-exchange) to the `/token` endpoint of your Okta test tenant with the following parameters: + +``` +POST /oauth2/v1/token HTTP/1.1 +Host: {{YOUR_TENANT}}.okta.com +Content-Type: application/x-www-form-urlencoded + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&requested_token_type=urn:ietf:params:oauth:token-type:id-jag +&audience={{YOUR_AUTH0_TENANT_ISSUER_URL}} +&resource={{YOUR_AUTH0_TENANT_API_AUDIENCE}} +&subject_token={{OKTA_ID_TOKEN}} +&subject_token_type=urn:ietf:params:oauth:token-type:id_token +&client_id={{REQUESTING_APP_CLIENT_ID_IN_OKTA}} +&client_secret={{REQUESTING_APP_CLIENT_SECRET_IN_OKTA}} +``` + +| __Parameter__ | __Description__ | +|---------------|-----------------| +| `grant_type` | The grant type. Set to the token exchange grant type: `urn:ietf:params:oauth:grant-type:token-exchange`. | +| `requested_token_type` | The type of token the client wants to receive back from the authorization server. Set to the Identity Assertion Authorization Grant, or ID-JAG: `urn:ietf:params:oauth:token-type:id-jag`. | +| `audience` | The intended recipient of the final token. Set to your Auth0 tenant issuer URL, or your Resource App whose authorization server is located at that specific URL. | +| `resource` | Optional. The Resource App's API that the client wants to access. When the authorization server issues the final access token, it includes this resource in the token's `aud` claim, which the Resource App's API will use for validation. If you don’t specify a `resource` parameter, the default audience you set for your tenant is used in the next request to get an access token. If you specify a `resource` that does not match a valid API audience in your Auth0 tenant, the token exchange request does not fail and you still receive an ID-JAG in return. However, the subsequent request to get an access token with the ID-JAG will be rejected by your Auth0 tenant. | +| `subject_token` | The token the client is exchanging. For XAA, the subject token is the “proof” or “assertion” of the user’s identity. Set to the Okta ID token that the IdP will use to verify the user’s identity. | +| `subject_token_type` | The type of token provided in the `subject_token` parameter. For XAA, it specifies that an ID token is being presented to the authorization server. | +| `client_id` | The client ID of the Requesting App within the enterprise IdP that is making the token exchange request. | +| `client_secret` | The client secret that that Requesting App uses to authenticate itself with the enterprise IdP. | + +XAA Beta does not support passing scopes to Okta’s `/token` endpoint. You can set the scopes in the next request to Auth0’s /token endpoint once the Requesting App receives the ID-JAG. + +In a production environment, the Requesting App makes the token exchange request to the `/token` endpoint of your customer’s Okta tenant. + +### Send ID-JAG to Auth0's /token endpoint + +Once the Requesting App gets an ID-JAG, it sends an [access token request](https://www.ietf.org/archive/id/draft-parecki-oauth-identity-assertion-authz-grant-05.html#name-access-token-request) to the `/token` endpoint of your Auth0 tenant: + +``` +POST https://{{YOUR_AUTH0_TENANT_DOMAIN}}/oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer +&client_id={{REQUESTING_APP_CLIENT_ID_IN_AUTH0}} +&client_secret={{REQUESTING_APP_CLIENT_SECRET_IN_AUTH0}} +&scope=scope1%20scope2%20 +&assertion={{ID_JAG}} +``` + +| __Parameter__ | __Description__ | +|---------------|-----------------| +| `grant_type` | The grant type. It tells the Authorization Server to expect a JSON Web Token (JWT) as the primary credential in the request. | +| `client_id` | The client ID of the Requesting App within the Resource App Authorization Server making the API call. | +| `client_secret` | The client secret of the Requesting App within the Resource App Authorization Server making the API call. | +| `scope` | The set of permissions the Requesting App is requesting for the access token. | +| `assertion` | The ID-JAG or JSON Web Token (JWT) that acts as the bearer of the identity assertion. | + +After the Auth0 Authorization Server validates the ID-JAG to verify the user’s identity, it issues an access token to consume the target API audience of your Auth0 tenant. The access token also includes the scopes you requested that are allowed by RBAC and other policies set in your Auth0 tenant. + +The Auth0 Authorization Server does not issue refresh tokens in response to ID-JAG token exchanges. As a result, the Requesting App needs to get a new ID-JAG from the enterprise IdP, and undergo the applicable access controls, to get a new access token via XAA.