Learn Key Concepts in Headless Identity

Learning Objectives

After completing this unit, you’ll be able to:

Describe the difference between public and private clients.
Explain the implications of building and securing a flow for a public client vs. a private client.
Describe the core pattern of the Authorization Code and Credentials Flow.

What Can I Do with Headless Identity?

After learning more, you’re excited about headless identity’s potential for NTO’s use case. You see that Salesforce offers a bounty of features:

Headless registration
Headless login with a username and password
Headless passwordless login with email or SMS
Headless password reset
Native single sign-on (SSO) experiences in your app
Headless flow to identify guest users who visit your app

That’s a lot of features to learn about! As it turns out, many of these features have a lot in common. Let’s start with a few key concepts that span most headless identity features. Once you understand these concepts, learning about each flow in the next unit will be simple.

Securing Headless Identity Flows

Security is a top priority for any identity implementation. For headless identity, there are some extra considerations that affect how you build your flow.

In a headless identity flow, the type of off-platform app matters. From a security perspective, there are two types of headless apps.

Public clients have the potential to be tattletales. Try as they might, they can’t keep confidential information, like consumer secrets, to themselves. These apps run in browsers or on devices. Mobile apps are an example of public clients.
Private clients are like trusted friends who safeguard your secrets. These apps run on their own servers that end users can’t access. Because these apps have a place to store their secrets, it’s harder to get information out of them. Web apps are an example of private clients.

Once you know what type of app you’re working with, you can make informed decisions about how to secure your flow. Take a look at this comparison table to understand the differences.

Security Measure

Public Clients

Private Clients

OAuth 2.0 Proof Key for Code Exchange (PKCE) extension defined by the Internet Engineering Task Force

Always implement the PKCE extension for public clients. PKCE helps you avoid leaking the app's consumer secret and other confidential information.

While PKCE is strongly recommended, it's less critical for a private client because the app can store the consumer secret and use it to protect the token exchange.

Google reCAPTCHA

Secure the public entries to these flows with reCAPTCHA. reCAPTCHA helps you prevent bot attacks. In headless identity flows, configuring reCAPTCHA involves a few steps, including configuring the right Experience Cloud settings, implementing reCAPTCHA on your app, and including a reCAPTCHA token in your requests to some Headless Identity APIs.

As an extra layer of security, you can implement reCAPTCHA the same way you would for a public client. But it's not the primary method for securing your flow. As a best practice, secure your flow with an integration user, so your calls to Headless Identity APIs are authenticated.

Authenticated calls to Headless Identity APIs

For a public client, we don't recommend securing your flow with authenticated API calls. Authenticated calls require an access token issued to an internal integration user in your requests. A public client can't keep the token or the integration user's credentials safe.

Secure your flow first by making authenticated requests to Headless Identity APIs. This means you include an access token issued to an internal integration user. To get the access token, implement a standard OAuth 2.0 flow, like the user-agent flow.

In addition to security considerations, your app type affects how you build each flow. To understand how it all comes together, let’s look at the core pattern of most headless identity flows and examine how it’s different for public and private clients.

The Foundation of Headless Identity: The Authorization Code and Credentials Flow

To build headless identity flows, you need a way to integrate your website with Salesforce Headless Identity APIs. Enter the Authorization Code and Credentials flow—a proprietary extension of the OAuth 2.0 authorization code flow.

Why do we call the Authorization Code and Credentials Flow the foundation of headless identity? Several headless identity features—headless login, headless registration, passwordless login, and the guest user flow—rely on variations of this flow. These variations follow a common, simplified pattern:

Request an authorization code: To get a code, your app sends credentials to the authorization endpoint. The type of credentials—for example, username and password—depends on the flow.
Get the code: Salesforce sends back an HTTP 302 redirect to a preconfigured URL containing the code, and the code is extracted.
Exchange the code for an access token: The authorization code is sent to the Salesforce token endpoint in exchange for an access token, which your app then uses to access Salesforce data.

This pattern is common across public clients and private clients, but it plays out slightly differently for each app type. Did you notice how we said “the code is extracted” in step 2, and “the authorization code is sent” in step 3—but we don’t say who or what takes these steps? That’s because it’s different for public clients and private clients.

Public Clients and the Authorization Code and Credentials Flow

For public clients, either a client backend or the Salesforce OAuth 2.0 echo endpoint extracts the authorization code. Then your app’s front end completes the token exchange. During the token exchange, the app doesn’t send its consumer secret. Remember, as a public client, it can’t keep the secret safe. That’s why we always recommend PKCE. It prevents code injection attacks by ensuring that your app and Salesforce both have parameters that no one else can verify.

A more complete view of the flow pattern looks like this:

Request an authorization code: Your app sends credentials in a call to the authorization endpoint.
Get the code:

Salesforce sends back an HTTP 302 redirect to a preconfigured URL that contains the code.
A server-side client backend extracts the code from the 302 redirect and returns it to your app. This backend can be an endpoint that you host or it can be Salesforce’s OAuth echo endpoint.

Exchange the code for an access token: Your app sends the code to the Salesforce token endpoint in exchange for an access token. The user is logged in and your app can use the token to access Salesforce data.

Private Clients and the Authorization Code and Credentials Flow

For private clients, a server-side client backend extracts the code and exchanges it for an access token. These apps do send the consumer secret during the token exchange, because they can safely store the secret in their private backends. The consumer secret acts like a password does to help protect the token endpoint.

Here’s how it works:

Request an authorization code: Your app sends credentials in a call to the authorization endpoint.
Get the code:

Salesforce sends back an HTTP 302 redirect to a preconfigured URL containing the code.
A server-side client backend extracts the code from the 302 redirect. It doesn’t return the code to the front end.

Exchange the code for an access token: The server-side client backend sends the code to the Salesforce token endpoint in exchange for an access token. The user is logged in and your app can use the token to access Salesforce data.

Building on the Authorization Code and Credentials Flow

Now that you understand the core pattern of the Authorization Code and Credentials Flow, you’ll spot it in several headless identity features. In the next unit, we review these features and how you can use them in a real-world identity implementation.

Keep in mind that two headless identity features—the Headless Forgot Password Flow and native SSO experiences—break this mold. We discuss that in the next unit too.

需要帮助？

了解更多