OAuth 2.0 User-Agent Flow for Desktop or Mobile App Integration
With the OAuth 2.0 user-agent flow, users authorize a desktop or mobile app to access data by using an external or embedded browser. Client apps running in a browser using a scripting language such as JavaScript can also use this flow. This flow uses the OAuth 2.0 implicit grant type.
Required Editions
| Available in: both Salesforce Classic and Lightning Experience |
| Available in: All Editions |
With the user-agent flow, the external client app, which integrates the client application with the Salesforce API, receives the access token as an HTTP redirection. The external client app requests that the authorization server redirects the user-agent to a web server or to an accessible local resource. The web server can extract the access token from the response and pass it to the external client app. For security, the token response is provided as a hash tag (#) fragment on the URL. This format prevents the token from being passed to the server or to any other servers in referral headers.
For example, you use Salesforce Mobile SDK to build a mobile app that looks up customer contact information from your Salesforce org. Mobile SDK implements the OAuth 2.0 user-agent flow for your external client app, integrating the mobile app with your Salesforce API and giving it authorized access to the defined data. The flow follows these steps.
- The user opens the mobile app.
- The external client app directs the user to Salesforce to authenticate and authorize the mobile app.
- 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 external client app uses the access token to access data on the user’s behalf.
Redirection to Authorization Endpoint
To get a user’s authorization to access Salesforce data, the external client app redirects the user to the authorization endpoint. Here’s an example HTTP redirection.
https://login.salesforce.com/services/oauth2/authorize?response_type=token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuDZrXcPCmBv4o.8ds.5iE&
redirect_uri=https://www.customercontactinfo.com/user_callback.jspk&
state=mystateInclude 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 App Manager, find the external client app and select View from the dropdown. Then click Manage Consumer Details. 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 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. |
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 |
prompt
|
Specifies how the authorization server prompts the user for reauthentication and reapproval. Salesforce supports these values.
You can pass |
sso_provider
|
The developer name of a single sign-on (SSO) identity provider configured with a My Domain login URL or Experience Cloud site URL. You can use this parameter to create an SSO experience that feels like your app is integrated with the SSO provider. For example, you can use this parameter to offer SSO in a Headless Identity implementation. For more information, see Create a Native Single Sign-On Experience in Your App. |
User Authenticates and Authorizes Access
The user logs into Salesforce with their credentials. The user interacts with the authorization endpoint directly, so the application 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
After a user approves access to an external client app, Salesforce redirects the user to the callback URL. Included in the redirection is the granted access token, which the external client app can extract and use to access data on the 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=00Dx0000000BV7z%21AR8AQBM8J_xr9kLqmZIRyQxZgLcM4HVi41aGtW0qW3JCzf5xd
TGGGSoVim8FfJkZEqxbjaFbberKGk8v8AnYrvChG4qJbQo8&
refresh_token=5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xReb54_pZfVti1dPEk8aimw4Hr9ne7VXXVSIQ%3D%3D&
instance_url=https://yourInstance.salesforce.com&
id=https://login.salesforce.com%2Fid%2F00Dx0000000BV7z%2F005x00000012Q9P&
issued_at=1278448101416&
signature=miQQ1J4sdMPiduBsvyRYPCDozqhe43KRc1i9LmZHR70%3D&
scope=id+api+refresh_token&
token_type=Bearer&
state=mystateThe 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 user-agent flow is only issued if you requested
|
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. |
token_type
|
A Bearer token type, which is used for all
responses that include an access token. |
state
|
The state requested by the client. This value is included only if the state parameter is included in the original query
string. |
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. |
