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

Step 1: User Opens First-Party App and Clicks Register

A user opens your first-party app and clicks a registration link. Or they click a link to access a resource that requires registration.

Step 2: First-Party App Displays Registration Form

In your first-party app, you natively display a registration form to collect information about the user. You control everything about this form, including its look, feel, and the user information that you want to collect.

There are a few considerations about what information you want to gather from users. When your app submits user information to the authorization challenge endpoint, Salesforce checks for an email address, username, last name, and password. You can collect this information from users or autogenerate it, but it must be included in your POST request. When deciding what information to include, make sure to collect an email address or phone number so that the user can verify their identity.

Step 3: User Enters Their Information

In your app's registration form, the user enters their information.

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

From the browser, your app sends a POST request to the services/oauth2/v1/authorization_challenge endpoint on your Experience Cloud site.

Include this header in your request if necessary.

Include these parameters in the request body.

Here's an example initial registration request.

POST /services/oauth2/v1/authorization_challenge? HTTP 1.1
Host: MyExperienceCloudSite.my.site.com
{
    "userdata": {
        "firstname": "Janice"
        "lastname": "Edwards"
        "email": "janice.edwards@example.com"
        "username": "jedwards@myapp.com"
        }
    "customdata": {
        "mobilePhone"="<mobile phone number>"
        }
    "password":"*********"
    "recaptcha": "*******"
    "login_type": "email"
    "emailtemplate": "unfiled$public/SalesNewCustomerEmail"
    "client_assertion": "Y2xpZW50YXNzZXJ0aW9u..."
}

Step 6: 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.

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. The response also 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. They're already represented by 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.

Step 7: 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 8: 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 9: User Enters OTP in Verification Form

The user receives the OTP and enters it in the verification form in your first-party app.

Step 10: Your App Requests an Authorization Code

To request an authorization code, your app sends the auth_session and the OTP that the user entered to the authorization challenge endpoint using another POST request to the services/oauth2/v1/authorization_challenge This request has no required headers. Include these parameters in the request body.

Here's an example request.

POST /authorize HTTP/1.1
Host: MyExperienceCloudSite.my.site.com

auth_session=uY29tL2F1dGhlbnRpY*
login_otp=<otp_from_sms>

Step 11: Salesforce Returns an Authorization Code

If the OTP is correct and the auth_session request 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 12: Your App Exchanges the Authorization Code for an Access Token

After you get the authorization code, your app sends a request to the Salesforce 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 13: 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 14: App Creates the User’s Session

Your first-party app processes the token response and creates the user's session.

Step 15: User Is Registered and Performs an Action in the App

Your user is now registered and logged in. They perform an action in your app that requires access to Salesforce data. For example, they click a button to view their travel booking 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 16: 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 17: User Can Access Salesforce Data

The user can now access protected Salesforce data in your app. For example, they can see their travel booking history.