Headless Identity APIs: Authorization Code and Credentials Flow for Private Clients

A key component of this flow is the client-side JavaScript that requests authorization and receives the access token response. This example uses a connected app.

var clientId = '<Connected App Client ID>';
var baseURL = '<Experience Cloud Domain>';
var redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';

function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}    

Another key component is the server-side callback handler, which extracts the code and exchanges it for an access token. Here’s an example callback handler using an Apex class exposed as a REST resource.

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }
  
  
   global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = null;
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }
  
   // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }
}

Here’s a detailed breakdown of this flow.

End User Opens Third-Party App and Logs In

Your user opens your third-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.

Third-Party App Generates code_verifier and code_challenge Values (Optional)

If you’re using the Proof Key for Code Exchange (PKCE) extension, the app generates values used to verify the authorization code.

As a security best practice, we strongly recommend using the PKCE extension when you implement the Authorization Code and Credentials Flow. 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.

When you’re implementing this flow using a server-side callback handler, enable the Require Secret for Web Server Flow and Require Secret for Refresh Token Flow settings in your external client app or connected app settings. With these settings enabled, ensure that your callback handler keeps the consumer secret secure.

Third-Party App Headlessly Requests an Authorization Code

From the browser, the third-party app sends a headless authorization request to the Headless Login API authorization endpoint on your Experience Cloud site using Asynchronous Java and XML ((AJAX). If you aren't using headless user discovery, you can use either the GET or POST method for this request. If you are using headless user discovery, only POST requests are supported.

function startLogin() {
   var username = document.getElementById('user_name').value;
   var password = document.getElementById('password').value;
   var encodedUNP = btoa(username + ':' + password);
   var client = new XMLHttpRequest();
   client.open("POST", baseURL + "/services/oauth2/authorize", true);
   client.setRequestHeader("Auth-Request-Type", "Named-User");
   client.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
   client.setRequestHeader("Authorization", "Basic " + encodedUNP);
   client.send("response_type=code_credentials&client_id=" + clientId + "&redirect_uri=" + redirectURL);
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           console.log("here");
           console.log(client.response);
           response = JSON.parse(client.response);
           if (response.success) {
               getUserInfo(response.access_token, baseURL);
           }
       }
   }
   return false;
}  

For both GET and POST requests, you must include the header Auth-Request-Type: Named-User.

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’s generated and managed entirely by your app. To get an access token with a UVID, you must enable your external client app or connected 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.

You can also include the plain UVID value in the request body.

GET /services/oauth2/authorize? HTTP 1.1
Host: MyDomainName.my.site.com
Auth-Request-Type: Named-User
Authorization: Basic <encoded username:password>

response_type=code_credentials&
redirect_uri=https://www.MyDomainName.my.site.com/services/apexrest/code/exchange&
client_id=******&
code_challenge=Y29kZ*******

If you’re using a POST request, you can include the Base64-encoded user credentials in an authorization header, or you can put them in the request body.

If you're using headless user discovery, you don't send a username and password. Instead, you send an identifier in the login_hint parameter, optional custom data, and a password. Include the identifier, custom data, and password in the body of a POST request. Don't use a GET request.

Note If you have the Require user credentials in the POST body for Authorization Code and Credentials Flow setting enabled on your external client app or connected app, you can send the user credentials only in the request body. With this setting enabled, you can’t use the GET method for the authorization code request. You can use only the POST method.

For GET and POST methods, include these required parameters in the body of the authorization request.

You can also include these optional parameters in the authorization request.

(Optional) Headless User Discovery Handler Finds the User

If you're using a headless user discovery handler, the handler takes the login_hint and customdata parameters 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.

Salesforce Validates Credentials and Returns a 302 Redirect

https://www.MyDomainName.my.site.com/services/apexrest/code/exchange?code=aPrxC1*******
&sfdc_community_url=https%3A%2F%2FMyDomainName.my.site.com&sfdc_community_id=0DBxxxxxxxxxxxx

Callback Handler Extracts Code and Performs Code Exchange

The server-side callback handler extracts the authorization code and other parameters from the 302 redirect. It then initiates the code exchange by sending a headless POST request to the token endpoint.

@RestResource(urlMapping='/code/exchange')
global class CodeExchangeAPI {
  
   @HttpGet
   global static ExchangeResponse doGet() {
       RestRequest req = RestContext.request;
       RestResponse res = RestContext.response;
       try {
           res.statusCode = 200;
          
              String accessToken = doCodeExchange(req.params.get('code'), req.params.get('sfdc_community_url'));
           if (accessToken != null) {
                return new ExchangeResponse(accessToken, req.params.get('state'));
           } else {
               return new ExchangeResponse('Could not parse auth code redirect URI');
           }
       } catch (Exception e) {
           res.statusCode = 500;
           return new ExchangeResponse('Could not parse auth code redirect URI');
       }
      
   }

global static String doCodeExchange(String code, String communityURL) {
       String clientId = 'Connected App Client ID';
       String redirectURL = '<Experience Cloud Domain>/services/apexrest/code/exchange';
       String clientSecret = '<ConnecedApp Secret>';
      
       Http h = new Http();
       HttpRequest req = new HttpRequest();
       req.setMethod('POST');
      
       //Create Code Exchange URL
       String url = communityURL + '/services/oauth2/token';
       req.setEndpoint(url);
      
       //Post Body
       String body = 'grant_type=authorization_code';
       body = body + '&client_id=' + clientId;
       body = body + '&code=' + code;
       if (clientSecret != null) {
          body = body + '&client_secret=' + clientSecret;
       }
       body = body + '&redirect_uri=' + redirectURL;
      
       //URL encode Post Body
       String encodedBody = EncodingUtil.urlEncode(body, 'UTF-8');
      
       // Set request body
       req.setBody(body);
      
       //Add Headers
       req.setHeader('Content-Type','application/x-www-form-urlencoded');
      
       //Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }
   }

For the access token request, you can use only a POST request—GET requests aren’t supported. You must include a Content-Type header. Include these required parameters in the request body.

You can also include these optional parameters in the token request.

 // Response Wrapper
   global class ExchangeResponse {
       String access_token;
       String state;
       String errMsg;
       Boolean success; 
      
       public ExchangeResponse(String access_token, String state) {
           this.access_token = access_token;
           this.state = state;
           this.success = true;
       }
      
        public ExchangeResponse(String errMsg) {
           this.success = false;
           this.errMsg = this.errMsg;
       }       
   }

Salesforce Grants an Access Token

{
"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 required parameters.

The access token response can also include these parameters.

Callback Handler Processes Token Response and Returns Parameters to App

//Send Token Request
       HttpResponse res = h.send(req);
      
       if (res.getStatusCode() == 200) {
           //Extract Token from Response
           Map<String,Object> tokenResponseMap = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
           return (String)tokenResponseMap.get('access_token');
       } else {
           return null;
       }

The server-side callback handler returns the access token and state to the browser, along with user data, tokens, and session data. In our example, the response wrapper returns the access token to the app. As a best practice, we recommend that you configure your server to store the access token, create a session for the app, and return the session to the app, instead of returning the access token. As the developer, you’re in full control of creating the session, storing the access token, and managing the logged-in state, so your specific implementation is up to you.

{"success":true,"state":"https://MyExperienceCloudSite.my.site.com/","errMsg":null,"access_token":"00*******"}

App Processes Token Response and Creates the User Session

function getUserInfo(accessToken, userInfoBaseURL) {
   var client = new XMLHttpRequest();
   client.open("GET", userInfoBaseURL + "/services/oauth2/userinfo", true);
   client.setRequestHeader("Content-Type", "application/json");
   client.setRequestHeader("Authorization", "Bearer " + accessToken);
   client.send();
   client.onreadystatechange = function() {
       if(this.readyState == 3) {
           response = JSON.parse(client.response);
           response.access_token = accessToken;
           document.getElementById("json").textContent = JSON.stringify(response, undefined, 2);
           document.getElementById("results").style.display="block";
       }
   }
}

End User Is Logged in and Performs an Action in the App

Your user is now 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.

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.

End 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. From the end user’s perspective, the entire process from logging in to accessing their data happened without ever requiring them to leave the app.