Level 3: Salesforce as the OAuth client

Salesforce calling out — not being called. How Named Credentials, External Credentials, and Auth Providers work together, and whose identity goes on the wire.

The question this level answers

Levels 1 and 2 covered Salesforce acting as an identity provider and authorization server. Level 3 flips the direction: when Salesforce makes an outbound API call, whose identity does it use?

There are exactly two answers:

The choice between these two answers is the core decision in Salesforce outbound integration.

The three configuration layers

Salesforce outbound OAuth is configured in a three-layer stack. Each layer has a distinct responsibility:

Auth Provider Defines the protocol and endpoints
Which IdP, what flows, client ID and secret, authorize URL, token URL
↓
External Credential Ties to an Auth Provider, picks named or per-user, stores tokens
Principal type, permission sets that grant access, stored access tokens per principal
↓
Named Credential The callout URL that uses the External Credential for auth
Endpoint URL, the External Credential to use; referenced in Apex callouts

Apex code references only the Named Credential by name. It never sees a token, a client secret, or a URL. Salesforce resolves the full chain at callout time and injects the Authorization header automatically.

Auth Provider

An Auth Provider is a registration of an external identity provider inside Salesforce. It stores the OAuth protocol type (OpenID Connect, Salesforce, Google, custom), the authorization and token endpoint URLs, and the client ID and secret for the application registered at the IdP.[1]

Auth Providers serve two distinct purposes — which surprises people who first encounter them in an SSO context:

The same Auth Provider can serve both purposes simultaneously. Auth Providers are created in Setup → Auth. Providers.

External Credential

An External Credential ties an Auth Provider to a principal type.[2] This is where you choose named principal or per-user principal. It also controls which users and permission sets can use the credential. Salesforce stores the actual access tokens here — one token for a named principal, one token per user for per-user principal.

External Credentials are created in Setup → Named Credentials → External Credentials tab.

Named Credential

A Named Credential is the callout endpoint: a URL plus a reference to an External Credential.[3] This is what Apex code references via HttpRequest.setEndpoint('callout:MyNamedCredential/path'). Salesforce intercepts the callout, looks up the External Credential, retrieves or refreshes the token, and adds it as an Authorization: Bearer header before the request leaves the org.

Named Credentials are created in Setup → Named Credentials → Named Credentials tab.

Named principal: one identity for all callers

A named principal External Credential holds a single token for the entire org. Every user whose permission set grants access to that credential sends the same token to the external API. The API has no visibility into which Salesforce user triggered the call.

At runtime:

  1. Apex calls callout:GraphNamedCredential/v1.0/sites
  2. Salesforce checks whether the named principal token is valid; if expired, it requests a new one using client credentials
  3. Salesforce adds Authorization: Bearer <org-token> to the outbound request
  4. Microsoft Graph receives the request and sees one application identity — not Jordan, not Alex

Under the hood: Named principal is typically backed by the client credentials grant (no user) or JWT bearer. Neither involves a user consent step. An admin configures the credentials once; the token is managed automatically from then on.

When to use it: Nightly data syncs, background jobs, any scenario where the external API does not enforce who the caller is — just that the caller is authorized. If your SharePoint integration needs to read a shared document library and Microsoft Graph only checks application-level permissions, named principal is the right choice.

Verify in your org: In Setup, go to Named Credentials → Named Credentials tab. Open any Named Credential and look at the External Credential field. Then navigate to that External Credential. Under the Principals section, you will see one principal of type "Named Principal" — this is the shared identity. Any user with the right permission set assignment uses this same principal.

Per-user principal: a different identity for each caller

A per-user principal External Credential stores a separate token for each user. The first time a user triggers a callout, Salesforce redirects them through the OAuth authorization code flow to obtain consent. After that, the token is stored and reused silently on subsequent calls.

At runtime (first call for Jordan):

  1. Jordan's Apex trigger hits a callout to callout:GraphPerUser/v1.0/me/calendars
  2. Salesforce checks whether Jordan has a stored token — Jordan doesn't yet
  3. Salesforce redirects Jordan's browser to the IdP authorization endpoint
  4. Jordan logs in and consents to the requested scopes
  5. The IdP returns an authorization code; Salesforce exchanges it for Jordan's token and stores it
  6. Salesforce retries the callout with Authorization: Bearer <jordan-token>

At runtime (subsequent calls for Jordan): Salesforce retrieves Jordan's stored token and uses it directly — no redirect.

At runtime (first call for Alex): Same consent flow as Jordan, resulting in a separate token stored for Alex.

When to use it: When the external API enforces per-user permissions. Reading Jordan's personal OneDrive files via Microsoft Graph requires Jordan's delegated token — an application-level token would be denied. Per-user principal is the only way to satisfy that requirement.

Verify in your org: In Setup, go to Named Credentials → External Credentials tab. Open an External Credential that uses per-user principal. Under the Principals section, you will see one row per user who has completed the OAuth consent flow. Each row is a separate stored token. If a user has never triggered a callout, they will not appear here yet.

Side-by-side comparison

Dimension Named principal Per-user principal
What the external API sees One application identity — the same for every Salesforce user The individual user's identity — Jordan's token, Alex's token
OAuth flow behind it Client credentials or JWT bearer (no user) Authorization code (user logs in and consents)
When setup happens Once, by an admin. No user action needed. Admin configures the credential; each user completes consent on first use
User consent None — no user is involved Required once per user at the IdP
Token expiry handling Salesforce refreshes automatically using the refresh token or re-runs client credentials Salesforce refreshes using the user's stored refresh token; if that expires, user must re-consent
If a user is deleted No effect — the shared credential is not tied to any user That user's stored token is removed; callouts for that user stop working
Audit trail granularity External API logs show one application identity — cannot attribute actions to individual users from API logs alone External API logs show individual users — full attribution
Choose when External API uses application-level permissions; individual user identity does not matter to the API External API enforces per-user permissions; you need delegated access on behalf of a specific user

Auth Providers: the legacy path

Auth Providers are an older Salesforce mechanism for registering external IdPs. They predate External Credentials and serve a similar purpose — storing the IdP protocol, endpoint URLs, and client credentials. You will still encounter Auth Providers in several contexts:

For new outbound integration work, External Credentials are the modern path. They offer cleaner separation of concerns, better permission set integration, and are the direction Salesforce is investing in. If you see an Auth Provider in an existing org, it was likely created before External Credentials existed — you do not need to migrate it unless you have a reason to.

Lab: call Graph both ways

These exercises simulate the two principal types using the Keycloak instance from this course (standing in for Microsoft Entra ID). In a real Salesforce org, Named Credential does the token management automatically — these exercises show you what is happening behind the scenes.

Exercise 1: Named principal (simulated). This simulates what Salesforce does when it makes a callout through a Named Credential backed by a named principal External Credential. The token is obtained using client credentials — no user is involved.

Run this command to get a token the way a named principal would:

curl -s -X POST https://follow-the-token-lab-12063c94a91d.herokuapp.com/token/client-credentials

Inspect the response. The access_token is what Salesforce would inject into the Authorization: Bearer header on a callout to Microsoft Graph. The aud claim is https://graph.microsoft.com. The token belongs to the application — there is no sub claim identifying a human user. In a real Salesforce org, you would never see this token; Named Credential handles it invisibly.

Exercise 2: Per-user principal (simulated). This simulates the first time a user triggers a callout through a per-user Named Credential. Salesforce redirects the user to log in and consent, then stores their token.

Open the Keycloak lab and run Flow 1 (Authorization code grant). Log in as testuser. The ID token and access token you receive represent what Salesforce would store for that user. The access token's sub claim identifies the specific user. In a real Salesforce org, Salesforce would store this token and silently reuse it on subsequent callouts — the user only sees the consent screen once.

Compare the two tokens: the named principal token from Exercise 1 has no sub claim (no user). The per-user token from Exercise 2 has a sub claim (a specific user). That difference is the entire distinction between the two principal types.

Self-check: test your understanding

Answer these questions to confirm you understand Salesforce outbound OAuth:

Question 1 of 5: Configuration layers

An Apex developer calls HttpRequest.setEndpoint('callout:GraphIntegration/v1.0/sites'). What does the Named Credential GraphIntegration contain, and what does it reference?

Question 1 choices

Question 2 of 5: Choosing the principal type

Harbor Point Financial runs a nightly Apex batch job that reads SharePoint documents from a shared team site and indexes their titles in Salesforce. No individual user is running the job. Which principal type should the External Credential use?

Question 2 choices

Question 3 of 5: First-time per-user callout

Jordan Reyes is a Salesforce user with a permission set that grants access to a per-user External Credential for Microsoft Graph. Jordan clicks a button that triggers an Apex callout. This is Jordan's first time using this integration. What happens?

Question 3 choices

Question 4 of 5: OAuth flow backing named principal

A named principal External Credential needs to call Microsoft Graph to read shared SharePoint content. No user is involved. Which OAuth grant type does Salesforce use to obtain the access token?

Question 4 choices

Question 5 of 5: Auth Providers vs. External Credentials

A colleague says you should use an Auth Provider to set up a new Salesforce outbound integration with Microsoft Graph. What is the most accurate response?

Question 5 choices

What's next

Next: Level 4 (in development). Level 4 covers the hard parts: scopes vs. app roles, admin consent, the On-Behalf-Of flow, token exchange (RFC 8693), workload identity federation, and a brief look at sender-constrained tokens (mTLS, DPoP).

← Back to course home

Sources

  1. About Auth. Providers, Salesforce Help
  2. External Credentials, Salesforce Help
  3. Apex Callouts Using Named Credentials, Salesforce Developer
  4. The OAuth 2.0 Authorization Framework, IETF
  5. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants, IETF

All company names, tokens, and identifiers in this course are fictional. Harbor Point Financial is a teaching example for Salesforce colleagues learning identity and OAuth fundamentals.