OAuth
OAuth is the open-standard authorization framework Salesforce uses to grant external applications access to its APIs without sharing user passwords.
Definition
OAuth is the open-standard authorization framework Salesforce uses to grant external applications access to its APIs without sharing user passwords. OAuth 2.0 is the version Salesforce supports across REST API, SOAP API, Bulk API 2.0, Streaming API, Pub/Sub API, and Lightning Out. Every modern Salesforce integration starts with an OAuth flow that exchanges credentials for an access token, then uses that token as a bearer credential on subsequent API calls.
Salesforce implements OAuth through Connected Apps, which act as the OAuth client configuration. The Connected App stores the client ID, client secret, allowed scopes, callback URLs, and security policies. The user (or admin pre-authorization) grants the app permission, the platform issues an access token, and the app uses the token to call the Salesforce APIs as that user. Salesforce supports several OAuth flows tailored to different integration patterns: Web Server flow for interactive user redirects, JWT Bearer flow for headless server integrations, Client Credentials flow for service accounts, User-Agent flow for SPAs, and Device flow for input-constrained devices.
How OAuth handles authentication for Salesforce integrations
The five common OAuth flows
Web Server flow is the classic user-facing pattern: user clicks Connect, redirects to Salesforce, approves the app, redirects back with an authorization code, server exchanges code for tokens. JWT Bearer flow is the headless server pattern: app signs a JWT with a private key, exchanges it for an access token, no user involvement. Client Credentials flow (newer) is for service accounts: app trades its credentials for an access token without any user context. User-Agent flow is for SPAs and mobile apps with no backend. Device flow is for smart TVs and similar input-constrained devices. Each fits different integration architectures.
Access tokens, refresh tokens, and token lifetimes
OAuth issues two tokens. The access token is short-lived (typically 2 hours) and used as the Authorization: Bearer header on every API call. The refresh token is long-lived (configurable, typically months) and used to obtain a new access token without re-authenticating. The Connected App configures both lifetimes and the maximum number of refresh tokens that can exist simultaneously. Mishandling token storage is the most common security incident pattern: refresh tokens are essentially long-term credentials and need to be protected accordingly.
Scopes: what the token is allowed to do
OAuth scopes are permission flags that constrain what an access token can do. The common scopes: api (call REST/SOAP APIs), refresh_token (obtain refresh tokens for offline access), full (everything), openid (OpenID Connect identity claims), custom_permissions (user''s custom permissions), web (use the API on behalf of the user via web redirect), id (user identity), profile, email, address, phone (OpenID Connect profile claims). Pick the minimum scopes the integration needs; broader scopes increase blast radius if credentials leak.
PKCE for public clients
Mobile apps and SPAs cannot safely store Connected App secrets because the client code is distributed to user devices. PKCE (Proof Key for Code Exchange) is the OAuth extension that secures the authorization code flow without requiring a secret. The client generates a random verifier, hashes it as a challenge, sends the challenge during authorization, and proves possession of the verifier during code exchange. This makes intercepted authorization codes useless without the verifier. Modern mobile and SPA integrations should always use PKCE.
Pre-authorization, IP relaxation, and session policies
Connected Apps have policies that gate OAuth access. Permitted Users: Admin approved users are pre-authorized (recommended for production) versus All users may self-authorize (lower control). IP Relaxation: Enforce IP restrictions (default) versus Relax (necessary for cloud integrations outside trusted IPs). Session policies override the org default for tokens issued through this Connected App, supporting High Assurance session requirements for sensitive integrations. These policies are the security envelope around OAuth tokens.
OpenID Connect: identity on top of OAuth
OAuth handles authorization (what the app can do). OpenID Connect (OIDC) is the identity layer built on top of OAuth that handles authentication (who the user is). When the OAuth request includes the openid scope, Salesforce returns an id_token (a JWT containing user claims) alongside the access token. The id_token lets the application verify the user identity without making additional API calls. SSO scenarios with Salesforce as the identity provider use OIDC; SAML is the alternative identity protocol for legacy SSO.
Monitoring, revocation, and audit
Setup > Connected Apps OAuth Usage shows recent token grants and active sessions per Connected App. Revoking an OAuth token invalidates it immediately; the next API call returns 401. Revoking the Connected App revokes all tokens for that app. Setup Audit Trail logs every Connected App change. Setup > Login History tracks API logins by source IP and Connected App. Build alerting on unusual usage patterns (new IPs, unexpected scope usage) because OAuth tokens are the most common attack vector for credential-based incidents.
How to use OAuth with Salesforce
Implementing OAuth with Salesforce has three layers: configure the Connected App, pick the right OAuth flow, and implement the token exchange in your application code. The Connected App configuration is the security envelope; the flow choice fits the integration architecture; the token exchange is mostly handled by SDKs. Build with a tested OAuth library rather than rolling raw HTTP.
- Pick the OAuth flow that matches your integration
Web Server for user-facing web apps. JWT Bearer for headless server integrations. Client Credentials for service accounts. User-Agent with PKCE for mobile and SPA. Device flow for input-constrained devices. The choice constrains every other config step.
- Create a Connected App
Setup > App Manager > New Connected App. Configure OAuth settings: callback URLs, scopes, certificate (for JWT Bearer). Save and capture the Consumer Key and Consumer Secret in a secrets manager, never in source code.
- Set Permitted Users and IP Relaxation
Admin approved users (pre-authorized profiles or permission sets) is the standard for production. Enforce IP restrictions unless the integration genuinely needs to call from cloud IPs outside the trusted range.
- Implement the token exchange
Use a tested OAuth library or SDK (Salesforce ships SDKs for Node, Python, Java, .NET). Construct the authorization URL or JWT, exchange for an access token, store securely. The SDK handles retry, refresh, and error semantics.
- Make API calls with the access token
Set Authorization: Bearer ACCESS_TOKEN on every API request. The token authenticates the call. Refresh on 401 responses using the refresh token. Most SDKs handle the refresh transparently.
- Store refresh tokens securely
Refresh tokens are long-lived credentials. Store them encrypted at rest in a secrets manager, the user''s OS keychain, or an encrypted database column. Never embed in source code.
- Implement revocation handling
Build a logout flow that revokes the OAuth token via /services/oauth2/revoke. When users disconnect the integration, revoke their tokens promptly. Stale tokens after disconnect are a common audit finding.
- Monitor OAuth usage for anomalies
Setup > Connected Apps OAuth Usage. Watch for new IPs, unexpected scope grants, or unusual hours. Pair with Setup Audit Trail for change history. Set up alerts for spikes in OAuth-failure rates.
Web Server, JWT Bearer, Client Credentials, User-Agent (with PKCE), or Device. Pick based on integration architecture.
Permission flags constraining what the access token can do. Pick the minimum the integration needs to limit blast radius.
Access token typically 2 hours; refresh token lifetime configurable. Adjust based on integration security requirements.
- Refresh tokens are long-lived credentials. Storing them in source code, plain-text config files, or unencrypted databases is a security incident waiting to happen.
- Callback URLs must match exactly during OAuth handshakes. Trailing slashes, case differences, and protocol mismatches (http versus https) produce mysterious OAuth failures.
- Asking for the full scope is broader than most integrations need. Stick to api, refresh_token, and openid for typical cases. full grants administrative access and inflates blast radius if leaked.
- Mobile apps and SPAs should use PKCE, not raw client secrets. Embedded secrets in distributed code are trivially extractable from the app bundle.
- Tokens expire. Implement refresh handling for the 401 case; without it, integrations randomly fail when access tokens reach the 2-hour lifetime.
Related free tool
Trust & references
Cross-checked against the following references.
- OAuth Authorization FlowsSalesforce Help
- Connected Apps OverviewSalesforce Help
- OpenID Connect OverviewSalesforce Help
Straight from the source - Salesforce's reference material on OAuth.
- OAuth Web Server FlowSalesforce Help
- OAuth JWT Bearer FlowSalesforce Help
- OAuth Client Credentials FlowSalesforce Help
Hands-on resources to go deeper on OAuth.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is OAuth in Salesforce?
Q2. What are some OAuth flows?
Q3. Why is OAuth better than password-based auth?
Discussion
Loading discussion…