User-Agent with Social Sign-On Flow Template
OAuth 2.0 User-Agent flow combined with Social Sign-On (OIDC), where Salesforce acts as both the Authorization Provider (for the client) and the Relying Party (to the external OIDC Provider like Facebook, Google, etc.).
When to Use
- Mobile apps or SPAs requiring social login (Google, Facebook, etc.)
- When Salesforce is an intermediary between your app and social identity providers
- User-Agent flow (implicit-like) with external OIDC authentication
- Silent re-authentication scenarios (OP session cookies)
Mermaid Template
%%{init: {'theme': 'base', 'themeVariables': {
'actorBkg': '#ddd6fe',
'actorTextColor': '#1f2937',
'actorBorder': '#6d28d9',
'signalColor': '#334155',
'signalTextColor': '#1f2937',
'noteBkgColor': '#f8fafc',
'noteTextColor': '#1f2937',
'noteBorderColor': '#334155'
}}}%%
sequenceDiagram
autonumber
box rgba(165,243,252,0.3) CLIENT
participant C as 📱 Client<br/>(Mobile App)
end
box rgba(221,214,254,0.3) SALESFORCE
participant SF as ☁️ Salesforce<br/>(Auth Provider /<br/>Relying Party)
end
box rgba(254,215,170,0.3) OIDC PROVIDER
participant OP as 🔐 OIDC Provider<br/>(Google/Facebook)
end
Note over C,OP: User-Agent Flow with Social Sign-On (OIDC)
%% Phase 1: Initial Access Token Request
C->>SF: 📤 Access Token Request
Note over C,SF: GET /services/oauth2/authorize<br/>client_id, response_type=token<br/>redirect_uri, state, scope
SF->>SF: ⚙️ Check for RP session
%% Phase 2: Redirect to OIDC Provider
SF->>C: 📥 HTTP Redirect to OP
Note over SF,C: Redirect to OIDC authorize endpoint
C->>OP: 📤 Auth Code Request
Note over C,OP: GET /authorize<br/>response_type=code<br/>redirect_uri=/services/authglobalcallback<br/>scope, state
%% Phase 3: Authentication at OP
OP->>OP: ⚙️ Check for OP session
OP->>C: 📥 Display Login Page
C->>OP: 🔐 User authenticates
OP->>OP: ⚙️ Validate credentials
OP->>C: 📥 Display Consent Screen (first time only)
C->>OP: 🔐 User grants consent
OP->>OP: ⚙️ Generate authorization code
%% Phase 4: Return to Salesforce
OP->>C: 📥 HTTP Redirect to Salesforce
Note over OP,C: Redirect to /services/authglobalcallback<br/>?code=OP_AUTH_CODE&state=...
C->>SF: 📤 Deliver OP Auth Code
Note over C,SF: GET /services/authglobalcallback<br/>code=OP_AUTH_CODE, state
%% Phase 5: Salesforce exchanges code with OP
SF->>OP: 📤 Access Token Request
Note over SF,OP: POST to OP Token Endpoint<br/>client_id, client_secret<br/>code, redirect_uri, state
OP->>OP: ⚙️ Validate client & code
OP-->>SF: 📥 Access Token Response
Note over OP,SF: id_token (JWT)<br/>access_token<br/>refresh_token
SF->>SF: 🔐 Verify ID token signature
%% Phase 6: Optional UserInfo
rect rgba(248,250,252,0.5)
Note over SF,OP: Optional: UserInfo Endpoint
SF->>OP: 📤 Request User Information
Note over SF,OP: POST /userinfo<br/>Authorization: Bearer ACCESS_TOKEN
OP-->>SF: 📥 User Info Response
Note over OP,SF: User claims (email, name, etc.)
SF->>SF: 🔐 Validate sub matches ID token
end
%% Phase 7: Salesforce User Provisioning
SF->>SF: ⚙️ Invoke registration handler<br/>to create/update user
%% Phase 8: User Authorization for Salesforce
SF->>C: 📥 Display Salesforce Consent
Note over SF,C: "App requests:<br/>• API Access<br/>• Refresh Token"
C->>SF: 🔐 User grants Salesforce consent
%% Phase 9: Return tokens to Client
SF->>C: 📥 Redirect to Client Callback
Note over SF,C: Redirect URI with:<br/>access_token (Salesforce)<br/>refresh_token<br/>instance_url
C->>C: ⚙️ Store Salesforce tokens
%% Phase 10: API Usage
C->>SF: 📤 Use Salesforce APIs
Note over C,SF: Authorization: Bearer SF_ACCESS_TOKEN
SF-->>C: ✅ API Response
Note over C,SF: ⚠️ OP session cookie enables<br/>silent re-auth (~15 min)
ASCII Fallback Template
┌────────────────┐ ┌────────────────────┐ ┌─────────────────────┐
│ Client │ │ Salesforce │ │ OIDC Provider │
│ (Mobile App) │ │ (Auth/RP Server) │ │ (Google/Facebook) │
└───────┬────────┘ └─────────┬──────────┘ └──────────┬──────────┘
│ │ │
│ 1. Access Token Req │ │
│ (response_type= │ │
│ token) │ │
│───────────────────────>│ │
│ │ │
│ 2. Redirect to OP │ │
│<───────────────────────│ │
│ │ │
│ 3. Auth Code Request (response_type=code) │
│────────────────────────────────────────────────────>│
│ │ │
│ 4. Login Page │
│<────────────────────────────────────────────────────│
│ │ │
│ 5. Enter Credentials (authenticate) │
│────────────────────────────────────────────────────>│
│ │ │
│ 6. Consent Screen (first time) │
│<────────────────────────────────────────────────────│
│ │ │
│ 7. Grant Consent │
│────────────────────────────────────────────────────>│
│ │ │
│ 8. Redirect with ?code=OP_AUTH_CODE │
│<────────────────────────────────────────────────────│
│ │ │
│ 9. Deliver OP Code │ │
│───────────────────────>│ │
│ │ │
│ │ 10. POST Token Request │
│ │ (code, secret) │
│ │──────────────────────────>│
│ │ │
│ │ 11. ID Token + Access │
│ │ Token Response │
│ │<──────────────────────────│
│ │ │
│ │ [Optional: UserInfo] │
│ │ 12. GET /userinfo │
│ │──────────────────────────>│
│ │ │
│ │ 13. User Claims │
│ │<──────────────────────────│
│ │ │
│ │ 14. Registration Handler │
│ │ (create/update user) │
│ ├─────────────┐ │
│ │ │ │
│ │<────────────┘ │
│ │ │
│ 15. SF Consent Screen │ │
│<───────────────────────│ │
│ │ │
│ 16. Grant SF Consent │ │
│───────────────────────>│ │
│ │ │
│ 17. Redirect with │ │
│ SF Access Token │ │
│ + Refresh Token │ │
│<───────────────────────│ │
│ │ │
│ 18. Call SF APIs │ │
│───────────────────────>│ │
│ │ │
│ 19. API Response ✅ │ │
│<───────────────────────│ │
Key Concepts
Dual Role of Salesforce
| Role |
Context |
Responsibility |
| Authorization Provider |
OAuth flow with Client |
Issues access tokens to your app |
| Relying Party (RP) |
OIDC flow with Social Provider |
Consumes ID tokens from Google/Facebook |
Authentication Endpoints
| System |
Endpoint |
Purpose |
| Salesforce Auth |
/services/oauth2/authorize |
Start User-Agent flow |
| Salesforce Callback |
/services/authglobalcallback |
Receive OP auth code |
| Salesforce Token |
/services/oauth2/token |
(Not used in User-Agent) |
| OP Authorization |
Provider-specific |
/authorize endpoint |
| OP Token |
Provider-specific |
Exchange code for tokens |
| OP UserInfo |
Provider-specific |
Get user profile claims |
Security Considerations
- OP Session Cookies - Enable silent re-authentication (~15 min intervals)
- ID Token Validation - Salesforce verifies JWT signature from OP
- Sub Claim Matching - UserInfo
sub must match ID token sub
- State Parameter - CSRF protection between all parties
- Registration Handler - Custom Apex to map OP user to Salesforce User
Salesforce Configuration
Auth. Provider Setup
Setup → Auth. Providers → New
├── Provider Type: OpenID Connect (or specific: Google, Facebook)
├── Consumer Key: [From OP Developer Console]
├── Consumer Secret: [From OP Developer Console]
├── Authorize Endpoint: https://provider.com/authorize
├── Token Endpoint: https://provider.com/token
├── User Info Endpoint: https://provider.com/userinfo (optional)
└── Registration Handler: [Your Apex Class]
Registration Handler Example
public class SocialLoginHandler implements Auth.RegistrationHandler {
public User createUser(Id portalId, Auth.UserData data) {
// Map social identity to Salesforce User
User u = new User();
u.Username = data.email + '.social';
u.Email = data.email;
u.FirstName = data.firstName;
u.LastName = data.lastName;
// ... additional mapping
return u;
}
public void updateUser(Id userId, Id portalId, Auth.UserData data) {
// Update existing user on subsequent logins
User u = [SELECT Id FROM User WHERE Id = :userId];
u.Email = data.email;
update u;
}
}
Token Types
| Token |
Issued By |
Purpose |
| OP Auth Code |
OIDC Provider |
Short-lived, exchanged by SF |
| OP ID Token |
OIDC Provider |
JWT with user identity claims |
| OP Access Token |
OIDC Provider |
Used by SF to call OP UserInfo |
| SF Access Token |
Salesforce |
Used by Client to call SF APIs |
| SF Refresh Token |
Salesforce |
Long-lived, refresh SF access |
Customization Points
Replace these placeholders:
CLIENT_ID → Your Connected App's Consumer KeyCALLBACK_URL → Your registered callback URLOP_CLIENT_ID → Consumer Key from Social ProviderOP_CLIENT_SECRET → Consumer Secret from Social Provider
Reference
tools-only