OAuth 1.0.A has a single authentication flow.
|Available in: both Salesforce Classic and Lightning Experience|
|Available in: All Editions|
|To manage, create, edit, and delete OAuth applications:||“Manage Connected Apps”|
The following diagram displays the authentication flow steps for OAuth 1.0.A. The individual step descriptions follow.
- The consumer requests a RequestToken. Salesforce verifies the request and returns a request token.
- The consumer redirects the user to Salesforce, where the user is prompted to log in.
authorizes the user.
- Once the user is authorized, the consumer requests an AccessToken.
- Salesforce verifies the request and grants the token.
- After the token is granted, the consumer accesses the data either through their application or through the Force.com Web services API.
- Salesforce verifies the request and allows access to the data.
The following sections go into more details about each of these steps.
To use a connected app with a sandbox
, use test.salesforce.com
instead of login.salesforce.com
in the following sections.
For the list of possible error codes returned by Salesforce, see OAuth 1.0.A Error Codes.
Requesting a RequestToken
When a consumer makes an initial request to Salesforce and the request is valid, a RequestToken is returned. The following steps contain more detail for the developer who is using a connected app to request Salesforce data.
- A consumer application has to access Salesforce data and sends a request to https://login.salesforce.com/_nc_external/system/security/oauth/RequestTokenHandler. The request contains the following:
- A valid request for a RequestToken, which contains the following OAuth parameters.
- oauth_signature_method—must be HMAC-SHA1.
- oauth_version—optional, must be “1.0” if included
- oauth_callback—must be one of the following:
- URL hosted by the consumer, for example, https://www.appirio.com/sfdc_accounts/access_token_ready.html. This URL uses https or another protocol. It can’t use http.
- oob, meaning out of band.
- A signature created according to the OAuth specification for HMAC-SHA1.
- After Salesforce receives the request, Salesforce:
- Validates the request with its own copy of the consumer secret
- Generates a response containing RequestToken and RequestTokenSecret in the HTTP body as name/value pairs
- Sends the response back to the consumer
A RequestToken is only valid for 15 minutes, plus three minutes to allow for differences between machine clocks.
- The consumer directs the user to a Salesforce login page, as specified in the next section.
After the request from the consumer is made to Salesforce, Salesforce has to authenticate the user before the process continues. The following contains more detailed steps about the login procedure for developers who are using a connected app to request Salesforce data.
- The consumer redirects the user to the following location, where they are prompted to log in: https://login.salesforce.com/setup/secur/RemoteAccessAuthorizationPage.apexp. The appropriate GET query parameters are appended to this URL.
- oauth_token – the RequestToken
If an oauth_callback
parameter is included, it is ignored.
- The Remote Access Authorization page displays.
- If the user approves access for the consumer, Salesforce generates the AccessToken and AccessTokenSecret.
The number of concurrent access tokens that a user can grant to an application is limited. The default is five per application per user. If this authorization exceeds the org’s limit, the user is notified that the authorization automatically revokes the token or tokens for this application that haven't been used for the longest period.
- Salesforce verifies the callback URL (either specified in the connected app definition pages or in the oauth_callback parameter from the previous stage). One of the following redirections occurs.
- If the oauth_callback defined in the RequestToken is oob and the Callback URL field in the connected app definition page has a valid value, the user is redirected to that URL.
- If the oauth_callback defined in the RequestToken is a valid URL, the user is redirected to that URL.
- The consumer is notified that the AccessToken and AccessTokenSecret are available. The consumer receives either the verification token from Salesforce or the validation code from the end user.
Requesting the AccessToken
Once the user has been authenticated, the consumer can exchange a RequestToken for an AccessToken. The following contains more detailed steps regarding the exchange of tokens for developers who are using a connected app to request Salesforce data.
- The consumer makes an HTTPS GET or POST request to https://login.salesforce.com/_nc_external/system/security/oauth/AccessTokenHandler, with the required parameters in the query or post data.
- oauth_version—optional, must be “1.0” if included
- Salesforce validates the following elements.
- The consumer secret
- The consumer key
- The signature
- That the RequestToken has never been used before
- The timestamp (must be within 15 minutes, plus three minutes to allow for differences between machine clocks)
- That the nonce has never used before
- Upon validation, Salesforce returns the AccessToken and AccessTokenSecret in the HTTP response body as name/value pairs.
Generating oauth_signature for Login
You can access Salesforce using either the user interface, or using the API. The oauth_signature used for login is generated differently, depending on which method you use.
- User interface—use https://login.salesforce.com for generating the signature
- API—use https://login.salesforce.com/services/OAuth/type/api-version for generating the signature.
For example, https://login.salesforce.com/services/OAuth/u/17.0.
must have one of the following values.
- u—Partner WSDL
- c—Enterprise WSDL
Accessing Salesforce Data Using the Consumer Application
Once the consumer possesses a valid AccessToken, a connected app can request to access Salesforce data. The following contains more detailed steps regarding accessing data for developers who are using a connected app to request Salesforce data.
- The consumer makes an HTTPS POST request to https://login.salesforce.com, with the required parameters in the authorization header.
- oauth_version (optional, must be “1.0” if included)
- Salesforce validates the request and sends a valid session ID to the consumer. The session ID is short-lived and is valid only for frontdoor.jsp. To obtain a session ID that can be used directly, use the API access token exchange.
Accessing Salesforce Data Using the API
Once the consumer possesses a valid AccessToken, a connected app can request to access Salesforce data using the Force.com Web services API.
Your organization must have access to both the API and to the connected app. Contact your Salesforce representative for more information.
The following contains more detailed steps regarding accessing data for developers who are using a connected app to request Salesforce data.
- The consumer makes an HTTPS POST request to Salesforce.
- Salesforce validates the request and sends a valid session ID to the consumer. The response header includes the following.