diff --git a/hugo/content/en/account_management/org_settings/cross_app_access.md b/hugo/content/en/account_management/org_settings/cross_app_access.md index 5e694ff8861a..08cb93975689 100644 --- a/hugo/content/en/account_management/org_settings/cross_app_access.md +++ b/hugo/content/en/account_management/org_settings/cross_app_access.md @@ -27,19 +27,20 @@ In Preview, Cross-App Access supports Okta as the only identity provider and Cla Setup moves values in both directions between Datadog and Okta. Two of them are issuer URLs that name different systems, so confirm you enter each one in the correct place. -| Value | Direction | Where you enter it | -| ----------------------------------- | --------------- | ----------------------------------------------------------------------------------------- | -| Datadog organization UUID | Datadog to Okta | Datadog application in Okta: {{< ui >}}Resource Server{{< /ui >}} tab > {{< ui >}}Audience/tenant ID{{< /ui >}} | -| Agent client ID | Datadog to Okta | Okta AI Agent: {{< ui >}}Resource Connection{{< /ui >}} > {{< ui >}}Client ID at resource{{< /ui >}} | -| Datadog resource URL and issuer URL | Datadog to Okta | Datadog application in Okta: {{< ui >}}Resource Server{{< /ui >}} tab > {{< ui >}}Resource URL{{< /ui >}} and {{< ui >}}Issuer URL{{< /ui >}} | -| Okta tenant issuer URL | Okta to Datadog | Datadog: {{< ui >}}Organization Settings > Cross-App Access{{< /ui >}}, {{< ui >}}Issuer URL{{< /ui >}} | +| Value | Direction | Where you enter it | +| ------------------------- | --------------- | ------------------ | +| Datadog organization UUID | Datadog to Okta | Datadog application in Okta: {{< ui >}}Machine Assignments{{< /ui >}} > {{< ui >}}Callers{{< /ui >}} > {{< ui >}}Cross App Access (XAA){{< /ui >}} > {{< ui >}}Audience/tenant ID{{< /ui >}} | +| Datadog issuer URL | Datadog to Okta | Datadog application in Okta: {{< ui >}}Machine Assignments{{< /ui >}} > {{< ui >}}Callers{{< /ui >}} > {{< ui >}}Cross App Access (XAA){{< /ui >}} > {{< ui >}}Issuer URL{{< /ui >}}. The Datadog application from the Okta Integration Network fills this in. | +| Datadog resource URL | Datadog to Okta | Claude AI agent in Okta: {{< ui >}}Resource connections{{< /ui >}} > {{< ui >}}Resource indicator{{< /ui >}} | +| Agent client ID | Datadog to Okta | Claude AI agent in Okta: {{< ui >}}Resource connections{{< /ui >}} > {{< ui >}}AI agent's client ID registered in this app{{< /ui >}} | +| Okta issuer URL | Okta to Datadog | Datadog: {{< ui >}}Organization Settings > Cross-App Access{{< /ui >}}, {{< ui >}}Issuer URL{{< /ui >}} | ## Prerequisites - Your organization uses Okta for SAML single sign-on to Datadog. Cross-App Access resolves users through your existing SAML connection, so it does not work without one. See [Configure SAML single sign-on](/account_management/saml/). -- Each user who uses Claude exists in your Datadog organization and is assigned to both the Claude application and the Datadog application in Okta. +- Each user who uses Claude exists in your Datadog organization and, in Okta, is assigned to both the Claude AI agent and the Datadog application. - You have the `org_management` permission in Datadog. To configure Cross-App Access through the API instead of the UI, you also need a [Personal Access Token](/account_management/personal-access-tokens/) (PAT), used as `DD_TOKEN` in the examples. -- Your Okta tenant has the {{< ui >}}AI Agent Identity Assertion{{< /ui >}} and {{< ui >}}Agent to Agent Connections{{< /ui >}} features enabled, and you have Okta Super Administrator access. +- Your Okta org runs Okta Identity Engine and subscribes to Single Sign-On, and you have Okta Super Administrator access. Under Single Sign-On, Okta limits Cross App Access to 250 ID-JAG tokens per user, per resource application, per month. See [Okta's Cross App Access documentation](https://help.okta.com/oie/en-us/content/topics/apps/apps-config-xaa-connection.htm) for the current limits. ## Configure Cross-App Access in Datadog @@ -64,13 +65,15 @@ The issuer URL must meet all of the following, or Datadog rejects it: Click {{< ui >}}Remove{{< /ui >}} to unset the issuer. Datadog stops accepting tokens after you remove it. +Enter your Okta org URL, such as `https://example.okta.com`. Okta issues ID-JAGs from its org authorization server, so the URL of a custom authorization server, such as `https://example.okta.com/oauth2/default`, does not work. Datadog accepts only Okta domains, so a custom URL domain, such as `https://login.example.com`, does not work either. If your Okta org uses a custom URL domain, make sure Okta issues tokens for Claude with the Okta URL as the issuer. + ### Copy your organization UUID Copy the value in the {{< ui >}}Org UUID{{< /ui >}} field. Okta sends this value as the `aud_tenant` claim, which tells Datadog which organization a token targets when several organizations share one Okta tenant. It is not the same as the company ID that Okta asks for elsewhere. ### Copy the agent client ID -The {{< ui >}}Registered client IDs{{< /ui >}} table lists every agent Datadog supports for Cross-App Access and the OAuth client ID each one uses. Copy the client ID for the agent you are setting up. You will enter it in Okta as {{< ui >}}Client ID at resource{{< /ui >}}. +The {{< ui >}}Registered client IDs{{< /ui >}} table lists every agent Datadog supports for Cross-App Access and the OAuth client ID each one uses. Copy the client ID for the agent you are setting up. You will enter it in Okta as {{< ui >}}AI agent's client ID registered in this app{{< /ui >}}. Datadog adds agents to this table as it supports them, so check the table rather than reusing a client ID from another source. @@ -120,18 +123,23 @@ To read your organization UUID from the API, call [{{< region-param key="dd_api" Complete the setup in the Okta Admin Console as a Super Administrator. This section lists the values Datadog expects and the Okta fields they belong in. See [Okta's Cross-App Access documentation](https://help.okta.com/oie/en-us/content/topics/apps/apps-cross-app-access.htm) for more details. -### Configure the Datadog application as a resource server +### Configure the Datadog application as a resource application + +Use the Datadog application from the Okta Integration Network, the one you use for SAML single sign-on to Datadog. -On your Datadog application, open the {{< ui >}}Resource Server{{< /ui >}} tab and enable {{< ui >}}Cross-app access (XAA){{< /ui >}}. Set the following fields. +1. In the Okta Admin Console, navigate to {{< ui >}}Applications and Resources > Applications{{< /ui >}} and select your Datadog application. +2. Open the {{< ui >}}Machine Assignments{{< /ui >}} tab and select the {{< ui >}}Callers{{< /ui >}} tile. +3. Click {{< ui >}}Edit{{< /ui >}} next to {{< ui >}}Cross App Access (XAA){{< /ui >}}, then select {{< ui >}}Enable{{< /ui >}}. +4. Check the following fields, then click {{< ui >}}Save{{< /ui >}}. {{< site-region region="us,us3,us5,eu,ap1,ap2,uk1" >}}

The values below match your selected Datadog site ({{< region-param key="dd_site_name" >}}). To see the values for another site, use the {{< ui >}}Datadog Site{{< /ui >}} selector on the right side of this page.

- - + +
Okta fieldValue
{{< ui >}}Resource URL{{< /ui >}}{{< region-param key="mcp_xaa_resource_url" code="true" >}}
{{< ui >}}Issuer URL{{< /ui >}}{{< region-param key="mcp_xaa_issuer_url" code="true" >}}
{{< ui >}}Issuer URL{{< /ui >}}{{< region-param key="mcp_xaa_issuer_url" code="true" >}}. The Okta Integration Network application sets this value.
{{< ui >}}Audience/tenant ID{{< /ui >}}Your Datadog organization UUID
{{< ui >}}Scopes{{< /ui >}}The Okta Integration Network application sets these values. See Control scopes in Datadog.
{{< /site-region >}} @@ -140,39 +148,42 @@ The issuer URL identifies the Datadog authorization server, not the token endpoi **Note**: Changing the issuer URL later requires deleting and recreating the resource connection described in [Connect Claude to the Datadog application](#connect-claude-to-the-datadog-application). -### Register Claude as an AI Agent +### Register Claude as an AI agent -Create an AI Agent entry for Claude in Okta, then exchange keys with Anthropic. Anthropic signs the requests Okta receives, so Okta needs Anthropic's public key before it issues any token. +Register Claude as an AI agent in Okta, then exchange keys with Anthropic. Anthropic signs the requests Okta receives, so Okta needs Anthropic's public key before it issues any token. -1. Create the AI Agent entry for Claude. -2. Assign owners to the agent. Okta requires an owner before you can activate it. -3. Send the AI Agent ID that Okta generates to Anthropic. -4. Add the public key that Anthropic returns to the AI Agent entry, on the {{< ui >}}Credentials{{< /ui >}} tab. +1. Navigate to {{< ui >}}Directory > AI Agents{{< /ui >}} and click {{< ui >}}Register AI Agent{{< /ui >}}. +2. Under {{< ui >}}Profile{{< /ui >}}, enter a name and description, then click {{< ui >}}Next{{< /ui >}}. +3. Under {{< ui >}}User access and authentication{{< /ui >}} > {{< ui >}}Allow users to access this agent{{< /ui >}}, select {{< ui >}}Select an existing app{{< /ui >}}, select your Claude application, then click {{< ui >}}Next{{< /ui >}}. Okta does not let you change this link later without deleting and recreating the agent. +4. Assign owners to the agent. Okta requires an owner before you can activate it. +5. Send the client ID that Okta generates for the agent to Anthropic. +6. On the {{< ui >}}Client registration{{< /ui >}} tab, click {{< ui >}}Configure{{< /ui >}} next to the public/private key method, click {{< ui >}}Add public key{{< /ui >}}, and paste the public key that Anthropic returns. Then activate the method. +7. On the {{< ui >}}User access{{< /ui >}} tab, assign the users and groups who use Claude. Until the public key is in place, token exchange fails even though every other value is correct. This exchange is manual, so start it early. ### Connect Claude to the Datadog application -On the Claude AI Agent, add the Claude SAML application as a delegated caller, then connect the agent to your Datadog application. - -1. On the {{< ui >}}Delegations{{< /ui >}} tab, add the Claude SAML application as a caller. -2. On the {{< ui >}}Resource connections{{< /ui >}} tab, add a resource connection. Select {{< ui >}}Application{{< /ui >}} as the resource type, then select your Datadog application. -3. Set the following fields. +1. In {{< ui >}}Directory > AI Agents{{< /ui >}}, select the Claude agent. +2. On the {{< ui >}}Resource connections{{< /ui >}} tab, click {{< ui >}}Add resource connection{{< /ui >}}. +3. Under {{< ui >}}Application{{< /ui >}} > {{< ui >}}Application instance{{< /ui >}}, select your Datadog application, then select {{< ui >}}Enable{{< /ui >}}. +4. Set the following fields, then click {{< ui >}}Add{{< /ui >}}. - | Okta field | Value | - | ------------------------- | ---------------------------------------------------------------------------------------------------- | - | {{< ui >}}Client ID at resource{{< /ui >}} | The Claude client ID you copied from [{{< ui >}}Registered client IDs{{< /ui >}}](#copy-the-agent-client-id) | - | {{< ui >}}Scope Condition{{< /ui >}} | {{< ui >}}Allow all{{< /ui >}}, the only supported value. See [Control scopes in Datadog](#control-scopes-in-datadog) | + | Okta field | Value | + | ---------- | ----- | + | {{< ui >}}Resource indicator{{< /ui >}} | {{< region-param key="mcp_xaa_resource_url" code="true" >}} | + | {{< ui >}}AI agent's client ID registered in this app{{< /ui >}} | The Claude client ID you copied from [{{< ui >}}Registered client IDs{{< /ui >}}](#copy-the-agent-client-id) | + | {{< ui >}}Scopes{{< /ui >}} | {{< ui >}}Allow any scope{{< /ui >}}, the only supported value. See [Control scopes in Datadog](#control-scopes-in-datadog) | -4. Activate the agent from the {{< ui >}}Actions{{< /ui >}} menu. +5. Activate the agent from the {{< ui >}}Actions{{< /ui >}} menu. ## Control scopes in Datadog -{{< ui >}}Allow all{{< /ui >}} is the only supported {{< ui >}}Scope Condition{{< /ui >}} for Cross-App Access. Set it in Okta, then restrict what Claude reaches from Datadog. +{{< ui >}}Allow any scope{{< /ui >}} is the only supported {{< ui >}}Scopes{{< /ui >}} option on the resource connection for Cross-App Access. Set it in Okta, then restrict what Claude reaches from Datadog. -Okta does not filter scopes. With {{< ui >}}Allow all{{< /ui >}}, Okta copies whatever Claude requests into the token, which makes Datadog the enforcement point. +With {{< ui >}}Allow any scope{{< /ui >}}, Okta copies the scopes Claude requests into the token, which makes Datadog the enforcement point. -
Do not enter a list of scopes in Okta. Okta rejects any token request that contains a scope outside the list, so the integration fails with an error instead of falling back to narrower access.
+
Do not select {{< ui >}}Allow specific scopes{{< /ui >}} or {{< ui >}}Disallow specific scopes{{< /ui >}} in Okta. Okta rejects any token request that contains a scope outside the allowed set, so the integration fails with an error instead of falling back to narrower access.
To set the scopes Claude is allowed: @@ -195,7 +206,7 @@ Use the Datadog connector from the directory, not a custom connector. ## Verify the configuration -Sign in to Claude as a user assigned to both Okta applications, then run a request that calls Datadog. A successful call confirms the full path: Okta issues the token, Datadog accepts it, and Datadog resolves the user. +Sign in to Claude as a user assigned to both the Claude AI agent and the Datadog application in Okta, then run a request that calls Datadog. A successful call confirms the full path: Okta issues the token, Datadog accepts it, and Datadog resolves the user. If a user signed in before you enabled Cross-App Access, have them sign out of Claude and sign back in through Okta. Sessions established earlier lack the identity token the agent needs.