OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supersedes the work done on the original OAuth protocol created in 2006. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.
OAuth (Open Authorization) is an open protocol that provides secure API authorization from applications in a simple and standardized way. OAuth can authorize access to resources without revealing user credentials to apps. Apps that use OAuth can also directly authenticate and access Salesforce resources without a user present.
An OAuth token is the valet key that authorizes access to resources. Here’s a quick review of the different OAuth 2.0 token types.
—The authorization server creates this short-lived token and passes it to the client application via the browser. The client application sends the authorization code to the authorization server to obtain an access token and, optionally, a refresh token.
—The client uses an access token to make authenticated requests on behalf of the end user. It has a longer lifetime than the authorization code, usually minutes or hours. When an access token expires, attempts to use it fail, and the app must obtain a new access token. In Salesforce terms, the access token is a session ID (SID), much like a session cookie on other systems. It must be protected against interception, for example, by Transport Layer Security (TLS, also called SSL). To use an OAuth access token to access the Salesforce web UI on behalf of a user, you can either set a SID cookie or use a “front door” URL (such as https://mydomain.salesforce.com/secur/frontdoor.jsp?sid=<sid_value>). In both cases, you must include “web” in the list of requested scopes. For parameter details, see Scope Parameter Values.
—A refresh token can have an indefinite lifetime, persisting for an admin-configured interval or until explicitly revoked. The client application can store a refresh token, using it to periodically obtain fresh access tokens. For this reason, the app must protect a refresh token against unauthorized access. Like a password, a refresh token can be used repeatedly to gain access to the resource server. Because a refresh token can expire or a user can revoke it outside of the client, the client must handle failures to obtain an access token. Typically, the client replays the protocol from the start.
—OpenID Connect, an authentication layer on top of OAuth 2.0, defines an ID token as a signed data structure. The data structure contains authenticated user attributes (including a unique identifier for the user), the time when the token was issued, and an identifier for the requesting client. An ID token is encoded as a JSON web token (JWT).
Understanding the Web Server OAuth Authentication Flow
The web server authentication flow is used by apps that are hosted on a secure server. A critical aspect of the web server flow is that the server must be able to protect the consumer secret. You can use code challenge and verifier values in the flow to prevent authorization code interception.
In this flow, the client application requests the authorization server to redirect the user to another web server or resource that authorizes the user and sends the application an authorization code. The application uses the authorization code to request an access token. The following shows the steps for this flow.
- The application redirects the user to the appropriate Salesforce authorization endpoint, such as https://login.salesforce.com/services/oauth2/authorize. The following parameters are required:
There are certain other optional parameters as listed below.
Let’s look at an example authorization URL
- The user logs into Salesforce with their credentials. The user is interacting with the authorization endpoint directly, so the application never sees the user’s credentials. After successfully logging in, the user is asked to authorize the application. Note that if the user has already authorized the application, this step is skipped.
- After Salesforce confirms that the client application is authorized, the end-user’s Web browser is redirected to the callback URL specified by the redirect_uri parameter. Salesforce appends authorization information to the redirect URL with the following values:
Now, let’s look at an example callback URL
with authorization information.
- The application extracts the authorization code and passes it in a request to Salesforce for an access token. This request is a POST request sent to the appropriate Salesforce token request endpoint, such as https://login.salesforce.com/services/oauth2/token.
Let’s now see an example access token POST request
POST /services/oauth2/token HTTP/1.1Host: login.salesforce.comgrant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZVEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=1955279925675241571&redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp
- If this request is successful, the server returns a JSON response body might look something like:
- The application uses the provided access token and refresh token to access protected user data.