Skip to content

feat: guide human-gated clearing on Okta and other customer IdPs - #61

Open
pareilly wants to merge 3 commits into
mainfrom
docs/okta-session-clearing
Open

pareilly wants to merge 3 commits into
mainfrom
docs/okta-session-clearing

Conversation

@pareilly

@pareilly pareilly commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

What

The dtwo-gateway-config skill gets guidance for arming human-gated clearing on a gateway that authenticates against the customer's own IdP:

  • Okta clearing app: a Native OIDC app with an Okta-generated client ID (not a Client ID Metadata Document), included in the custom authorization server's access policy, alongside the apps the MCP clients sign in with.
  • Redirect URI: <gateway origin>/session-control/clear/callback, or the session_control.redirect_uri value, and when that override is required.
  • Intent capture: intent clears need gateway.intent.enabled: true; without it set_intent stores nothing.
  • Identity claim: the gateway detects Entra ID and Okta from the issuer host. For an Okta custom domain or a sovereign-cloud Entra ID issuer, set SESSION_SUBJECT_PROVIDER in gateway.advanced.

The vendored schema-reference.json is re-copied from the product's schema generator, picking up the updated session_control.client_id guidance. The digest is regenerated and the pinned artifact hash bumped. Only that one rationale string changed, so no safe-default seed moved.

The plugin version goes to 1.3.5 in all three manifests.

Merge timing

This describes gateway behaviour in the next gateway release. Keep it as a draft until that release is out.

Checks

  • node scripts/generate-schema-digest.mjs --check passes.
  • skill-harness: pnpm test (183 pass), biome:check and typecheck are clean.
  • node scripts/build-openai-plugin.mjs --check passes.

Gateways now bind human-gated clears on the claim that identifies the
same person in both tokens, detected from the issuer host: Entra ID and
Okta are recognised, and SESSION_SUBJECT_PROVIDER in `gateway.advanced`
covers an Okta custom domain or a sovereign-cloud Entra ID issuer.

The gateway-config skill now tells users how to set up the clearing app
on Okta (Native app, Okta-generated client ID, in the authorization
server's access policy), which redirect URI to register, that intent
clears need intent capture, and when to set the provider. The vendored
schema reference picks up the matching `session_control.client_id`
guidance; the digest is regenerated and its pinned hash bumped. Only
that rationale string changed, so no safe-default seed moved.

Bumps the plugin to 1.3.5.
@pareilly

pareilly commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Ready for review, but shouldn't merge yet. This needs to wait until after the production deploy that includes the updated gateway version, since the guidance describes behaviour that ships in that release.

The schema reference was re-copied for the session_control.client_id guidance; the validator bundle is built from the same schema, so it is re-vendored from the same source revision and its pinned hash bumped. Only that rationale string differs.
The identity-claim note and the vendored client_id guidance now lead with the default: Entra ID and Okta are detected and every other issuer, Auth0 included, is standard OIDC. The setting is only for an Okta custom domain or a sovereign-cloud Entra ID issuer. Schema and validator bundle are re-vendored from the same source revision and their pins bumped.
@pareilly
pareilly marked this pull request as ready for review November 5, 2026 20:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant