Set up SAML single sign-on

Use this process to let customers sign in to your store with a SAML 2.0 identity provider (IdP), such as Okta, OneLogin, PingFederate, or Salesforce acting as an IdP. Choose SAML when your organization manages its own identity infrastructure.

You supply StoreConnect with a single value: your IdP’s SAML metadata URL. StoreConnect fetches and parses that metadata to obtain the IdP’s entity ID, sign-in URL, and signing certificate, so there is no certificate to copy by hand.

SAML is one of several login methods StoreConnect supports. For the other providers and the login behavior they all share, see authentication providers and single sign-on (SSO).

Before you begin

• You need administrator access to your Salesforce org and to your identity provider.
• Have your IdP’s SAML metadata URL ready.
• Decide which store this login applies to — each SAML provider is configured against a specific store.

Step 1: Add the SAML option as an Authentication Provider

Authentication provider records do not include SAML as a provider option out of the box, so you need to add it before creating the record.

1. Go to Setup > Object Manager > Authentication Provider > Fields & Relationships > Provider.
2. Under Values, click New.
3. Enter saml as the value. It must be exactly saml, in lowercase, because this is the value StoreConnect matches on.
4. Select Save.

Step 2: Create the authentication provider record

1. On the store record, go to the Authentication Providers related list, and select New.

2. Configure the record as follows.

   StoreConnect Field	Value
   Provider	SAML
   Authorised Domains	Your IdP’s host (only needed if the IdP posts its response from a different domain than the metadata URL)
   Client Id
   Client Secret
   Provider URL	Your IdP’s SAML metadata URL
   Reset Password URL

3. Save the record and take note of the Salesforce record ID (the 15- or 18-character ID in the browser URL, referred to below as PROVIDER_SFID). It forms part of every SAML URL for this provider.

Step 3: Configure your identity provider

This step completes entirely in your IdP’s admin console. First give it StoreConnect’s service provider (SP) URLs, then set how it sends the assertion.

Enter StoreConnect’s service provider URLs

Use your store domain and the Salesforce record ID you recorded above to form the IdP settings you need. StoreConnect exposes them at a ‘convenience endpoint’. Open this URL in a browser and it returns the values as JSON:

https://your-store-domain/logins/auth/saml/PROVIDER_SFID/config

IdP setting	Value
Entity ID / Issuer	https://your-store-domain/logins/auth/saml/PROVIDER_SFID/metadata
Assertion Consumer Service (ACS) URL	https://your-store-domain/logins/auth/saml/PROVIDER_SFID/auth
Start URL	your store’s home page

StoreConnect also publishes the SP metadata as XML at the Entity ID URL above, which many IdPs can import directly.

Stores served on a path

If a store is served on a path rather than its own bare domain (for example a regional or geolocated store at https://your-store-domain/eu/), every SAML URL must include that path segment, immediately after the domain and before logins:

https://your-store-domain/store-path/logins/auth/saml/PROVIDER_SFID/config

The Entity ID, ACS URL, and sign-in link all follow the same pattern. Open the config endpoint on the store’s own path URL, as above, so the values it returns already include the path, then paste those into your IdP exactly as given.

:::warning If the URLs entered in the IdP omit the store path, the identity provider’s response will not match what the store expects, and sign-in fails with a message that SSO via SAML is not fully configured, even though the metadata URL still loads. This is the most common reason SAML works on a bare-domain store but not on a path-based one. :::

Configure the assertion

Configure your IdP to send the assertion as follows:

• NameID format — email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
• SSO binding — HTTP-Redirect
• Attributes — release these attributes so StoreConnect can populate the Contact:

SAML attribute	Used for
email (falls back to NameID if omitted)	Contact email and username
username (or id)	The stored SSO user identifier
firstName	Contact first name
lastName	Contact last name

Step 4: Verify and add a login link

Confirm the configuration by opening the SP metadata URL in a browser:

https://your-store-domain/logins/auth/saml/PROVIDER_SFID/metadata

If the Provider URL is valid, StoreConnect returns SP metadata XML. If it is misconfigured, the page returns an error instead of XML. Recheck the Provider URL on the authentication provider record. When a customer then attempts to sign in with a provider that is still not configured correctly, they see a message that SSO via SAML is not fully configured.

To start a login, the store’s SAML sign-in link submits to:

https://your-store-domain/logins/auth/saml/PROVIDER_SFID/sign_in

:::note This is a form POST target, not a link. Opening the sign_in URL directly in a browser returns a 404. That is expected, and does not mean the provider is misconfigured. Use the metadata URL above to confirm the provider is working. :::

Render the sign-in button in a custom theme

The default theme reads the store’s Authentication Providers and renders a sign-in button for each one. A custom theme with its own login template does not, so you need to render the button yourself. Until you do, customers have no way to start an SSO login.

There is no error message to work from. The Authentication Provider record is valid, the metadata URL returns the correct XML, and the login page shows only the username and password fields, as though no provider existed.

Add this to your theme’s login template, alongside the existing login form:

```liquid

{%- for provider in current_store.authentication_providers %}

Sign in with {{ provider.provider | upcase }}

{%- endfor %} ```

Use provider.sign_in_path rather than building the URL by hand. On a store served on a path, the store path is already included.

The snippet labels each button from provider.provider, which returns the provider type (saml). Replace it with your identity provider’s name if you want a friendlier label, for example Sign in with Okta. Do not label the button from provider.name: that returns the Salesforce record’s auto-number, such as AuthProvider-00001, and the Authentication Provider object has no writable display-name field.

For the full list of attributes, see the AuthenticationProvider object reference.

What happens on login

SAML supports new-account registration. When a customer signs in through SAML and no matching Contact exists, StoreConnect creates one using the attributes above.

For how StoreConnect matches returning customers to existing contacts, the fields saved on a new Contact, and logout behavior, see the shared sections in authentication providers and single sign-on (SSO).