Connecting multiple accounts
A user signs in to PolicyArc once. But the tools they reach through the gateway can each belong to a different service — a user who logged in with Microsoft might call a tool backed by GitLab, and another backed by Jenkins. For those tools to act as the real person (not a shared account), PolicyArc needs that user's own identity at each service.
How a connector authenticates to its upstream decides whose identity a tool call runs as:
- Forward the user's login — for upstreams that speak OAuth (Google, Microsoft, Atlassian Cloud, GitLab), PolicyArc forwards the user's own identity-provider token.
- A shared, app-wide credential — one credential (a service account, or a shared account) that every user's calls run as. Simple, but the upstream can't tell users apart.
- Per-user credentials — for upstreams that don't support OAuth (they take a user-held API token or personal access token), each user supplies their own credential.
This page covers the two per-user paths — signing in with another provider, and supplying a per-user credential. In both, the user connects their own account once, on demand, and PolicyArc uses it only for that user's calls.
You (the admin) register identity providers and set up connectors — including choosing, per connector, whether it uses per-user or a shared app-wide credential. Each user connects their own account or credential once, on demand — the first time a tool needs it, and again if it later lapses. There's no per-user setup on your side.
Why it exists
PolicyArc issues one access token per login and federates the user to exactly one identity provider at sign-in. That single login is enough for tools that need no upstream identity, or that the gateway calls with a shared service account. It is not enough for connectors that act as the individual user:
- OAuth upstreams need the user's token for that provider. PolicyArc only captured the sign-in provider's token, so a tool for a different provider has nothing to forward.
- Non-OAuth upstreams — self-hosted developer/DevOps tools, CI servers, artifact registries, code-quality servers — reject identity-provider tokens entirely and accept only a credential the user creates in that tool. The shared-credential alternative means the upstream sees one account for everyone, so its own logs, permissions, and audit trail can't distinguish users.
Rather than fail, PolicyArc turns the gap into a one-time "connect your account" step, keyed to the user's PolicyArc identity, so each user's calls carry their own identity end-to-end.
How it works
The connection happens lazily — on the first call to a tool that needs it — so a user only ever connects the accounts they actually use. There are two collection styles depending on the upstream.
Signing in with another provider (OAuth)
The link points at PolicyArc's own endpoint on the issuer origin, then redirects the user into the provider's standard OAuth sign-in — the same flow they'd use to log in anywhere else. PolicyArc never sees the user's password; it receives and stores only the resulting OAuth token, server-side.
Supplying a credential (non-OAuth services)
The credential is entered on a PolicyArc-hosted page in the user's browser — it goes straight to PolicyArc and is stored encrypted; PolicyArc assembles the upstream's Authorization header from it on each request. Which fields the form asks for (for example a username and a token, or just a token) is defined by the connector. The credential never transits the MCP client or the model — the agent only ever receives a link to open.
What the user sees
How the "connect your account" prompt reaches the user depends on their MCP client, and is the same for both styles:
- Clients that support URL elicitation (the MCP mechanism, SEP-1036, for a server to ask the user to visit a URL) present the connect link automatically, and can retry the tool once the user finishes.
- Every other client receives the link inside the tool's result, which it relays to the model, so the user still gets a clickable "connect your account, then retry" message.
Either way the outcome is the same: one browser interaction, then the tool works.
Signing in first
The connect page confirms the person completing it is the same user the tool call was for. If the browser has no active PolicyArc session (common — the agent's session and the browser session are independent), the user is simply asked to sign in first and is then returned to finish. This isn't a dead end; it preserves the guarantee that an account is only ever connected to its own user's identity.
Reconnecting when access lapses
Connections don't last forever, and the same connect flow covers renewing them:
- OAuth accounts — if a user's stored token has expired and can't be refreshed (PolicyArc holds no refresh token, or the provider rejected the refresh), the same
idp_link_requiredlink is returned so the user can reconnect. - Per-user credentials — API tokens get revoked or expire, and PolicyArc can't always tell in advance, so reconnection is reactive: if the upstream rejects a stored credential with a
401, the same connect prompt appears so the user can re-enter their token (overwriting the old one).
Failures a fresh connection would not fix stay hard errors — a misconfigured or disabled provider, a missing admin consent / API permission, a transient outage, or an upstream 403 (authenticated but not permitted). This keeps the connect prompt meaningful: it appears only when reconnecting is the actual remedy.
Google only returns a refresh token when the sign-in requests offline access and forces the consent screen. PolicyArc seeds those parameters (access_type=offline, prompt=consent) automatically — but only for Google identity providers registered after this became the default. A Google provider you registered earlier keeps its saved authorize parameters, so its users may get a fresh connect prompt each time the hourly token lapses. To fix an existing Google provider, re-register it (or update its authorize parameters to request offline access). This does not affect Google connectors that use a service account.
What you configure
This feature is automatic once the pieces below are in place — there is no per-user setup on your side.
- Register each identity provider your users will connect to (see the other pages in this section). A provider only appears in a connect flow if it's registered and enabled.
- Point each OAuth connector at the provider it needs. For a connector that forwards the user's token, its user-IdP setting names the provider PolicyArc will ask the user to sign in with. Connectors that use a shared service account or no upstream identity never trigger a connect prompt.
- Choose the auth mode for each non-OAuth connector — per-user credentials (recommended; each user connects their own token, no shared secret to manage) or a shared, app-wide credential (one credential all users' calls run as; use only when per-user identity genuinely doesn't matter for that upstream). Per-user is the default where it's offered.
- Make sure the gateway's link signing secret is set. The connect links are signed so they can't be forged; on hosted PolicyArc tenants this is provisioned for you, and self-hosted deployments must set it before the gateway will issue connect links (the server refuses to start in production without it).
Security
The connect flow is designed so one user can never connect an account to someone else's identity, and so upstream tokens and credentials never reach the agent:
- The account link / credential is bound to the user. Completing a connection requires an authenticated PolicyArc browser session whose identity matches the one the link was minted for — a link opened by a different user is refused, and a link opened with no session prompts a sign-in rather than proceeding.
- The link can't be tampered with or replayed. It's signed (HMAC), short-lived, and single-use; it carries no secret and is safe to place in a URL.
- Secrets stay out of the agent. OAuth tokens are held server-side and injected into upstream calls; per-user credentials are entered on PolicyArc's own page in the browser (masked inputs, same-origin submit) and never touch the MCP client or the model. The retry-me signal sent back to capable clients carries no token or credential.
- Encrypted at rest. Stored tokens and credentials are AES-GCM encrypted, scoped per user (and per provider / connector), never returned by any API, and never logged in cleartext.
- Trust only PolicyArc's own links. A legitimate connect link always arrives in the gateway's own response and always points at your PolicyArc issuer origin. Treat any "re-authenticate here" link embedded in an upstream tool's content as untrusted.
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
| A user is asked to connect the same Google account repeatedly | The Google provider predates the offline-access default and has no refresh token — re-register it or add offline-access authorize parameters (see the Google caution above). |
| A tool keeps asking the user to connect a non-OAuth service | The stored token was rejected by the upstream (401) — it was revoked or expired; the user re-enters a current token to overwrite it. |
| Tool call returns a hard error instead of a connect prompt | The failure isn't something a connection fixes — an upstream 403 (authenticated but not permitted), a disabled/misconfigured provider, or a missing admin consent / API permission. Check the user's access on the upstream. |
| User is asked to sign in to PolicyArc when opening the connect link | Expected if their browser session had lapsed — the agent's session and the browser session are independent. They sign in and are returned to finish connecting. |
| Connect link says it belongs to a different identity | The link was minted for another PolicyArc user; each user must connect from their own session. |
| Every user's calls show up as the same account on a non-OAuth upstream | The connector is configured with a shared, app-wide credential — switch it to per-user credentials if the upstream should see individual users. |
| A client shows the connect message as text but doesn't open it automatically | The client doesn't support automatic URL elicitation — the user opens the link manually, completes it, then retries the tool. |
Related
- Identity providers — register the providers users connect to.
- Resource connectors — connectors that act as the user run in a per-user mode and drive this flow.
- MCP Protocol Flows — the wire-level view of gateway authorization, including the connect (step-up) response.