OAuth 2.0 for First-Party Applications: Headless Username-Password Flow for Private Clients

Step 1: End User Opens First-Party App and Logs In

An end user opens your first-party app intending to log in. In your app, your login form appears showing username and password fields and a login button. Salesforce doesn’t provide this login form. Its look and feel are up to you. Your user enters their username and password and clicks the login button.

Step 2: First-Party App Mints a Client Attestation JWT and Generates code_verifier and code_challenge Values

The app mints a client attestation JWT.

The app also generates values for the PKCE parameters used to verify the authorization code.

Note We strongly recommend that you always implement PKCE for this flow. Otherwise, you don't get its security benefits.

For more information on PKCE, see the specificationRFC 7636: Proof Key for Code Exchange by OAuth Public Clients provided by the Internet Engineering Task Force (IETF).

The PKCE specification defined in RFC 7636 also includes an optional code_challenge_method parameter that you can send in the authorization request. Salesforce ignores any value that you send in this parameter and defaults to SHA256.

Step 3: First-Party App Headlessly Requests an Authorization Code

From the browser, your app sends the user's credentials, along with other parameters, to the services/oauth2/v1/authorization_challenge endpoint on your Experience Cloud site via a headless POST request.

There are no required headers for this request. 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 unique visitor ID (UVID) value.

Include these parameters in the request body.

Here's an example request to the authorization challenge endpoint.

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

username=janice.edwards@example.com&
password=*****&
client_assertion=******&
recaptcha=********&
scope=profile&
code_challenge=********

Step 4: Salesforce Validates the Request

Salesforce first attempts to validate the client attestation JWT by validating that the signature passed in the client_asssertion parameter matches the signature for the certificate configured for the external client app.

If the client attestation JWT isn't valid, Salesforce returns an invalid_attestation error and you must resubmit the request with all of the parameters you originally submitted. Here's an example error response.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "invalid_attestation",
  "error_code": "client_attestation_failed"
}

If the client attestation JWT is valid, but there are other issues with the request, Salesforce returns an error response specifying what was wrong with the request. Here's an example response that's returned if the user submits the wrong username or password.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store

{
  "error": "authorization_required",
  "auth_session": "uY29tL2F1d*****",
  "error_code": "invalid_credentials"
}

The response includes an auth_session parameter that remains valid for 5 minutes after it's issued. During the timeframe while the auth_session is valid, you can use it to resubmit the request. In the corrected versions that you resubmit, include only the corrected values for the parameters that caused the request to fail. You must also resubmit the password with each request because Salesforce doesn't store it. But for other parameters, if they didn't cause the request to fail, you can leave them out. Salesforce already knows that you submitted these parameters because they're linked to the auth_session.

Note reCAPTCHA parameters don't get linked to the auth_session, but you can resubmit the request without them, unless they caused the request to fail.

Here are a few examples of common error scenarios. This list isn't comprehensive.

• The user submitted the wrong username or password. Resubmit the request with only the username, password, and auth_session.
• The reCAPTCHA token was incorrect. Resubmit the request with only the reCAPTCHA token, password, and auth_session.

After 5 minutes from when the auth session was issued, it doesn't work anymore and you get an auth_session_invalid error. In that case, resubmit the full request with all the parameters that you originally included.

(Optional) Headless User Discovery Handler Finds the User

If you're using a headless user discovery handler, the handler takes the login_hint and customdataparameters and finds the associated user. The handler confirms that the email address or phone number for the user is verified.

For an example handler, see Auth.HeadlessUserDiscoveryHandler.

Step 5: Salesforce Returns an Authorization Code

When your request to the authorization challenge endpoint is successful—whether that happens on the first try or after several retries with the auth_session—Salesforce returns an authorization code. Here's an example of a successful authorization code response.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "authorization_code": "uY29tL2F1d******"
}

Step 6: Your App Exchanges the Authorization Code for an Access Token

After you get the authorization code, your app sends a request to the services/oauth2/token endpoint.

This request has no headers. Include these parameters in the request body.

Here's an example token request.

POST services/oauth2/token? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com

code=********&
client_id=**********&
client_secret=*********&
redirect_uri=<callback_URL>&
grant_type=authorization_code&
code_verifier=*******

Step 7: Salesforce Grants an Access Token

After validating the app’s credentials. Salesforce returns an access token. Here’s an example access token response in JSON format.

{
"access_token":"*******************",
"sfdc_community_url":"https://MyDomainName.my.site.com",
"sfdc_community_id":"0DBxxxxxxxxxxxx",
"signature":"ts6wm/svX3jXlCGR4uu+SbA04M6qhD1SAgVTEwZ59P4=",
"scope":"openid api",
"id_token":"XXXXXX",
"instance_url":"https://yourInstance.salesforce.com",
"id":"https://yourInstance.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx",
"token_type":"Bearer",
"issued_at":"1667600739962"
}

The access token response contains these parameters.

Step 8: App Creates the User’s Session

The app receives the access token response and creates the user’s session.

Step 9: The User Is Logged In and Performs an Action in the App

The end user is now logged in, and they perform an action in your app that requires access to Salesforce data. For example, they click a button to view their order history, which is stored in Salesforce.

Note When you set up your external client app or connected app for the Authorization Code and Credentials Flow, you set the Permitted Users policy to Admin-approved users are pre-authorized and configure which profiles or permission sets can access the app. With this policy, users access the app without authorizing it, so they don’t get an authorization screen prompting them to let the app access their data.

Step 10: App Makes an Authenticated Call to a Salesforce Endpoint

To access the user’s Salesforce data, your app uses the access token to make an authenticated call to a protected Salesforce endpoint, such as a Salesforce API.

Step 11: User Can Access Salesforce Data

The user can now access protected Salesforce data in your app. For example, they can see their order history. From the user’s perspective, the entire process from logging in to accessing their data happened without ever requiring them to leave the app.