Skip to main content
Beta: This requires the Agents beta. Test with one Agent, one person and a harmless tool, following Connect an Agent with Okta, before giving an Agent access for more people.
An Agent signs a person in at Okta and sends Conduit that person’s Okta user access token. Conduit verifies the token itself, works out which Agent sent it and which person it acts for, and runs only the tools both may use. Okta issues and renews the tokens; Conduit keeps none of them. An Agent’s request runs only while all of these hold:
  • External agent access is on for the instance.
  • The person’s Okta or Custom OIDC sign-in provider is enabled, and its Agent access is on.
  • The Agent is switched on, and its Okta app is approved for it.
  • The person is in the workspace and has signed in to Conduit through that provider, in a way the workspace’s sign-in settings accept.
  • The Agent’s Delegation includes the person.
  • The tool is allowed both for the person and by the Agent’s groups.

Who approves

Approving trusts a set of Okta tokens to act for people, so it takes a workspace owner: turning on, creating or changing a provider’s Agent access, and approving an Agent’s Okta app. Every workspace admin can switch a provider’s Agent access off without other changes and remove an Agent’s app, so stopping access never waits for an owner. Admins also create Agents, switch them on and off, and choose their groups and Delegation. An instance provider is the instance’s to vouch for: Agent access through one, and the apps of Agents using it, are approved by an instance administrator, and only in a workspace that accepts that provider for sign-in. Instance administrators can approve in every workspace. An instance administrator also controls External agent access, at the top of Agents. It’s off by default. Turning it off pauses every Agent in every workspace and keeps their configuration. Upgrade every replica to the current release before turning it on.

Turn on Agent access for a sign-in provider

As a workspace owner, open Settings → Sign-in, find your Okta or Custom OIDC provider, and choose Agent access from its menu.
  1. Turn on Allow Agent access with this provider.
  2. Conduit uses the provider’s own issuer when it is an Okta custom authorization server (https://company.okta.com/oauth2/<server-id>). Otherwise, turn on Use a different Okta authorization server and enter the Access-token issuer: a custom authorization server on the same Okta domain as the provider.
  3. Select Save. Reopen Agent access and select Check signing keys to confirm Conduit can fetch the issuer’s keys.
  4. Check the claims in Okta before you rely on it.
The dialog shows the Access-token audience, the MCP server URL and the Required scope; give them to the Agent’s developer. Conduit fetches signing keys from the issuer’s /v1/keys endpoint. Each issuer serves one provider’s Agent access in a workspace. Browser sign-in keeps its own client, redirect URI and scopes, and each Agent signs people in with its own Okta app. The provider’s row on Sign-in reads Agent access enabled, Agent access paused or Agent access needs review.

How Conduit finds the person

Okta puts the person’s Okta user ID (it normally begins with 00u) in a different claim in each token. An Agent’s access token carries it as uid; its sub is the person’s Okta username, often an email address, which can change. The ID token of their Conduit sign-in carries it as sub. Conduit matches the access token’s uid with the sub of the person’s sign-in through the provider, so there is nothing to configure, and an email never identifies anyone.

Check the claims in Okta

  1. In the Okta Admin Console, open Security → API → Authorization Servers. Select the server used by Conduit’s browser sign-in and open Token Preview.
  2. Select the Conduit browser application, Authorization Code, a test person, and the scopes openid email profile. Preview the ID token and note its sub.
  3. Open Token Preview on the Agent’s authorization server. Select the Agent application, the same person and grant, and the scopes openid conduit:connectors. Preview the access token and note uid.
  4. Check that both values are the person’s Okta user ID: find the person under Directory → People, where the profile URL contains it (it normally begins with 00u). Repeat with a second person; each pair matches, and the two people’s IDs differ.
Compare the Conduit browser app’s ID token with the Agent app’s access token: they are separate applications. If browser sign-in uses Okta’s org authorization server, which Token Preview doesn’t cover, inspect a real browser ID token with your usual OIDC diagnostics. Okta’s Token Preview guide shows the controls, and its token reference defines uid. A preview checks configuration; a real sign-in and a permitted tool call test the integration.

Approve the Agent’s Okta app

On the Agent’s page in Agents, a workspace owner selects Configure authentication under Authentication, chooses the Sign-in provider and enters the Agent OAuth client ID of the Agent’s Okta app. Each Agent has one Okta app, and an app identifies one Agent in a workspace. To move an Agent to another provider, remove its app and approve it again there. Then set the Agent’s Tool access and Delegation and switch it on.

The people an Agent acts for

An Agent acts for someone through the Conduit account they signed in to through the provider. Conduit matches the token’s uid with that sign-in, so each person signs in to Conduit through the provider at least once. This uses their existing account for that provider, including a SCIM-provisioned account once sign-in establishes its identity. A password-only account, including one created by accepting an invite, stays separate even if its email matches. Tools and connected accounts on that separate account do not carry over. The Agent uses the tools and accounts on the account signed in through the provider. The workspace’s sign-in settings apply as if the person signed in directly:
  • The workspace must accept sign-in through the provider. When it accepts an instance provider only for its own domains, the person’s verified email must be in one of them. Owners are exempt, as when they sign in themselves.
  • When the workspace asks people to sign in again after a set time, the token’s auth_time must fall within it. Okta keeps the original auth_time when it refreshes a token, so once that time passes the person signs in at Okta again and the Agent uses the new token.

Send the access token

The Agent’s backend gets user access tokens with Authorization Code with PKCE, requesting openid conduit:connectors, and sends each request to the workspace’s MCP server URL:
Conduit accepts a token with:
  • an RS256 signature from the approved issuer’s keys;
  • exactly one audience, the access-token audience;
  • the scope conduit:connectors;
  • the person’s uid and the approved Agent app’s cid;
  • integer iat and exp, at most 15 minutes apart.
ID tokens, Client Credentials tokens, tokens from Okta’s org authorization server and tokens for other APIs are refused, as is any token carrying an act, may_act or cnf claim. A token sent to /mcp itself gets 400 invalid_request naming the workspace URL to use. The Agent’s client secret and refresh tokens stay in its backend.

What an Agent can use

An Agent lists and calls remote tools, including through Conduit’s list_available_tools, describe_tools and call_tool. Prompts, resources, MCP Apps, local tools, Conduit’s administration tools, sampling and elicitation are for people’s own assistants; for an Agent, prompt and resource lists are empty and the rest is refused. Agents are managed on Agents: the MCP Clients page and its client rules cover people’s assistants.

Pause and stop access

Switching off a provider’s Agent access, the provider itself, an Agent or External agent access is enforced before a tool result is delivered; an idle stream can take up to five seconds to end. A request whose response hasn’t started gets 403, and an open stream ends. New requests get 403, or 401 while External agent access is off, when Conduit accepts no Agent tokens. Switching it back on accepts tokens that haven’t expired yet. Tool and permission changes apply within five seconds. A side effect an upstream app already accepted can’t be undone. To stop an Agent acting for one person, remove them, or their group, from its Delegation. Editing a provider’s issuer or client ID marks its Agent access needs review and pauses it until an owner opens Agent access and saves it again; each person then signs in through the provider once more. Deleting a provider deletes its Agent access and the Okta apps approved through it. Open streams are rechecked every five seconds and end when the token expires; the Agent reconnects with a fresh token. Each Agent holds at most eight open streams for one person on each Conduit server; beyond that, a new stream gets 429 with Retry-After.

Security limits

  • Okta revocation reaches Conduit at expiry. Conduit verifies tokens itself, so a token revoked at Okta (by logout, revocation or a policy change) works until it expires. Keep lifetimes short; Conduit refuses lifetimes over 15 minutes.
  • A removed signing key can verify for up to 5 minutes. After removing a compromised key at Okta, select Check signing keys in the provider’s Agent access: every Conduit server drops its cached keys at once.
  • Tokens are bearer tokens. They aren’t sender-constrained (RFC 9700 §2.2.1): anyone holding one can use it until it expires. Keep tokens in the Agent’s backend, out of browsers and logs.
  • A token works in every workspace that approved its app. Its audience is the instance’s MCP address, so any workspace on the same instance that approved the same Okta app through the same issuer accepts it for the same person. Each workspace approves an app separately, so nobody can extend an Agent to another workspace alone. Give each Agent its own Okta app in each workspace.
The audit log records each change to Agent access and each tool call an Agent runs, naming the Agent and the person and never the tool’s arguments or results. A refused call is recorded as a policy denial naming the Agent. Calls whose results are withheld after cancellation, expiry or an access change are recorded as failures. The connected service may still have made changes before the call ended.

Troubleshooting