Salesforce calling out — not being called. How Named Credentials, External Credentials, and Auth Providers work together, and whose identity goes on the wire.
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.
Salesforce outbound OAuth is configured in a three-layer stack. Each layer has a distinct responsibility:
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.
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.
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.
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.
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:
callout:GraphNamedCredential/v1.0/sitesAuthorization: Bearer <org-token> to the outbound requestUnder 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.
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):
callout:GraphPerUser/v1.0/me/calendarsAuthorization: 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.
| 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 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.
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.
Answer these questions to confirm you understand Salesforce outbound OAuth:
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).
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.