- 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.- Turn on Allow Agent access with this provider.
- 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. - Select Save. Reopen Agent access and select Check signing keys to confirm Conduit can fetch the issuer’s keys.
- Check the claims in Okta before you rely on it.
/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 with00u) 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
- In the Okta Admin Console, open Security → API → Authorization Servers. Select the server used by Conduit’s browser sign-in and open Token Preview.
- Select the Conduit browser application, Authorization Code, a test
person, and the scopes
openid email profile. Preview the ID token and note itssub. - 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 noteuid. - 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.
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’suid 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_timemust fall within it. Okta keeps the originalauth_timewhen 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, requestingopenid conduit:connectors, and sends each request to the
workspace’s MCP server URL:
- an RS256 signature from the approved issuer’s keys;
- exactly one audience, the access-token audience;
- the scope
conduit:connectors; - the person’s
uidand the approved Agent app’scid; - integer
iatandexp, at most 15 minutes apart.
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’slist_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 withRetry-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.

