Level 0: Vocabulary and mental model

Learn the core concepts of identity, authentication, and authorization before diving into flows

Authentication vs. authorization

These two terms sound similar but answer different questions:

Both are essential for secure integrations, but they solve different problems.

Three protocols: Security Assertion Markup Language (SAML), OAuth 2.0 (OAuth), and OpenID Connect (OIDC)

Three protocols dominate enterprise identity and integration:

SAML 2.0: web single sign-on

SAML allows one party to assert security information about a subject.[2]§3 In practice, SAML answers "who is this person, so this app can log them in." An identity provider (IdP) like Microsoft Entra ID authenticates the user and sends a signed Extensible Markup Language (XML) assertion through the browser to a service provider (SP) like Salesforce.[2]§3 The service provider checks the assertion's signature, audience[10]§2.5.1.4 and validity window.[10]§2.4.1.2 After validation, Salesforce creates a session cookie for the authenticated user. The assertion's job is done—it proves who logged in, but it doesn't grant access to any external Application Programming Interface (API).

A SAML assertion is an XML document. The key pieces are a subject (who is being asserted), an audience restriction (who the assertion is for), and a signature (so the SP can verify it wasn't tampered with). A minimal example:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml:Subject>
      <saml:NameID>jordan.reyes@harborpoint.example</saml:NameID>
    </saml:Subject>
    <saml:Conditions>
      <!-- The assertion is valid for 5 minutes -->
      <saml:AudienceRestriction>
        <!-- The assertion is addressed to Salesforce, not to any other service -->
        <saml:Audience>https://harborpoint.my.salesforce.com</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement>
      <!-- How the user was authenticated (password, MFA, etc.) -->
    </saml:AuthnStatement>
  </saml:Assertion>
  <!-- The IdP's signature over the assertion above -->
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
</samlp:Response>

The AudienceRestriction element is what prevents this assertion from being replayed at a different service. It is addressed to Salesforce and only Salesforce will accept it.

OAuth 2.0: delegated authorization for APIs

OAuth 2.0 answers "what is this app allowed to do at that API, possibly for which user." It enables delegated authorization: a user grants an application permission to act on their behalf without sharing their password.[3]§1 The client requests an access token from an authorization server, and the resource owner (the user) approves. The client then presents that access token to a resource server (the API) to access protected resources. Access tokens are credentials used to access protected resources,[3]§1.4 and the access token string is usually opaque to the client.[3]§1.4

OpenID Connect: authentication layer on OAuth

OIDC is a thin login layer built on top of OAuth 2.0. It adds an ID token—a security token that contains claims about the authentication of an end-user[4]§2—so the client knows who logged in. After a successful token request, the authorization server returns an ID token and an access token together.[4]§3.1.3.3 The ID token serves as proof of authentication, confirming that a user is successfully authenticated.[5]§Introduction The access token is for calling APIs; the ID token is for the client to validate the user's identity.

SAML vs. OAuth/OIDC: a mapping table

SAML 2.0 Term OAuth 2.0 / OIDC Equivalent Notes
Identity Provider (IdP) Authorization Server / OpenID Provider Issues credentials after authentication
Service Provider (SP) Client / Relying Party The app receiving credentials
SAML Assertion ID Token (a JSON Web Token, JWT) Proof that authentication happened
No SAML equivalent Access Token For calling APIs; SAML has no analog
Session Cookie Roughly a bearer credential Both allow access by possession
No SAML equivalent Refresh Token For obtaining new access tokens[3]§1.5

The four OAuth roles

OAuth 2.0 defines four roles, each with a distinct responsibility:[3]§1.1

  1. Resource Owner: An entity capable of granting access to a protected resource.[3]§1.1 Usually a person (Jordan Reyes). When the flow says "the user," it means the resource owner.
  2. Client: An application making protected resource requests on behalf of the resource owner and with its authorization.[3]§1.1 In Salesforce integrations, this is often Salesforce itself acting as a client to call Microsoft Graph or another API. The client authenticates using a client_id and client_secret, where confidential clients are typically issued a set of client credentials used for authenticating with the authorization server (for example, password or public/private key pair).[3]§2.3
  3. Authorization Server: The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.[3]§1.1 Examples: Salesforce (when issuing tokens for its own APIs), Microsoft Entra ID (the Microsoft identity platform is the authorization server[6]§Roles).
  4. Resource Server: The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.[3]§1.1 Examples: Salesforce APIs, Microsoft Graph.

Salesforce in multiple roles

Salesforce plays different roles depending on the scenario:

Verify in your org: When you create a Connected App or External Client App in Salesforce, you receive a consumer key and consumer secret. These map directly to the OAuth 2.0 terms client_id and client_secret. To confirm it yourself: in Salesforce Setup, search for App Manager, open any Connected App, and click Manage Consumer Details. The Consumer Key is what an OAuth server calls client_id; the Consumer Secret is the client_secret. These are the credentials Salesforce presents when it makes an outbound OAuth token request to an external authorization server like Microsoft Entra ID.

Three token rules

Understanding who reads which token is essential:

Rule 1: the ID token is for the client

The ID token proves authentication. Its audience (aud) claim must contain the client's client_id.[4]§3.1.3.7 The client validates the ID token to confirm the user's identity. The API never sees it.

Rule 2: the access token is for the API

The access token is for calling the API (the resource server). The API validates it; the client treats it as opaque. Client applications should treat access tokens as opaque strings and not attempt to validate them.[7]§Introduction Microsoft explicitly warns developers not to parse or validate Microsoft Graph access tokens—just present them to the API.

Rule 3: bearer tokens can be used by anyone who holds them

A bearer token is a security token with the property that any party in possession of the token can use it without demonstrating possession of a cryptographic key.[8]§1.2 This makes bearer tokens simple to use but also means protecting them from interception is critical. Clients should make authenticated requests with a bearer token using the Authorization request header field with the Bearer Hypertext Transfer Protocol (HTTP) authorization scheme.[8]§2.1

Example: SAML login into Salesforce

Let's see SAML authentication in action. Jordan Reyes clicks "Entra_SSO" on the Salesforce login page. Salesforce redirects Jordan's browser to Microsoft Entra ID, which authenticates Jordan and returns a signed SAML assertion via HTTP POST.[9]§3.5 Salesforce validates the signature using Entra's public certificate and checks the audience restriction (the assertion specifies which service provider entities are intended recipients[10]§2.5.1.4). After validation, Salesforce creates a session for Jordan.

At the end of this flow, Jordan has a Salesforce session. But Salesforce holds no token for calling Microsoft Graph.

The reason is conceptual, not just technical. SAML is not transitive. The assertion was scoped to Salesforce as its audience — it was issued specifically to prove Jordan's identity to Salesforce. It carries no Graph permissions, no Graph audience, nothing that entitles the holder to Graph data. The fact that Entra ID trusted Jordan enough to issue a Salesforce login assertion says nothing about what Jordan should be able to do at Graph. These are two separate trust decisions.

OAuth 2.0 does define a mechanism to exchange a SAML assertion for an access token (RFC 7522).[16]§2.1 But even if that worked here, it would require a different assertion — one originally scoped for Graph, with Graph as the audience and the appropriate permissions. The Salesforce SSO assertion doesn't qualify. Beyond that, Microsoft only supports this exchange for SAML version 1 tokens from Active Directory Federation Services (AD FS), not SAML 2.0 tokens from Entra ID.[17]§Important note

To call Graph on Jordan's behalf, Salesforce must run a separate OAuth flow — one that explicitly requests Graph access. The authorization code flow, shown next, is how that works.

Example: OAuth authorization code flow with OIDC

Now consider a different scenario: Salesforce needs to read Jordan's Microsoft calendar on their behalf. This requires OAuth 2.0. Salesforce uses the authorization code grant type, which is used to obtain both access tokens and refresh tokens and is optimized for confidential clients.[3]§4.1 The client directs the resource owner to the authorization endpoint via user-agent redirection,[3]§4.1.1 and then makes a request to the token endpoint to exchange the authorization code for an access token.[3]§4.1.3

Because this flow includes OIDC, the token endpoint returns three tokens: an ID token (proof of authentication), an access token (for calling Microsoft Graph), and a refresh token (for getting new access tokens).[3]§4.1.4 Each token has a different audience.

Audience: every token is addressed to someone

Tokens are not interchangeable. Each token is issued for a specific recipient, indicated by the audience (aud) claim. The aud claim identifies the recipients that the JSON Web Token (JWT) is intended for,[11]§4.1.3 and each principal intended to process the JWT must identify itself with a value in the audience claim.[11]§4.1.3

Why you can't use a SAML login to call Graph

After a SAML login, Salesforce has a local session but no token for Microsoft's APIs. OAuth 2.0 does define a way to present a SAML assertion as an authorization grant: RFC 7522 specifies using a SAML 2.0 Bearer Assertion to request an OAuth 2.0 access token,[16]§2.1 and Microsoft supports it only for SAMLv1 tokens issued by AD FS.[17]§Important note A SAML 2.0 token issued by Microsoft Entra ID cannot be exchanged for a Microsoft Graph access token.[17]§Important note To call Graph on a user's behalf, Salesforce must obtain an access token through a separate OAuth flow (such as the authorization code flow, shown next). An alternative pattern is token exchange (RFC 8693), which enables clients to request and obtain security tokens from authorization servers,[12]§1 including the On-Behalf-Of (OBO) flow, which takes an access token as input.[13]§Introduction OBO is taught in Level 4 of this course.

Verify in your org: Salesforce does not hand the SAML assertion to integrations after login.

Hands-on: anatomy of a JWT

A JSON Web Token represents a set of claims as a JSON object encoded in a JSON Web Signature (JWS) or JSON Web Encryption (JWE) structure.[11]§1 In compact serialization, a JWT consists of three Base64url-encoded parts separated by dots: the header (which identifies the cryptographic algorithm used to secure the JWS[14]§4.1.1), the payload (the claims), and the signature (which validates that the header and payload have not been tampered with). Base64url encoding uses the Uniform Resource Locator (URL)- and filename-safe character set with all trailing '=' characters omitted.[14]§2

Try decoding a real JWT in the interactive lab below. You'll see how the signature becomes invalid if you change any claim, and how only someone with the signing key can create a valid signature.

Try it in your org

See how Salesforce access tokens work in your own org.

Exercise 1: confirm that a Salesforce access token is opaque. As of recent SF CLI versions, sf org display redacts the access token. Use the dedicated command instead (replace <your-alias> with any org alias you have configured):

sf org auth show-access-token --target-org <your-alias>

Warning: This prints a live access token to your terminal. Treat it as a secret. Never paste real tokens into websites or show them on screen shares.

Look at the token. It likely starts with your 18-character org ID followed by an exclamation mark (for example, 00Dxx0000000001!…). That prefix confirms it is an opaque string, not a JWT — it has no three-part dot structure and cannot be decoded.

This token is what a client application sends to the Salesforce REST API on every protected request. The client puts the token in the HTTP Authorization header:

GET /services/data/v68.0/sobjects/Account HTTP/1.1
Host: yourorg.my.salesforce.com
Authorization: Bearer 00Dxx0000000001!…

Salesforce (acting as the resource server) receives that request, validates the token against its own token store, and — if the token is valid and the user has permission — returns the data. The client never decodes the token; it just carries it. That is what Rule 2 means: the access token is for the API, not for the client.

Exercise 2: get a real JWT and decode it. The course lab server will request a token from the Keycloak instance on your behalf — the client secret stays on the server, which is exactly the confidential client pattern. Run this command:

curl -s -X POST https://follow-the-token-lab-12063c94a91d.herokuapp.com/token/client-credentials \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])"

Notice you received a JWT without ever seeing a client secret. That is the confidential client pattern in practice — the secret lives on the server. Copy the token it prints, then decode its payload:

python3 -c "import sys, base64, json; parts = sys.argv[1].split('.'); print(json.dumps(json.loads(base64.urlsafe_b64decode(parts[1] + '==').decode()), indent=2))" "PASTE_TOKEN_HERE"

You should see claims including:

Compare this to the opaque Salesforce token from Exercise 1. The Keycloak token has three dot-separated parts and a readable payload. The Salesforce token does not. That difference is what "opaque" means.

Self-check: test your understanding

Answer these questions to confirm you've grasped the vocabulary:

Question 1 of 10: OAuth grant type and roles

You create a Connected App in Salesforce and write code that calls the token endpoint using only the client_id and client_secret — no user is prompted to log in. Which grant type are you using, and which OAuth role is your code playing?

Question 1 choices

Question 2 of 10: SAML login and calling external APIs

Jordan logs into Salesforce using SAML SSO via Microsoft Entra ID. The login succeeds and Jordan has a Salesforce session. Why can't Salesforce immediately call Microsoft Graph to read Jordan's calendar?

Question 2 choices

Question 3 of 10: ID token vs. access token

Your Salesforce integration completes an OAuth authorization code flow with Microsoft Entra ID and receives both an ID token and an access token. You call GET https://graph.microsoft.com/v1.0/me. Which token goes in the Authorization header, and which token does your Salesforce code decode and validate?

Question 3 choices

Question 4 of 10: Authentication vs. authorization

Jordan Reyes enters a username and password on the Salesforce login page, and Salesforce confirms Jordan's identity. Later, Salesforce asks Jordan to approve read access to their Microsoft calendar, and Jordan clicks "Allow." Which event is authentication, and which is authorization?

Question 4 choices

Question 5 of 10: Bearer tokens and transport security

An access token is a bearer token. An attacker intercepts one in transit over an unencrypted connection. What can the attacker do with it, and why?

Question 5 choices

Question 6 of 10: Resource owner role

A Salesforce integration wants to read files from Jordan Reyes's OneDrive. Salesforce sends Jordan to Microsoft Entra ID, where Jordan logs in and approves the request. In this OAuth flow, who is the resource owner?

Question 6 choices

Question 7 of 10: Audience claim

A client obtains an access token from Microsoft Entra ID with aud: https://graph.microsoft.com. The developer mistakenly sends this token to the Salesforce REST API instead of to Graph. What happens?

Question 7 choices

Question 8 of 10: OIDC vs. plain OAuth 2.0

A client completes a plain OAuth 2.0 authorization code flow (no OIDC) and receives only an access token. What can the client not reliably do that it could do if the flow included OpenID Connect?

Question 8 choices

Question 9 of 10: Salesforce in multiple roles

A third-party mobile app authenticates using Salesforce credentials and receives an access token from Salesforce. The app then calls GET https://yourorg.my.salesforce.com/services/data/v68.0/sobjects/Contact using that token. Which two OAuth roles is Salesforce playing simultaneously?

Question 9 choices

Question 10 of 10: SAML assertion single-use

Jordan's browser POSTs a signed SAML assertion to Salesforce. Salesforce validates it and creates a session. Five minutes later, the same assertion is POST-ed to Salesforce again. What should Salesforce do, and why?

Question 10 choices

What's next

Next: Level 1 (in development). Level 1 covers setting up per-user credentials in Salesforce, configuring Named Credentials and External Credentials, and understanding when to use client credentials vs. per-user flows.

← Back to course home

Sources

  1. RFC 4949: Internet Security Glossary, Version 2, Section 4, IETF
  2. SAML 2.0 Technical Overview, OASIS
  3. The OAuth 2.0 Authorization Framework, IETF
  4. OpenID Connect Core 1.0, OpenID Foundation
  5. ID tokens in the Microsoft identity platform, Microsoft
  6. OAuth 2.0 and OpenID Connect protocols - Microsoft identity platform, Microsoft
  7. Access tokens in the Microsoft identity platform, Microsoft
  8. The OAuth 2.0 Authorization Framework: Bearer Token Usage, IETF
  9. SAML 2.0 Bindings Specification, OASIS
  10. SAML 2.0 Core Specification, OASIS
  11. JSON Web Token (JWT), IETF
  12. OAuth 2.0 Token Exchange, IETF
  13. Microsoft identity platform and OAuth2.0 On-Behalf-Of flow, Microsoft
  14. JSON Web Signature (JWS), IETF
  15. OAuth 2.0 client credentials flow on the Microsoft identity platform, Microsoft
  16. RFC 7522: Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants, IETF
  17. Exchange a SAML token issued by AD FS for a Microsoft Graph access token, Microsoft
  18. Tutorial: Microsoft Entra SSO integration with Salesforce, Microsoft
  19. SamlSsoConfig Metadata Type, Salesforce
  20. Apex Callouts Using Named Credentials, Salesforce
  21. Get access on behalf of a user, Microsoft
  22. Microsoft Graph permissions reference, Microsoft
  23. RFC 7518: JSON Web Algorithms (JWA), Sections 3.2 and 3.3, IETF
  24. RFC 7517: JSON Web Key (JWK), Section 5, 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.