Experience Cloud Authentication

Experience Cloud Authentication

Use this skill when designing or building custom authentication flows for Experience Cloud sites: social SSO via OIDC or SAML auth providers, self-registration with custom Apex handlers, passwordless OTP login (standard or headless), and custom login pages for Aura or LWR sites.

Before Starting

Gather this context before working on anything in this domain:

• Site type (Aura vs LWR): This controls whether a custom login page must be a Visualforce page (Aura) or an LWC (LWR). Mixing them is a silent failure — LWR ignores VF login pages.
• Authentication mode (standard, headless, or passwordless): Headless and passwordless flows require distinct Apex handler interfaces (HeadlessUserDiscoveryHandler, HeadlessSelfRegistrationHandler) that are separate from the standard Auth.RegistrationHandler used for non-headless flows.
• Who the user population is: External guest users, community members, or partner users each have different license and profile constraints that affect what auth flows are permissible.
• Sandbox-first constraint: Auth providers require an external identity provider that must be pre-configured in sandbox before production. Skipping sandbox causes mismatched callback URLs and production incidents.

Core Concepts

Auth Providers (OIDC/SAML) for Social Login

An auth provider is a Salesforce-managed connector to an external identity provider. When a site visitor clicks "Sign in with Google," Salesforce redirects them to the IdP, receives an OAuth token or SAML assertion, and then maps the returned identity to a Salesforce user via a Registration Handler Apex class.

• OIDC providers (Google, Okta, custom) are configured under Setup > Auth. Providers with provider type "OpenID Connect". You supply the consumer key, secret, and authorize/token/userinfo endpoints.
• SAML providers configured as auth providers (distinct from SAML SSO settings) require the issuer, entity ID, and certificate. The Start SSO URL must include the ?community=<site-url> query parameter to route the assertion back to the correct site rather than the internal org login.
• Federation ID is the primary matching key. The value returned in the IdP's subject or a custom attribute must match User.FederationIdentifier. OIDC can also match on email, but Federation ID is more reliable for long-lived accounts.

Registration Handlers: Standard vs Headless

Two distinct Apex interfaces govern how Salesforce creates or matches users after an external identity is verified:

The HeadlessUserDiscoveryHandler and HeadlessSelfRegistrationHandler interfaces live in the headless identity API surface and are not the same as Auth.RegistrationHandler. Using the wrong interface compiles successfully but the headless flow will fail at runtime because Salesforce cannot locate the handler.

Passwordless Login and the HeadlessPasswordlessLogin API

Passwordless login sends a one-time passcode (OTP) to the user's email or phone without a password. Two modes:

• Standard passwordless — Salesforce manages the OTP prompt within the site's login page. Enable under Digital Experience > Administration > Login & Registration > Allow passwordless login.
• Headless passwordless — Your custom front end (mobile app, React, custom LWC) calls the HeadlessPasswordlessLogin REST resource directly. The API issues an OTP; your UI collects it and exchanges it for a session. Requires headless identity to be enabled in the org and the site must be configured for headless flows.

Headless flows require HeadlessUserDiscoveryHandler to locate an existing user and HeadlessSelfRegistrationHandler to create new users. Both classes are assigned in the Headless Identity settings for the site.

Custom Login Pages: VF for Aura, LWC for LWR

• Aura sites use a Visualforce page as the custom login page. Assign it under Administration > Login & Registration > Login Page Type = Visualforce Page.
• LWR sites use an LWC-based login page. Build the component extending lwc/loginForm or composing the c/selfRegisterLwc pattern, then assign it under the same Administration panel. Setting a VF page on an LWR site has no effect — the default login page renders silently.
• Login page LWCs must be deployed before they appear in the Administration drop-down. Deploy them as metadata-type LightningComponentBundle with isExposed: true and targets including lightningCommunity__Page.

Common Patterns

Pattern 1: Social Login with OIDC Auth Provider

When to use: Site users should be able to authenticate with Google, Okta, LinkedIn, or any OIDC-compatible IdP instead of creating a Salesforce community account with a password.

How it works:

1. Create an Auth Provider in Setup under the provider type (e.g., "Google", "OpenID Connect"). Supply client ID, client secret, authorize endpoint, token endpoint, and userinfo endpoint.
2. Set the Callback URL in your IdP application to https://<myDomain>.my.site.com/services/authcallback/<ProviderName>.
3. Write an Auth.RegistrationHandler Apex class. In createUser(), look up an existing User by FederationIdentifier or email. If found, return the existing user. If not, create a new external user with the appropriate profile and community.
4. Assign the Registration Handler on the Auth Provider setup page.
5. On the Experience Cloud site, go to Administration > Login & Registration > Login Page Branding, enable the auth provider as a social sign-on option.
6. For Aura sites, the login button is rendered automatically. For LWR sites with a custom login LWC, call the standard authprovider navigation target or use window.location redirect to the Start SSO URL.

Why not redirect directly to the IdP: Bypassing the auth provider Start SSO URL loses the community parameter routing and the registration handler. Users authenticate but land on the internal org login, not the community.

Pattern 2: Headless Passwordless OTP for Mobile App

When to use: A mobile or SPA front end needs to authenticate community users without showing a Salesforce-hosted login page — typically a branded mobile app using Experience Cloud as the identity layer.

How it works:

1. Enable Headless Identity in Setup > Digital Experiences > Settings.
2. Create a HeadlessUserDiscoveryHandler Apex class implementing Auth.HeadlessUserDiscoveryHandler. The discover() method receives the identifier (email or phone) and returns a Auth.UserDiscoveryResult indicating whether to challenge the existing user or route to registration.
3. Create a HeadlessSelfRegistrationHandler Apex class implementing Auth.HeadlessSelfRegistrationHandler. The createUser() method provisions a new external user; autoConfirm() controls whether email verification is skipped.
4. Assign both handlers in the Headless Identity settings for the Experience Cloud site.
5. From the mobile app, POST to <siteUrl>/services/auth/headless/init/passwordless/login with the user's email or phone. Salesforce returns an OTP via email/SMS.
6. User enters the OTP; the app POSTs to the verification endpoint. On success, Salesforce returns an access token.

Why not use standard passwordless: Standard passwordless requires a Salesforce-hosted page. Headless gives full front-end control and works in native mobile contexts where a webview cannot be used.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Identify site type and auth mode — Confirm whether the target site is Aura or LWR. Confirm whether the flow is standard social SSO, self-registration, standard passwordless, or headless passwordless. This determines which interfaces and page types are required.
2. Configure the auth provider or headless settings — For social SSO, create the Auth Provider in Setup and register the Callback URL with the IdP. For headless flows, enable Headless Identity in Digital Experiences settings before writing any Apex.
3. Implement the correct Apex handler — For social SSO, implement Auth.RegistrationHandler. For headless passwordless, implement both HeadlessUserDiscoveryHandler and HeadlessSelfRegistrationHandler. Never substitute one interface for the other.
4. Build the login page component — For Aura, create a VF page and assign it in Administration > Login & Registration. For LWR, build an LWC with lightningCommunity__Page in its target metadata and deploy it before assigning.
5. Verify user matching and license — Confirm Federation ID is populated correctly for social login users. Confirm the profile and license assigned in createUser() are valid for the site's member configuration.
6. Test in sandbox end-to-end — Auth providers use callback URLs that must match exactly. Test the full login round-trip in a sandbox with the real IdP before promoting to production.

Review Checklist

Run through these before marking work in this area complete:

• Auth provider callback URL registered with IdP matches services/authcallback/<ProviderName> on the correct domain
• Registration handler implements the correct interface for the flow type (standard vs headless)
• Custom login page type matches site engine (VF for Aura, LWC for LWR)
• LWC login page has lightningCommunity__Page in targets metadata and is deployed
• Federation ID populated and matches across both IdP and Salesforce user records
• Headless Identity enabled in org settings if using any headless or headless passwordless flow
• Sandbox end-to-end login test completed before production deployment

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Start SSO URL missing community parameter — When constructing the social login redirect URL, the community parameter (?community=<encoded-site-url>) tells Salesforce which site to return the user to after the IdP handshake. Omitting it causes the user to be redirected to the internal org login page instead of the community, with no error message.
2. VF login page silently ignored on LWR sites — Assigning a Visualforce page as the custom login page on an LWR site produces no error in Setup, but the site continues to render the default login page. The fix is to create an LWC with the lightningCommunity__Page target and assign it instead.
3. HeadlessSelfRegistrationHandler is a different interface than Auth.RegistrationHandler — The two interfaces share a createUser() method name but are entirely different Apex types. A class that implements Auth.RegistrationHandler cannot be assigned in the Headless Identity settings; doing so causes a runtime error. Implement Auth.HeadlessSelfRegistrationHandler for headless flows.

Output Artifacts

Related Skills

• security/ip-range-and-login-flow-strategy — Post-authentication login flows that run after Experience Cloud SSO completes; use when you need MFA enforcement or custom verification steps on top of social login