OAuth 2.0 for First-Party Applications: Headless Passwordless Login for Private Clients

Step 1: End User Enters Their Email Address or Phone Number for Login

An end user visits your first-party app. Your app natively displays a login form requesting only the user's email address or phone number. The user enters their email address or phone number in the form.

Step 2: First-Party App Finds the Username

Your first-party app finds the username associated with the user's phone number or email address.

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

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 4: App Sends Initial Request to Authorization Challenge Endpoint

To initialize passwordless login, 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.

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

username=janice.edwards@example.com&
login_type=sms&
client_assertion=**********&
recaptcha_token=********&
scope=profile&
client_id=******&
code_challenge=********

Step 5: Salesforce Validates the Request

Salesforce first attempts to validate the client attestation JWT by checking 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 went wrong. Here's an example response that's returned if Salesforce can't find a username that matches the one sent in the request.

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 the auth-session and 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 this sensitive value. 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.

For example, if your client attestation JWT is valid but the request fails because the username was incorrect, resubmit a request that includes only the auth_session, username, and password.

(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 6: Salesforce Sends an OTP to the User

If the request is successful, Salesforce still returns an error response because it can't yet grant the authorization code. But this time, the error response indicates that login was initialized and that Salesforce sent an OTP to the user's email address or phone number. To confirm that the request was successful, look out for the error code login_initialized and the state otp_sent. The response also includes an auth_session parameter, which is important for the next step.

Here's an example response.

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

{
  "error": "authorization_required",
  "auth_session": "uY29tL2F1dGhlbnRpY",
  "error_code": "login_initialized",
  "login_status": {
    "type": "SMS",
    "state": "otp_sent",
    "displayData": "+120******58"
   }
}

Step 7: Your App Natively Displays a Verification Form

In your first-party app, you display a verification form where the end user can enter their OTP. The look and feel of this form are entirely up to you.

Step 8: User Enters OTP in Verification Form

The user receives the OTP at their email address or phone number and enters it in the verification form in your first-party app.

Step 9: Your App Requests an Authorization Code

To request an authorization code, your app sends another POST request to the /services/oauth2/v1/authorization_challenge endpoint. This request has no required headers. Include these parameters in the request body.

Here's an example request.

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

auth_session=uY29tL2F1dGhlbnRpY*
login_otp=<otp_from_sms>

Step 10: Salesforce Returns an Authorization Code

If the OTP is correct and the auth_session is valid, Salesforce returns an authorization code and terminates the auth_session. Here's an example authorization code response.

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

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

Step 11: 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 12: 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 13: App Creates the User’s Session

Your app receives the access token response, processes it, and creates the user’s session.

Step 14: 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 configured your external client app, 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 15: 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 16: 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.