--- schema_version: "1" id: 51e9c28f2ad56701dec72da3cd62e2e7d30d1402b479af33220d042f7b0c5d16 title: OAuth 2.0 Web Server Flow for Web App Integration collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/remoteaccess_oauth_web_server_flow.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 97cb81ed097d74171d45864cde872c08e8e2089cfa2ae5e65dac57c173f3dcb8 description: To integrate an external web app with the Salesforce API, use the OAuth 2.0 web server flow, which implements the OAuth 2.0 authorization code grant type. With this flow, the server hosting the web app must be able to protect the external client app’s identity, defined by the client ID and client secret. products: - Security - Cross Cloud release: "264" --- # OAuth 2.0 Web Server Flow for Web App Integration To integrate an external web app with the Salesforce API, use the OAuth 2.0 web server flow, which implements the [OAuth 2.0 authorization code grant type](https://tools.ietf.org/html/rfc6749#section-4.1). With this flow, the server hosting the web app must be able to protect the external client app’s identity, defined by the client ID and client secret. ### Required Editions
Available in: both Salesforce Classic (not available in all orgs) and Lightning Experience
Available in: all editions
We recommend that you use the web server flow with Proof Key for Code for Exchange (PKCE, pronounced pixy) in place of the user-agent flow or the username-password flow for special scenarios. Use the `code_challenge` and `code_verifier` parameters to implement PKCE with the web server flow. For more information on PKCE, see the [Internet Engineering Task Force (IETF.)](https://datatracker.ietf.org/doc/rfc7636/) We also recommend that you block all external client apps from using the user-agent flow or the username-password flow. For steps, see [Block Authorization Flows to Improve Security](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_disable_username_password_flow.htm&release=264.0.0&type=5 "The OAuth 2.0 user-agent and username-password flows are considered insecure and aren’t recommended. For better security, we strongly recommend that you block these flows in Salesforce to prevent developers from using them to build new integrations. If your org is created in Summer ‘23 or later, the username-password flow is blocked by default. You can enable the username-password flow if needed. If you have existing integrations that use the user-agent or username-password flow, update them to a more secure OAuth 2.0 flow. You can also block the Authorization Code and Credentials Flow, which is used to securely configure a headless login process. And you can block certain flows that don’t use the PKCE extension."). Here’s an example use case for implementing the web server flow. You recently developed a web service that allows secure access to customer order status. The order status data is securely stored in your Salesforce CRM platform. To authorize Help Desk users to view a customer’s order status, you develop an Order Status app and configure it as an external client app with the web server flow. - A Help Desk user clicks the Order Status web app. - The external client app posts an authorization code request to the Salesforce authorization endpoint. - The user is redirected to the Salesforce login page. After a successful login, the user is asked to approve the app’s access to order status data. - After the user approves the Order Status app to access the data, Salesforce sends a callback to the Order Status app with an authorization code. - The Order Status app passes the authorization code to the Salesforce token endpoint, requesting an access token. - Salesforce validates the authorization code and sends back an access token that includes associated permissions in the form of scopes. - The Order Status app sends a request back to Salesforce to access the order status data. The request includes the access token with associated scopes. - Salesforce validates the access token and associated scopes. - The Order Status app can access the protected data, and the customer’s order status is displayed in the app. ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_note.png) Note If the access token becomes invalid, the external client app can use a refresh token to get a new access token. Let’s take a closer look at each step of this authorization flow. - [Request an Authorization Code](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5) - [User Authenticates and Authorizes Access](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5) - [Salesforce Grants Authorization Code](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5) - [Request an Access Token](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5) - [Salesforce Grants an Access Token](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm&release=264.0.0&type=5) ## Request an Authorization Code To initiate the OAuth 2.0 web server flow, the external web service—via the external client app—posts an authorization code request using the authorization code grant type to the Salesforce authorization endpoint. With an authorization code, the external client app can prove that it’s been authorized as a safe visitor to the site and that it has permission to request an access token. The authorization code is in the form of an HTTP redirect. ``` https://MyDomainName.my.salesforce.com/services/oauth2/authorize? client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq& redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback& response_type=code ``` Include these parameters in an authorization code request. | Parameter | Description | | --- | --- | | `Request Header` | The Salesforce 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` | The OAuth 2.0 grant type that the external client app requests. The value for this flow must be `code` to indicate that the external client app is requesting an authorization code. | You can also include these parameters in an authorization code request.
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 Tokens and Scopes.
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.
state Any state that the external web service requests to be sent to the callback URL. This value must be URL encoded.
immediate

A boolean value to determine whether the user is prompted for login and approval. The default value is false. If you set this parameter to true, one of these scenarios happens.

  • If the user is logged in and has previously approved the client’s access, Salesforce skips the approval step.
  • If the user isn’t logged in or hasn’t previously approved the client’s access, Salesforce immediately terminates with the immediate_unsuccessful error code.

The immediate option isn’t available for Experience Cloud sites.
code_challenge

Specifies the SHA256 hash value of the code_verifier value in the token request. Set this parameter to help prevent authorization code interception attacks. The value must be base64url-encoded as defined in https://tools.ietf.org/html/rfc4648#section-5.

This parameter is required if a code_verifier is specified in the token request.

  • If the code_challenge value is provided in the authorization request and a code_verifier value is provided in the token request, Salesforce compares the code_challenge to the code_verifier. If the code_challenge is invalid or doesn’t match, the login fails with the invalid_request error code.
  • If the code_challenge value is provided in the authorization request, but a code_verifier value isn’t provided in the token request, the login fails with the invalid_grant error code.
display

Changes the display type of the login and authorization pages. Salesforce supports these values.

  • page—Full-page authorization screen (default).
  • popup—Compact dialog optimized for modern web browser popups.
  • touch—Mobile-optimized dialog designed for modern mobile devices, such as Android and iPhone.
  • mobile—Mobile-optimized dialog designed for less capable devices, such as the BlackBerry operating system 5.
login_hint

Provides a valid username value to prepopulate the login page with the username, such as login_hint=username@company.com. If a user already has an active session in the browser, the login_hint parameter does nothing, and the active user session continues.

To pass the login_hint parameter for Experience Cloud sites, also pass the prompt=login parameter. Together, these parameters redirect the user to the login page with the correct login hint.
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.

  • login—The authorization server must prompt the user for reauthentication, forcing the user to log in again.
  • consent—The authorization server must prompt the user for reapproval before returning information to the client.
  • select_account—If presented, take one of these actions.
    • If zero or one hint is available and the user is logged in, show the approval page without prompting for login.
    • If zero or one hint is available and the user isn’t logged in, prompt for login.
    • If more than one hint is available, show the account chooser.

You can pass login and consent values, separated by a space, to require the user to log in and reauthenticate. For example: ?prompt=login%20consent
Uvid-Hint header

Optionally, to connect this flow to the headless guest flow, you can include a Uvid-Hint header with a JWT-based access token containing a UVID value, which is a Version 4 universally unique identifier (UUID) that your app generates and manages. To get an access token with a UVID, you must enable your external client app to issue JWT-based access tokens and implement the headless guest flow on your app.

If you implement the guest user flow on your app, you can optionally use this header to pass in a JSON Web Token (JWT)-based access token containing a unique visitor ID (UVID) tied to a guest user’s identity. By passing the UVID into a named user flow, you can carry contextual information from a guest user session, like the user’s cookie preferences, into a named user session.
uvid_hint body parameter

A plain UVID value, which is a Version 4 UUID that your app generates and manages. To get a UVID, you must enable your external client app to issue JWT-based access tokens and implement the headless guest flow on your app. You can optionally use this parameter to pass in a UVID value tied to a guest user’s identity, carrying contextual information from a guest user session into a named user session.

Instead of passing the UVID in the request body, you can also pass it in a JWT-based token with a UVID via the UVID-Hint header.

## User Authenticates and Authorizes Access Before Salesforce provides authorization codes to external client apps, the authenticating users are asked to log in to Salesforce. ![Login page to Salesforce org](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/identity/images/remoteaccess_authflow_login.png) After a successful login, Salesforce redirects users to the approval page to grant access to the app. ![Approval page to grant access to the external client app](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/identity/images/remoteaccess_authflow_authorize.png) If users previously approved access, it isn’t necessary to approve access again. ## Salesforce Grants Authorization Code After users approve access to an external client app, Salesforce redirects users to the callback URL, where they can view the callback with an authorization code. ``` https://www.mycustomerorderstatus.com/oauth2/callback? code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg== ``` - The first part of the callback is the external client app’s callback URL: `https://www.mycustomerorderstatus.com/oauth2/callback`. - The second part is the authorization code that the external client app uses to get an access token: `code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==`. The authorization code expires after 15 minutes. If the `state` parameter is included in the original query string, the specified state is passed into the approval step. ## Request an Access Token To request an access token, the external client app passes the authorization code to the Salesforce token endpoint as an HTTP POST. ``` POST /services/oauth2/token HTTP/1.1 Host: mycompany.my.salesforce.com Content-length: 307 Content-type: application/x-www-form-urlencoded grant_type=authorization_code& code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==& client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq& client_secret=*******************& redirect_uri=https://www.mycustomerorderstatus.com/oauth2/callback ``` The POST in the example contains these parameters. ![Important](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_important.png) Important When developing OAuth integrations, always pass sensitive information in the body of a POST request or in a request header. Don't use GET parameters in the URL query string to pass sensitive information. Sensitive information includes but isn't limited to usernames, passwords, OAuth tokens, client secrets, and any personally identifiable information. For more information on security best practices, see [Storing Sensitive Data](https://developer.salesforce.com/docs/atlas.en-us.secure_coding_guide.meta/secure_coding_guide/secure_coding_storing_sensitive_data.htm) in the Secure Coding Guide.
Parameter Description
Request Header

The request header can contain these parameters.

  • The Salesforce OAuth 2.0 endpoint. External client apps send OAuth token requests to this endpoint.
  • The URL of the hosting service.
  • The length of the request’s content.
  • The requested format of the returned response. These formats are supported.
    • Accept: application/json
    • Accept: application/xml
    • Accept: application/x-www-form-urlencoded

The request header also supports these parameters.

  • The */* wildcard is accepted and returns JSON.
  • A list of values, which is checked left to right. For example: application/xml,application/json,application/html,*/* returns XML.

The format parameter takes precedence over the access request header.
grant_type The type of validation that the external client app can provide to prove it’s a safe visitor. For the web server flow, the value must be authorization_code.
code A temporary authorization code received from the authorization server. The external client app uses this code in exchange for an access token. This type of OAuth 2.0 flow is a secure way to pass the access token back to the application.
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.
client_secret

The consumer secret of the external client app. To access the consumer secret, 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 secret.

This parameter is required unless the external client app doesn’t have Require Secret for Web Server Flow enabled. If a client_secret isn’t required, and the external client app sends it in the authorization request, Salesforce attempts to validate it anyway.

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 or from the external client app’s definition. This value must be URL encoded.
You can also include these parameters.
Parameter Description
client_assertion Instead of passing a client_secret, you can provide a client_assertion and client_assertion_type. If a client_secret parameter isn’t provided, Salesforce checks for the client_assertion and client_assertion_type. See Use client_assertion Instead of client_secret.
client_assertion_type

Provide this value when using the client_assertion parameter.

The value of client_assertion_type must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
code_verifier

Required only if a code_challenge parameter was specified in the authorization request. Specifies 128 bytes of random data with high entropy to make guessing the code value difficult. Set this parameter to help prevent authorization code interception attacks. The value must be base64url-encoded as defined in https://tools.ietf.org/html/rfc4648#section-5.

  • If the code_verifier value is provided in the token request and a code_challenge value is in the authorization request, Salesforce compares the code_verifier to the code_challenge. If the code_verifier is invalid or doesn’t match, the login fails with the invalid_grant error code.
  • If the code_verifier value is provided in the token request, but a code_challenge value isn’t provided in the authorization request, the login fails with the invalid_grant error code.
format

If not included in the request’s header, you can specify the expected return format. The format parameter takes precedence over the request’s header. These formats are supported.

  • urlencoded
  • json (default)
  • xml
Use `client_assertion` instead of `client_secret`. If you provide a `client_assertion` instead of a `client_secret`, the value of `client_assertion` must include these parameters. - `iss`—The `client_id` from the external client app definition. - `sub`—The `client_id` from the external client app definition. - `aud`—The token servlet URL: https://hostname/services/oauth2/token. - `exp`—The expiration time of the assertion within 5 minutes, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC. The `client_assertion` must also be signed with the private key associated with the OAuth consumer’s uploaded certificate. Only the RS256 algorithm is supported. For the `private_key_jwt` client authentication method, see the [OpenID Connect specifications](http://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). HTTP Basic Authentication Scheme Instead of sending client credentials as parameters in the body of the POST, Salesforce supports the HTTP Basic authentication scheme. This scheme’s format requires the `client_id` and `client_secret` in the authorization header of the post as follows: `Authorization: Basic64Encode(client_id:secret)` The `client_id` and `client_secret` are separated with a colon (`:`). For more information, see the [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) document. This example shows an access token POST request that uses the HTTP Basic authentication scheme, rather than sending client credentials in the POST request’s body. ``` POST /services/oauth2/token HTTP/1.1 Host: mycompany.my.salesforce.com Authorization: Basic client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq& client_secret=*******************& grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D& redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp ``` ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_note.png) Note If the `client_id` and `client_secret` are sent in the POST’s body, the authorization header is ignored. ## Salesforce Grants an Access Token After Salesforce validates the external client app’s credentials, it returns a response with the access token. In this example, the response is in a JSON format. ``` { "access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK", "signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=", "scope": "web openid", "id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...", "instance_url": "https://mycompany.my.salesforce.com", "id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC", "token_type": "Bearer", "issued_at": "1558553873237" } ``` The response includes these parameters.
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.
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 Tokens and Scopes.
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 openid.

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.
token_type A Bearer token type, which is used for all responses that include an access token.
issued_at Time stamp of when the signature was created in milliseconds.
The response can also contain these parameters.
Parameter Description
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.

This parameter is returned only if your external client app is set up with a refresh_token scope.

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.
state The state requested by the client. This value is included only if the state parameter is included in the original query string.
#### See Also - [OAuth 2.0 Authorization Errors](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_flow_errors.htm&release=264.0.0&type=5 "Errors can occur during OAuth authorization. For example, a user denies access to the connected app or request parameters are incorrect. When errors occur, the authorizing server sends an error to the callback URL with an error code.")