OAuth and Linked Accounts

Overview

OAuth on a has two independent halves:

Half	Between	What it does
Linked accounts (upstream)	and the upstream service	Each user links their own account once. The Connector sends that user’s access token upstream.
Formal OAuth (downstream)	Client and Connector	Clients sign in with Formal and get a short-lived token for one Resource.

Linked accounts replace shared credentials. Requests reach the upstream as the person who made them, with that person’s upstream permissions. Users never see or handle the upstream token. You can enable OAuth on MCP, HTTP, gRPC, and LLM Resources. For remote MCP servers, the MCP Gateway guide covers the full setup, including listeners, hostnames, and client configuration. Linked accounts are sent through a native user. A Linked Account native user sends the requesting user’s linked token instead of a stored credential, and the Resource’s native user selection picks it like any other native user. Linked Account native users need native_users_v3_enabled on the Resource and Connector 2.25.14 or later.

How the Connector picks the linked account

The Connector sends the linked account of the human the request is for:

Request authenticated with	Linked account used
A Formal OAuth access token	The user who approved the client
Identity headers from the Formal Endpoint	The signed-in user
An OIDC federation token that names an end user	The end user (Connector 2.25.2 or later)
An OIDC federation token without an end user	None. The machine user can’t link accounts, so the request is rejected.

An end user asserted in a request header, such as X-Formal-End-User-Identity, never selects the linked account. It only sets the for policies and logs.

A federation token’s end user comes from the integration’s End-User Email Expression. Workloads that pass that check act upstream as the resolved person. Only map claims the workload can’t choose itself, such as a verified sub or email claim. Avoid instance tags that anyone with tagging access can set.

If the user hasn’t linked an account, or the link expired, the Connector rejects the request. The error tells the user to link the account on the Resource’s page in the Catalog.

Set up linked accounts (upstream)

1. Choose the OAuth app

Formal needs an OAuth client to sign users in to the upstream’s authorization server.

Formal's app (formal)

You don’t register anything. Formal identifies itself in one of two ways:

With an app Formal registered with the provider, when there is one.
Otherwise, with a Client ID Metadata Document (CIMD), when the authorization server supports it.

Formal checks the authorization server when you save. If neither works, saving fails. Use your own OAuth app instead.

Your OAuth app (pre_registered)

Use this for providers such as GitHub, where you register an app yourself.

Register an OAuth app with the provider.
Add the Redirect URI that Formal shows to the app’s allowed redirect URIs.
Enter the app’s Client ID and, if it has one, its Client secret.

Formal encrypts the secret and never shows it again. Leave the secret empty for a public client, which uses PKCE alone.

Formal doesn’t register itself with authorization servers through Dynamic Client Registration (DCR).

2. Point Formal at the authorization server

Formal discovers the authorization server from the Resource’s protected resource metadata (RFC 9728). MCP servers usually publish it. Most other APIs don’t. For those, set the Authorization server to the provider’s issuer URL. Formal then reads the issuer’s authorization server metadata directly.

Upstream	Authorization server
GitHub REST API (`api.github.com`)	`https://github.com/login/oauth`
An MCP server with protected resource metadata	Leave empty

The issuer must use https, have no query or fragment, and exactly match the issuer its metadata reports. Verify:

curl -s https://github.com/login/oauth/.well-known/oauth-authorization-server \
  | jq '{issuer, authorization_endpoint, token_endpoint}'
# Expected: "issuer" is exactly https://github.com/login/oauth

3. Choose scopes

Use Permissions to request to list scopes. When you leave it empty:

For an MCP server, Formal requests the scopes in its sign-in challenge, or else those its protected resource metadata lists.
Otherwise, Formal omits the scope parameter, and the provider’s defaults apply.

You can change the scopes later. New scopes apply the next time each user links. Linked accounts keep the scopes they were granted.

4. Save the settings

Control Plane
Terraform

Go to Resources and open the Resource.
Open the Authentication tab.
Under Linked Accounts, click Set Up Linked Accounts.
Choose the OAuth app, and set the Authorization server and Permissions to request if needed.
Click Save linked accounts.

Formal adds a linked-account native user that sends each user’s token as a bearer token. It becomes the default native user unless the Resource already has one.You can also click Add User under Native Users and choose Linked Account (OAuth).For MCP servers, configure Authentication on the server’s Configuration tab in the Catalog instead.

resource "formal_resource" "github" {
  name       = "github"
  technology = "http"
  hostname   = "api.github.com"
  port       = 443

  native_users_v3_enabled = true
}

resource "formal_resource_oauth_settings" "github" {
  resource_id              = formal_resource.github.id
  upstream_oauth_mode      = "pre_registered"
  client_id                = var.github_oauth_app_client_id
  client_secret_wo         = var.github_oauth_app_client_secret
  client_secret_wo_version = 1
  issuer                   = "https://github.com/login/oauth"
  requested_scopes         = ["repo", "read:org"]
}

resource "formal_native_user_v3" "linked_account" {
  resource_id = formal_resource_oauth_settings.github.resource_id
  label       = "linked-account"

  linked_http_bearer {
    header = "Authorization"
  }
}

resource "formal_resource_native_user_selection" "github" {
  resource_id = formal_resource.github.id
  cel         = "\"${formal_native_user_v3.linked_account.id}\""
}

Omit upstream_oauth_mode to use Formal’s app. See formal_resource_oauth_settings.Terraform doesn’t add the native user or the selection for you. Without formal_resource_native_user_selection, the Connector refuses requests that don’t name a native user with @<label>. Formal OAuth clients and the Formal Endpoint never name one.

You can update the scopes and the client secret in place. Linked accounts and client approvals are kept.

The OAuth app mode, client ID, and authorization server are fixed. Changing one deletes and recreates the settings. That unlinks every account and revokes every client approval for the Resource.

Verify: Open the Resource in the Catalog as a user, and go to the Installation tab. You’ll see a Your account panel with a Link account button.

5. Choose how the token is sent

Credential type	Sends
`linked_http_bearer`	The token as a bearer token in a named header, such as `Authorization: Bearer <token>`
`linked_http_basic`	Basic credentials in a named header, with your `username` and the token as the password

Use linked_http_basic for upstreams that only accept Basic credentials, such as git over HTTPS:

resource "formal_native_user_v3" "linked_account" {
  resource_id = formal_resource_oauth_settings.github.resource_id
  label       = "linked-account"

  linked_http_basic {
    header   = "Authorization"
    username = "<USERNAME>"
  }
}

The default selection can mix linked accounts with shared credentials:

"contractors" in user.groups
  ? native_users["read-only"]
  : native_users["linked-account"]

Clients can also request any of the Resource’s native users by label with @<label>. That includes one with a shared credential in place of their linked account. To restrict that, write a policy.

Link an account

Users link their own accounts:

Open the Resource in the Catalog, and go to the Installation tab.
Under Your account, click Link account, and sign in to the provider.

Users can also link during Formal OAuth sign-in, on the consent screen. Formal stores tokens encrypted in its control plane. When the provider issues refresh tokens, Formal refreshes access tokens before they expire. Otherwise, users link again once the access token expires. Verify: Send a request through the Connector as that user. For example, through the Formal Endpoint:

curl -s https://api.github.com/user | jq .login
# Expected: the GitHub login of the account you linked

Formal OAuth (downstream)

With OAuth enabled, the Connector is an OAuth protected resource for the Resource. Clients that support MCP-style authorization sign in with Formal:

The client calls the Resource’s Connector address without a token.
The Connector answers 401 Unauthorized. Its WWW-Authenticate header points to /.well-known/oauth-protected-resource, which lists Formal as the authorization server.
The user signs in to Formal and approves the client on a Catalog consent screen. If the Resource uses linked accounts, the user links there too.
Formal issues an access token bound to this Resource’s address, plus a refresh token.

The Connector address uses smart routing:

https://<resource-name>.<connector-hostname>

The Connector validates access tokens offline and removes them before forwarding the request.

Token	Lifetime
Access token	15 minutes, for one Resource
Refresh token	90 days, rotated on each use

Formal OAuth works when upstream authentication is linked accounts or shared credentials. Requests that identify no Formal user are rejected.

Every client must use PKCE with S256. Formal’s authorization server doesn’t support Dynamic Client Registration (DCR). Clients identify themselves in one of two ways:

Client type	How it identifies itself	Examples
CIMD	Its own Client ID Metadata Document URL	Claude, ChatGPT, Claude Code
Pre-registered	A client ID you create in Formal	Clients without CIMD support, such as Cursor or Devin

To pre-register a client:

Control Plane
Terraform

Go to OAuth and open the Clients tab.
Create a client with its name and exact redirect URIs.
Make it confidential if the client can keep a secret. Copy the secret now; Formal shows it only once.
Configure the client with the client ID and, if confidential, the secret.

resource "formal_oauth_client" "cloud_agent" {
  name          = "Cloud agent"
  redirect_uris = ["https://agent.example.com/oauth/callback"]
  confidential  = true
}

See formal_oauth_client.

Redirect URIs must be https, http on a loopback host (any port), or a private-use scheme containing a period. Confidential clients authenticate with client_secret_basic or client_secret_post. Public clients use PKCE alone.

Manage approvals and linked accounts

Users manage their own:

Authorized apps in the Catalog account menu lists every client they approved, with a revoke action.
Each Resource’s Installation tab in the Catalog shows their linked account, with Unlink.

Administrators manage the whole organization on the OAuth page:

Tab	Shows	Action
Authorized apps	Every user’s approved clients, and what each can access	Revoke
Linked accounts	Every user’s linked accounts, with scopes and token expiry	Unlink
Clients	Pre-registered clients	Create, edit, rotate secret, delete

Revoking an approval stops the client from refreshing. Access tokens it already holds keep working on Connector Resources until they expire, within 15 minutes. Unlinking revokes the tokens at the provider when it supports revocation, then deletes them. If the provider doesn’t confirm, revoke the authorization in the provider’s settings too.

Policies and logs

Requests authenticated with a Formal OAuth access token carry input.user.oauth: the client’s ID, name, type, and the consent ID. Logs record the same fields under user.formal.oauth. A cimd client chooses its own name, so match on input.user.oauth.client.id or type. See OAuth clients for every field and an example that allows only pre-registered clients.

Troubleshooting

Cause: The user the request is for has no linked account, or its access token expired without a refresh token.Fix: Link or re-link the account on the Resource’s page in the Catalog. For OIDC federation tokens, check these too:

The federation token names an end user. The mint response includes end_user_id.
That end user, not the machine user, linked the account.
The Connector runs 2.25.2 or later.

"No default native user is configured for <resource>"

Cause: The Resource has linked accounts but no default native user, and the request didn’t name one with @<label>.Fix: Make the linked-account native user the default. With Terraform, add a formal_resource_native_user_selection that picks it.

Requests reach the upstream without the user's token

Cause: The default native user, or the one the client requested with @<label>, sends a shared credential.Fix: Make the linked-account native user the default. To stop clients requesting another one, write a policy.

"<resource> rejected your credentials"

Cause: The upstream refused the linked account’s token, for example after a password change or revoked grant. The native user may also send it in a form the upstream doesn’t accept.Fix: Re-link the account. If the token lacks a permission, add the scope under Permissions to request, then re-link. For git over HTTPS, use linked_http_basic and Connector 2.25.14 or later. Older Connectors always send the token as a bearer token.

Saving linked accounts fails

Possible causes:

The Resource publishes no protected resource metadata, and no authorization server is set
The authorization server supports neither CIMD nor an app Formal registered

Fix: Set the Authorization server to the provider’s issuer. If saving still fails, switch to Your OAuth App.

Next Steps

MCP Gateway

Route remote MCP servers through a Connector

OIDC

Give workloads federated Connector access

Native Users

Send shared credentials instead

Policy Evaluation

Write policies on OAuth clients

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Overview

How the Connector picks the linked account

Set up linked accounts (upstream)

1. Choose the OAuth app

2. Point Formal at the authorization server

3. Choose scopes

4. Save the settings

5. Choose how the token is sent

Link an account

Formal OAuth (downstream)

Manage approvals and linked accounts

Policies and logs

Troubleshooting

Next Steps

MCP Gateway

OIDC

Native Users

Policy Evaluation

​Overview

​How the Connector picks the linked account

​Set up linked accounts (upstream)

​1. Choose the OAuth app

​2. Point Formal at the authorization server

​3. Choose scopes

​4. Save the settings

​5. Choose how the token is sent

​Link an account

​Formal OAuth (downstream)

​Clients that can sign in

​Manage approvals and linked accounts

​Policies and logs

​Troubleshooting

​Next Steps

MCP Gateway

OIDC

Native Users

Policy Evaluation

Overview

How the Connector picks the linked account

Set up linked accounts (upstream)

1. Choose the OAuth app

2. Point Formal at the authorization server

3. Choose scopes

4. Save the settings

5. Choose how the token is sent

Link an account

Formal OAuth (downstream)

Clients that can sign in

Manage approvals and linked accounts

Policies and logs

Troubleshooting

Next Steps