> ## Documentation Index
> Fetch the complete documentation index at: https://pipedream.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an Agent with Okta

> Get the values you need from Okta, enter them in Conduit, and let your Agent use approved tools for a person.

> [!WARNING]
>
> **Beta:** This requires the [Agents beta](https://pipedream.com/docs/conduit/use/agents.md). Start with one Agent,
> one test person and a harmless tool before giving the Agent access for more
> people.

Okta issues your Agent an access token for Conduit. Your Agent sends that token
to Conduit, which checks who it may act for and which tools it may use.

You need an Okta administrator and a Conduit workspace owner. Your Okta plan
must support [custom authorization servers](https://developer.okta.com/docs/concepts/auth-servers/).
People [sign in to Conduit through Okta](https://pipedream.com/docs/conduit/configure/sso.md); this guide adds
Agent access to that sign-in provider. Read the
[security limits](https://pipedream.com/docs/conduit/configure/agent-authentication.md#security-limits) first.

## 1. Copy the Conduit values

In Conduit, open **Settings → Sign-in**, find your Okta provider, and choose
**Agent access** from its menu. Copy **Access-token audience** for Okta and
**MCP server URL** for your Agent. Both are shown before you save.

For example, the audience is `https://conduit.example.com/mcp` and the MCP
server URL is `https://conduit.example.com/mcp/WORKSPACE_ID`. Use each value
exactly as shown.

## 2. Configure Okta and collect three values

Create an **OIDC Web Application** for the Agent. Enable **Authorization
Code**, register your Agent backend's sign-in redirect URI, and assign your
test person. Give each Agent its own application, and use a separate one in
each Conduit workspace: a token works in every workspace that approved its
application. The Conduit browser sign-in app stays as it is.

In Okta, open **Security → API → Authorization Servers** and use a custom
server for Conduit:

1. Set **Audience** to the value you copied from Conduit.
2. Add the scope `conduit:connectors`.
3. Create an access policy for your Agent app and test person, allowing
   Authorization Code and the requested scopes. Set the access-token lifetime
   to **10 minutes**. Conduit refuses lifetimes over 15 minutes.

Collect these values:

| From Okta | Where you use it |
| - | - |
| Custom server's **Issuer**, such as `https://company.okta.com/oauth2/default` | The provider's **Agent access** and your Agent's OAuth configuration |
| Agent app's **Client ID** | The Agent's **Authentication** in Conduit, and your Agent |
| Agent app's **Client secret** | Your Agent backend only |

The quickest setup uses the same custom server for Conduit's browser sign-in
and the Agent. A different server must be on the same Okta domain as the
sign-in provider, including when you use an Okta custom domain. See
[Okta's server setup guide](https://developer.okta.com/docs/guides/customize-authz-server/main/).

## 3. Turn on Agent access in Conduit

As a workspace owner, reopen the provider's **Agent access**:

1. Turn on **Allow Agent access with this provider**.
2. If the sign-in issuer is the custom server from step 2, keep it. Otherwise,
   turn on **Use a different Okta authorization server** and enter that issuer
   under **Access-token issuer**.
3. Select **Save**, reopen **Agent access**, then select **Check signing keys**.
4. [Check the claims in Okta](https://pipedream.com/docs/conduit/configure/agent-authentication.md#check-the-claims-in-okta):
   the ID token of Conduit's sign-in carries the person's Okta user ID as
   `sub`, and the Agent's access token carries the same ID as `uid`.

When the Okta provider is an instance sign-in provider, an instance
administrator must approve its Agent access here and the Agent's app in step 4.

An instance administrator turns on **External agent access** at the top of
**Agents**, after every replica runs the current release.

## 4. Create the Agent and choose its access

1. In **Agents**, select **Create agent**.
2. As an owner, select **Configure authentication**, choose the **Sign-in
   provider**, and enter the Agent app's **Client ID** as **Agent OAuth client
   ID**.
3. Add the Agent to a group whose policy grants your test tool, set its
   **Delegation** to your test person, and switch the Agent on. See
   [Agent access](https://pipedream.com/docs/conduit/use/agent-access.md).

Your test person signs in to Conduit through the Okta provider, turns on the
test tool on **Home**, and connects its account if it asks for one. The Agent
uses that same account and those same tools.

## 5. Connect your Agent

Configure your Agent backend for
[Authorization Code with PKCE](https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/)
with the issuer and Agent app credentials from step 2, requesting
`openid conduit:connectors` for the test person. Give the **access token** to
the backend's MCP client:

```text theme={null}
Server URL:    https://conduit.example.com/mcp/WORKSPACE_ID
Authorization: Bearer <Okta access token>
```

List tools, then call your test tool. Expect only the tools allowed both for
the person and by the Agent's groups. Then switch the Agent off and repeat:
the request gets **403** within seconds. If a request fails, see
[Troubleshooting](https://pipedream.com/docs/conduit/configure/agent-authentication.md#troubleshooting).
