Understanding the Web Server OAuth Authentication Flow

The Web server authentication flow is used by applications 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.

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:

Parameter	Description
`response_type`	Must be `code` for this authentication flow.
`client_id`	The Consumer Key from the remote access application definition.
`redirect_url`	The Callback URL from the remote access application definition.

The following parameters are optional:

Parameter	Description
`display`	Changes the login page’s display type. Valid values are: `page`—Full-page authorization screen. This is the default value if none is specified. `popup`—Compact dialog optimized for modern Web browser popup windows. `touch`—Mobile-optimized dialog designed for modern smartphones such as Android and iPhone. `mobile`—Mobile optimized dialog designed for smartphones such as BlackBerry OS 5 that don’t support touch screens.
`immediate`	Determines whether the user should be prompted for login and approval. Values are either `true` or `false`. Default is `false`. If set to `true`, and if the user is currently logged in and has previously approved the application, the approval step is skipped. If set to `true` and the user is not logged in or has not previously approved the application, the session is immediately terminated with the `immediate_unsuccessful` error code.
`state`	Specifies any additional URL-encoded state data to be returned in the callback URL after approval.
`scope`	Specifies what data your application can access. See “Scope Parameter Values” in the online help for more information.

An example authorization URL might look something like the following:

https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=
3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA
9GE&redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp&state=mystate

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.
Once 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:
Parameters Description
code Authorization code the consumer must use to obtain the access and refresh tokens.
state The state value that was passed in as part of the initial request, if applicable.
An example callback URL with authorization information might look something like:
```
https://www.mysite.com/authcode_callback?code=aWekysIEeqM9PiThEfm0Cnr6MoLIfwWyRJcqOqHdF
8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D
```

Parameters	Description
`code`	Authorization code the consumer must use to obtain the access and refresh tokens.
`state`	The state value that was passed in as part of the initial request, if applicable.

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. The following parameters are required:

Parameter	Description
`grant_type`	Value must be `authorization_code` for this flow.
`client_id`	The Consumer Key from the remote access application definition.
`client_secret`	The Consumer Secret from the remote access application definition.
`redirect_uri`	The Callback URL from the remote access application definition.
`code`	Authorization code the consumer must use to obtain the access and refresh tokens.

The following parameter is optional:

Parameter	Description
`format`	Expected return format. The default is `json`. Values are: `urlencoded` `json` `xml` The return format can also be specified in the header of the request using one of the following: `Accept: application/x-www-form-urlencoded` `Accept: application/json` `Accept: application/xml`

Parameter

Description

format

Expected return format. The default is json. Values are:

urlencoded
json
xml

The return format can also be specified in the header of the request using one of the following:

Accept: application/x-www-form-urlencoded
Accept: application/json
Accept: application/xml

An example access token POST request might look something like:

POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com 
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=3MVG9lKcPoNI
NVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCs
cA9GE&client_secret=1955279925675241571&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp

If this request is successful, the server returns a response body that contains the following:

Parameters	Description
`access_token`	Access token that acts as a session ID that the application uses for making requests. This token should be protected as though it were user credentials.
`refresh_token`	Token that can be used in the future to obtain new access tokens. Warning This value is a secret. You should treat it like the user's password and use appropriate measures to protect it.
`instance_url`	Identifies the Salesforce instance to which API calls should be sent.
`id`	Identity URL that can be used to both identify the user as well as query for more information about the user. Can be used in an HTTP request to get more information about the end user.
`issued_at`	When the signature was created, represented as the number of seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).
`signature`	Base64-encoded HMAC-SHA256 signature signed with the consumer's private key containing the concatenated ID and `issued_at` value. The `signature` can be used to verify that the identity URL wasn’t modified because it was sent by the server.

An example JSON response body might look something like:

{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448101416","refresh_token":"5Aep8614iLM.Dq661ePDmPEgaAW9
Oh_L3JKkDpB4xReb54_pZebnUG0h6Sb4KUVDpNtWEofWM39yg==","instance_url":
"https://na1.salesforce.com","signature":"CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk
4J2urAe+fVg=","access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0R
NBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}

The application uses the provided access token and refresh token to access protected user data.