OAuth 2.0 Hybrid User-Agent Token Flow for Web Session Management
Use the OAuth 2.0 hybrid user-agent token flow to give hybrid apps direct management of web sessions. When the authorizing server grants an access token, it includes session IDs (SID) for the requested domains in its response. After authorization, the hybrid app can set Lightning, Visualforce, and content domain cookies and bridge an access token into a web session, providing uninterrupted service.
Required Editions
| Available in: both Salesforce Classic and Lightning Experience |
| Available in: All Editions |
The hybrid user-agent token flow follows the same authorization steps used in the user-agent flow, with the exception that the hybrid user-agent token
flow uses hybrid_token as its grant type. For example,
you build a hybrid app for your sales department to access information on the go, including
a dashboard that tracks top sales prospects. This app implements the hybrid user-agent token
flow, which follows these steps.
- To integrate the hybrid app with the Salesforce API, create an external client app. Enable OAuth settings and assign these OAuth scopes to the external client app:
-
-
lightning -
content -
refresh_token -
visualforce -
web
-
- The end user opens the app and is directed to Salesforce to authenticate and authorize the app.
- After the user approves access for this authorization flow, the external client app receives the callback from Salesforce to the redirect URL, which extracts the access and refresh tokens. The Visualforce, Lightning, and content SIDs for the respective domains are also included, along with session cookies that allow the app to directly bridge a web session.
- The app sets the Lightning, Visualforce, and content domains’ session cookies and bridges an access token into a web session.
- The user can access the top sales prospects dashboard without interrupted sessions.
Here’s the breakdown of each step of the OAuth 2.0 hybrid app flow.
- Create an external client app for the hybrid app.
- The app redirects uses to the authorization endpoint.
- The user authenticates and authorizes access.
- Salesforce grants the access token and requested scopes.Note The hybrid user-agent flow can issue only opaque access tokens. It doesn't support JWT-based access tokens.
- The app directly sets the SIDs in the domains’ session cookies and bridges a web session.
Redirection to Authorization Endpoint
To get a user’s authorization to access Salesforce data, the app redirects the user to the authorization endpoint. Here’s an example HTTP redirection.
https://login.salesforce.com/services/oauth2/authorize?response_type=hybrid_token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuDZrXcPCmBv4o.8ds.5iE&
redirect_uri=https%3A%2F%2Flogin.salesforce.com%2Fservices%2Foauth2%2Fsuccess&scope=web%20visualforce%20refresh_token%20lightning%20content
Include these parameters in the URL.
| Parameter | Description |
|---|---|
| OAuth 2.0 authorization endpoint | The Salesforce instance’s OAuth 2.0 authorization endpoint. External client apps send OAuth authorization requests to this endpoint. |
client_id
|
The consumer key of the external client app. To access the consumer key, from the External Client App Manager, find the external client app and select Edit Settings from the dropdown. Then expand the OAuth Settings section and click Consumer Key and Secret. You're sometimes prompted to verify your identity before you can view the consumer key. |
redirect_uri
|
The URL where users are redirected after a successful authentication. The redirect URI must match one of the values in the external client app’s Callback URL field. Otherwise, the approval fails. You can find the redirect URI on the external client app’s OAuth Settings page. This value must be URL encoded. |
response_type
|
Use the hybrid_token value. You can also
use the token id_token value, with the
openid scope and a nonce parameter. If you specify token id_token, Salesforce returns an ID token in
the response. For more information, see OAuth Tokens and Scopes. |
These parameters are optional.
| Parameter | Description |
|---|---|
scope
|
Permissions that define the type of protected resources an external client app can access. You assign scopes to an external client app when you build it, and they’re included with the OAuth tokens during the authorization flow. If you don’t include this parameter, all scopes assigned to the external client app are requested. The scopes passed in this parameter must be a subset of the registered scopes. For valid parameters, see OAuth Scopes. For this flow, assign
the
|
state
|
Any state that the external web service requests to be sent to the callback URL. This value must be URL encoded. |
display
|
Changes the display type of the login and authorization pages. Salesforce supports these values.
|
login_hint
|
Provides a valid username value to prepopulate the login page with the
username, such as To pass the |
nonce
|
Use with the openid scope to request a
user ID token. The user ID token is returned in the response. This parameter is
optional, but it helps to detect replay attacks. |
prompt
|
Specifies how the authorization server prompts the user for reauthentication and reapproval. Salesforce supports these values.
You can pass |
Users Authenticates and Authorizes Access
The user logs into Salesforce with their credentials. The user interacts with the authorization endpoint directly, so the app never sees the user’s credentials.
After a successful login, Salesforce redirects users to the approval page to grant access to the app.
Salesforce Grants Access Token and Requested Scopes
After a user approves access to the app, Salesforce redirects the user to the callback URL. Included in the redirection is the granted access token, requested domain names, domain sessions, and associated scopes. The external client app extracts the token and parameters to access the scoped resources on the end user’s behalf.
Here’s an example of the callback from the server. The response is behind a hash tag (#), rather than as HTTP query parameters.
https://www.customercontactinfo.com/user_callback.jsp#
access_token=yourtokenhere&
refresh_token=yourtokenhere&
instance_url=https://yourInstance.salesforce.com/
id=https://user.internal.salesforce.com/7443%2Fid%2F00Dxx0000006HM7EAM%2F005xx000001X8ErAAK&
issued_at=1604004352722&
signature=DcQ84..
content_domain=MyDomainName.file.force.com&
content_sid=00Dxx0000006Gb…&
lightning_domain=MyDomainName.lightning.force.com&
lightning_sid=00Dxx000000...&
visualforce_domain=MyDomainName.file.force.com&
visualforce_sid=00Dxx000000...&
sidCookieName=sid&
cookie-sid_Client=0000000...&
cookie-clientSrc=10.xxx.xx.xx&
csrf_token=eyJub...&
scope=web+visualforce+refresh_token+lightning+content&
token_type=Bearer
The response in the example contains these parameters following the hash tag (#). The external client app’s callback URL precedes the hash tag (#).
| Parameter | Description |
|---|---|
access_token
|
OAuth token that an external client app uses to request access to a protected resource on behalf of the client application. Additional permissions in the form of scopes can accompany the access token. |
refresh_token
|
Token obtained from the web server, user-agent, or hybrid app token flow. This value is a secret. Take appropriate measures to protect it. The refresh
token for the hybrid user-agent token flow is only issued if you requested
The refresh token granted in this flow is fully compatible with the standard OAuth refresh token flow. |
instance_url
|
A URL indicating the instance of the user’s org. For example: https://yourInstance.salesforce.com/. |
id
|
An identity URL that can be used to identify the user and to query for more information about the user. See Identity URLs. |
issued_at
|
Time stamp of when the signature was created in milliseconds. |
signature
|
Base64-encoded HMAC-SHA256 signature signed with the client_secret. The signature can include the
concatenated ID and issued_at value, which you
can use to verify that the identity URL hasn’t changed since the server sent
it. |
scope
|
The scopes associated with the access token. Scopes further define the type of protected resources that the client can access. You assign scopes to an external client app when you build it, and they’re included with the OAuth tokens during the authorization flow. For valid parameters, see OAuth Scopes. |
content_domain
|
The domain of the content session, which maps to the content SID: You receive this value only if you assign the
|
content_sid
|
The SID associated with the domain of the content session. Salesforce returns a unique SID that the hybrid app directly sets in the domain’s session cookie. You receive this value only if you assign the |
lightning_domain
|
The domain of the Lightning session, which maps to the Lightning SID:
You receive this value only if you assign the
|
lightning_sid
|
The SID associated with the domain of the Lightning session. Salesforce returns a unique SID that the hybrid app directly sets in the domain’s session cookie. You receive this value only if you assign the |
visualforce_domain
|
The domain of the Visualforce session, which maps to the Visualforce SID:
You receive this value only if you assign the |
visualforce_sid
|
The SID associated with the domain of the Visualforce session. Salesforce returns a unique SID that the hybrid app directly sets in the domain’s session cookie. You receive this value only if you assign the |
token_type
|
A Bearer token type, which is used for
all responses that include an access token. |
csrf_token
|
The cross-site request forgery (CSRF) token to prevent attacks during child sessions. You receive this value only if you assign the |
sidCookieName
|
The name of the session cookie that the hybrid app uses to directly bridge a
web session. The default value is sid. |
cookie-sid_Client
|
A session cookie that detects and prevents session tampering. This session cookie allows the hybrid app to directly bridge a web session. |
cookie-clientSrc
|
A session cookie that is used for security protections. This session cookie allows the hybrid app to directly bridge a web session. |
The response can also contain these parameters.
| Parameter | Description |
|---|---|
id_token
|
A signed data structure that contains authenticated user attributes, including a unique identifier for the user and a timestamp indicating when the token was issued. It also identifies the requesting client app. See OpenID Connect specifications. This parameter is
returned if the scope parameter includes |
sfdc_site_url
|
If the user is a member of an Experience Cloud site, the site URL is provided. |
sfdc_site_id
|
If the user is a member of an Experience Cloud site, the user’s site ID is provided. |
App Sets Domain SIDs and Bridges a Web Session
The hybrid app sets the domains’ associated SIDs in the session cookies to directly bridge a web session. For examples of the cookies that are set for each domain, see OAuth 2.0 Hybrid App Flow Cookie Management.
For implementations that are resetting user division on objects for the Reset to Default Division on Login setting, the hybrid app must bridge a web session using frontdoor.jsp. For more information, see Using Frontdoor.jsp to Bridge Sessions into Salesforce. To learn more about user divisions, see Organize Data with Divisions.
