User Sources

A User Source is the connection between an Gateway and your OIDC identity provider. When a gateway uses a Source, Arcade redirects each end user to your identity provider to sign in and then identifies them by an OIDC subject claim on every gateway request.

What is a User Source?

Use a Source when your end users already have identities in your own identity system, such as Entra ID, Okta, Auth0, Clerk, Stytch, or a similar OIDC provider. A User Source plugs that identity directly into your gateway, so Arcade doesn’t have to know about your end users ahead of time and you don’t have to provision them into Arcade.

A Source is deliberately separate from any identity provider you use for Arcade admin sign-in. The User Source identifies the Users of your gateways (end users), while the Arcade admin sign-in provider identifies the Arcade that manage your . Keeping the two distinct means you can govern your administrators and your end users with different identity systems and different policies.

User Sources are project-bound. You create one in a project, then attach it to any Gateway in that project. One Source can back many gateways, so gateways serving different purposes can share the same end-user identity system without duplicating the configuration.

When to use a User Source

Arcade Gateways support three ways to authenticate end :

Mode	Best for
Arcade Auth	Development, testing, and internal use, when every end user is a member of your Arcade project
User Source (recommended for production)	Production agents whose end users have identities in your OIDC identity provider
Arcade Headers (fallback)	MCP clients that can’t run a browser-based OAuth flow

See MCP Gateway authentication for the full comparison and for how to pick an authentication mode when creating a gateway.

Register an OAuth client at your identity provider

Before you create a Source in Arcade, register a confidential OAuth client at your identity provider. The client must use the Authorization Code flow with PKCE.

Configure the redirect URL

Set the redirect URL on the OAuth client to https://cloud.arcade.dev/oauth2/intermediate_callback.

Your identity provider will redirect end back to this URL after they sign in, and Arcade exchanges the resulting code for an ID token.

Copy the client credentials

From your identity provider, copy the issuer URL, client ID, and client secret. You’ll provide them to Arcade in the next section.

Create a User Source

Open the User Sources dashboard

Open the Arcade Dashboard, select your , navigate to , and click Create Source.

Fill in the User Source details

Provide the following:

Name: A short, human-readable name for this connection. For example, Corporate Identity.
Description (optional): Free-form notes about the connection. These notes are visible to other members of your Arcade and are never shown to end .
Issuer URL: The OIDC issuer URL from your identity provider, for example https://accounts.example.com. Arcade matches this against the iss claim on incoming tokens, so it must exactly match what your identity provider issues.
Client ID: The client ID of the OAuth client you registered with your identity provider.
Client Secret: The matching client secret. Arcade stores it encrypted and never returns it through the API or dashboard.

Save the User Source

Click Create. The new Source appears in the list with Active status and is ready to attach to an Gateway.

Advanced: scopes and subject claim

The Source form’s Advanced section exposes two settings most setups can ignore. Both have defaults that work for the providers covered by the per-provider guides. Expand the section only if you have a specific reason to change them.

Scopes

Scopes are the OIDC scopes Arcade requests from your identity provider on every sign-in. The default is openid profile email, which is enough to receive an ID token and the standard profile claims most providers emit.

openid is always required. Arcade refuses to save a Source without it.
Arcade validates the rest of the list against your provider’s published scopes_supported, so the form catches an unrecognized scope at save time rather than letting it surface at runtime.
Add a provider-specific scope (for example, groups on Okta) when you’ve configured a custom claim that depends on it. See your provider’s documentation for which scopes unlock which claims.

Subject claim

The Subject Claim is the JWT claim Arcade uses to identify each of your end on every gateway request. The default is sub, and it’s the right pick on almost every provider. Whichever claim you choose must satisfy two properties:

Stable per : the value for one person stays the same across sessions, password resets, profile edits, and so on. If the value changes, Arcade treats the returning person as a brand-new user. Arcade prompts them to authorize again, and any per-user state your track starts over.
Unique forever: the value is never reused for a different person. Some claim values feel unique but aren’t. Email addresses and usernames are commonly reassigned, for example when a former employee leaves and a new hire with a similar name takes over the address. If a claim value gets reused, the new person inherits whatever the previous owner had access to.

sub satisfies both properties on every provider Arcade has documented. Some providers also expose a directory-wide identifier (for example, Microsoft Entra ID’s oid) that’s stable across multiple app registrations in the same tenant. Pick one of those only when you specifically need to correlate the same person across multiple Arcade projects or Sources. The per-app sub is otherwise more privacy-preserving.

Use a User Source on an MCP Gateway

You attach a User Source to an Gateway when you create or edit the gateway. One Source can back multiple gateways in the same , so you can reuse the same end-user identity system across every gateway you build for those users.

See Create via Dashboard for how to pick a Source when configuring a gateway’s authentication.

Manage User Sources

Edit a User Source

You can change a Source’s name, description, issuer URL, client ID, or subject claim at any time from the User Sources dashboard. Saving the changes affects every gateway that uses this User Source on its next request.

Rotate the client secret

To rotate the client secret:

Open the Source in the dashboard.
Enter the new secret in the Client Secret field.
Save.

The field is blank in edit mode and only updates when you fill it in, so editing other fields does not affect the stored secret.

Rotate the client secret in your identity provider first, then update it in Arcade. There’s a short window where token exchange fails if Arcade’s stored secret doesn’t match the one your provider expects.

Deactivate a User Source

Set a Source’s status to Inactive to take it out of rotation. You can only deactivate a User Source after every Gateway that uses it is itself deactivated or deleted. If an active gateway still references the source, the dashboard blocks deactivation and tells you how many gateways still depend on it.

To deactivate a Source, deactivate or delete the dependent gateways first, then change the User Source’s status to Inactive.

Delete a User Source

Deleting a Source is permanent. As with deactivation, you can only delete a User Source when no active gateway references it. The dashboard blocks the action until you deactivate or remove the dependent gateways.

Next steps

MCP Gateway authentication for a comparison of Arcade Auth, Sources, and Arcade Headers
Connect to MCP clients to point your client at a gateway that uses a Source