Level 2: OAuth 2.0 core flows

Six grant types, one decision table. Pick the Overview tab for the reference, then explore each flow.

OAuth 2.0 defines several grant types — ways for a client to obtain an access token. Each one answers a different question about who is involved, how the client proves its identity, and what gets returned. The table below is the reference; the other tabs let you run each flow live against Keycloak.

Flow User? Credentials presented Client receives Typical Salesforce use case
Auth code + PKCE Yes code_verifier (PKCE) or client_secret Access + refresh + ID token (OIDC) Per-user API access; external apps that connect user's Salesforce data
Client credentials No client_id + client_secret Access token only Scheduled nightly sync; integration user; server-to-server
Refresh token Not again refresh_token + client creds New access token Keeping a Named Credential alive without re-prompting the user
JWT bearer No Signed JWT (private key — no shared secret) Access token Connected App certificate-based auth; server-to-server without a secret
Device authorization Yes — other device device_code polled; user enters user_code Access + refresh token sf org login device; headless servers; IoT; Agentforce agents
External Client Apps Depends Depends on configuration Depends on configuration Salesforce packaging layer over standard flows; replaces legacy Connected Apps
Auth code vs. client credentials: The key difference is the user. Authorization code involves a resource owner granting permission; client credentials does not. If your integration acts on a user's behalf, use authorization code. If it acts as the application itself — a background job, a service account — use client credentials.
Client credentials vs. JWT bearer: Both are machine-to-machine with no user. JWT bearer replaces the client_secret with a signed assertion — the client proves its identity using a private key rather than a shared secret. Use it when you can't safely store a secret or when higher assurance is required.

Use this when a user needs to grant your application access to their resources. The user logs in, consents, and the authorization server issues tokens scoped to that user's permissions. PKCE (Proof Key for Code Exchange, pronounced "pixie") prevents an attacker who intercepts the authorization code from using it — only the client that generated the original code_verifier can complete the exchange.[1]§1 PKCE is now recommended for all authorization code flows, not just public clients.[3]§2.1.1

code_verifier  = base64url(random_bytes(32))          # generated in browser
code_challenge = base64url(SHA256(code_verifier))      # sent to auth server

GET /authorize?response_type=code
  &client_id=agent365-integration
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &scope=openid profile email offline_access

POST /token
  grant_type=authorization_code
  &code=<received_code>
  &code_verifier=<original_verifier>

Tokens received

Access token:

ID token:

Refresh token stored:

Compare to client credentials: Both return an access token, but authorization code requires the user to be present and consent. The result is a token scoped to that user's permissions, not the application's.

Use this when no user is involved. The client authenticates as itself — using its client_id and client_secret — and receives an access token scoped to the client's own permissions.[4]§4.4 No consent screen, no redirect, no ID token. Right for scheduled jobs, background integrations, and server-to-server calls where you're acting as the application.

POST /token
  grant_type=client_credentials
  &client_id=agent365-integration
  &client_secret=<secret>

Access token received

Compare to JWT bearer: Both are machine-to-machine. JWT bearer replaces the shared client_secret with a signed key assertion — useful when you can't safely store a secret or when the authorization server requires stronger client authentication.

A refresh token is returned alongside the access token in auth code flows. When the access token expires, the client can exchange the refresh token for a new one — no login prompt, no user interaction.[4]§1.5 This is not re-authentication: it assumes the original consent is still valid. If the refresh token is revoked or expired, the user must go through the full flow again.

POST /token
  grant_type=refresh_token
  &refresh_token=<stored_refresh_token>
  &client_id=agent365-integration
  &client_secret=<secret>

New access token

Compare to auth code: Auth code gets the initial tokens with user consent. Refresh token extends that authorization silently. Revoking the refresh token (the user removes access) forces a full re-authorization.

Instead of a client_secret, the client signs a JWT assertion with its private key and sends it to the token endpoint.[5]§2.1 The authorization server validates the signature against the registered public key. No secret is transmitted — only a proof of key possession. This is how Salesforce Connected App certificate-based authentication works.

# JWT assertion payload
{ "iss": "agent365-jwt-bearer",
  "sub": "agent365-jwt-bearer",
  "aud": "https://keycloak.example/token",
  "exp": now + 60,
  "jti": "<unique_id>" }

POST /token
  grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
  &client_id=agent365-jwt-bearer
  &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  &client_assertion=<signed_JWT>

Access token received — no secret transmitted

Compare to client credentials: Same outcome — machine-to-machine access token — but the client authentication method differs. A secret can be leaked or rotated; a private key stored in an HSM or secure enclave cannot be extracted, making JWT bearer the stronger option.

Use this when the client cannot open a browser — a CLI tool, a headless server, an IoT device, an Agentforce agent. The device requests a short human-readable code, displays it, and polls until the user approves on a separate device.[6]§1 The SF CLI uses this exact flow: sf org login device prints a URL and a code, you open the URL on your laptop and enter the code, and the CLI gets an access token when you approve.

Enter this code at the link below

Waiting for you to approve at the link above…
Compare to auth code: Both involve a user, but auth code uses a browser redirect. Device flow was designed for clients that cannot receive a redirect — the user authenticates on a completely separate device, and the client learns about it only by polling.

External Client Apps (ECAs) are not a new OAuth grant type. They are Salesforce's configuration container for standard OAuth flows — the successor to Connected Apps for outbound integrations. To understand what an ECA is doing on the wire, identify the underlying flow it's running.

Pattern 1: Backend service syncing data nightly

A Salesforce org pushes daily reports to an external data warehouse on a schedule. No user is present. The underlying flow is client credentials: the ECA authenticates as itself, calls the external API as the application. In Salesforce terms: a named principal ECA — one shared identity for all calls.

Pattern 2: Mobile app where users connect their Salesforce data

A field service app lets technicians log in with their Salesforce credentials and see their open cases. Each technician's access is scoped to their own data. The underlying flow is authorization code + PKCE: each user logs in, consents, the app gets a per-user token. In Salesforce terms: a per-user principal ECA — each user's credential stored separately.

Pattern 3: Server calling Salesforce with certificate-based auth

A microservice calls the Salesforce REST API from an environment that uses key-based auth instead of a shared secret. The underlying flow is JWT bearer: the server signs a JWT with its private key, Salesforce validates against the registered public key. No secret transmitted.

Key point: When you configure an ECA in Salesforce, you are choosing which standard OAuth flow it will use and how credentials are stored. The ECA is not a protocol — it is a configuration container. Understanding the underlying flow tells you exactly what happens on the wire.

Self-check: test your understanding

Answer these questions to confirm you can apply the right flow to the right situation.

Question 1 of 5: Choosing a flow

Your team needs a Salesforce integration that syncs records to an external data warehouse every night at 2 a.m. No user will be present when it runs. Which OAuth grant type should it use?

Question 1

Question 2 of 5: What PKCE protects against

A malicious app intercepts the authorization code during the redirect to the legitimate app's callback URI. Why does PKCE prevent this from being useful to the attacker?

Question 2

Question 3 of 5: Refresh tokens

Jordan's access token expires. The app sends the stored refresh token to get a new one. At no point does Jordan see a login page. Why not?

Question 3

Question 4 of 5: Device flow

A developer runs sf org login device. The CLI prints a URL and a short code. What is the CLI doing while the developer opens the URL in their browser and approves?

Question 4

Question 5 of 5: External Client Apps

A Salesforce admin configures an External Client App as a "named principal." The ECA will call an external REST API on a nightly schedule. Which standard OAuth flow does this ECA use, and why?

Question 5

What's next

Level 3 covers Salesforce as the OAuth client — Named Credentials, External Credentials, and Auth Providers — and the critical distinction between named principal and per-user principal.

← Back to course home

Sources

  1. RFC 7636: Proof Key for Code Exchange by OAuth Public Clients, IETF
  2. RFC 7636 §4: Protocol, IETF
  3. RFC 9700: Best Current Practice for OAuth 2.0 Security, IETF
  4. The OAuth 2.0 Authorization Framework, IETF
  5. RFC 7523: JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants, IETF
  6. RFC 8628: OAuth 2.0 Device Authorization Grant, 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.