Use this guide for identity providers that use SAML 2.0, such as Okta (SAML), Microsoft Entra ID (Azure AD), ADFS, Google Workspace, OneLogin, Ping Identity or JumpCloud. If your identity provider supports OpenID Connect, you can also use OpenID Connect or Okta OpenID.

Step 1: Copy your store's SAML addresses from Zoey

In your Zoey Admin, open the Settings menu and click Single Sign-On. Click Add Identity Provider, give it a name and select Type SAML 2.0. Zoey shows the addresses your identity provider needs:

SP Entity ID / Metadata URL
Your store's Service Provider entity ID. If your identity provider can import metadata from a URL, give it this address.

ACS (Reply) URL
Also called Assertion Consumer Service URL, Reply URL or Single sign-on URL.

Single Logout URL
Shown after you save. Only needed if you turn on Sign Out of Identity Provider on Logout.

Keep this window open (or come back to it) while you set up the identity provider.

Step 2: Set up the application in your identity provider

Create a new SAML application (sometimes called an Enterprise Application or Custom SAML App) and enter:

• Single sign-on URL / ACS URL / Reply URL: the ACS (Reply) URL from Zoey
• Audience URI / Entity ID / Identifier: the SP Entity ID from Zoey
• Name ID format: Persistent (recommended) or Email Address
• Attributes: send the user's email as email, first name as firstName and last name as lastName. Other common names (such as mail, givenName, surname, and the Microsoft claim names) also work.
• Signing: sign the response or the assertion (the default for most providers)

Assign the users or groups who should be able to log in, then copy from the identity provider:

• Entity ID / Issuer
• Single Sign-On URL (HTTP-Redirect)
• X.509 signing certificate
• Single Logout URL (optional)

Step 3: Finish the setup in Zoey

Back in the Zoey identity provider, enter:

IdP Entity ID (Issuer)
The Entity ID / Issuer from your identity provider.

IdP Single Sign-On URL
The Single Sign-On URL from your identity provider. It must start with https://.

IdP X.509 Signing Certificate
Paste the signing certificate (with or without the BEGIN/END CERTIFICATE lines).

IdP Single Logout URL (optional)
Only needed for Sign Out of Identity Provider on Logout.

Email / First Name / Last Name Attribute (optional)
Fill these in only if your identity provider uses attribute names Zoey doesn't recognize.

Additional Settings

Show on Login Form
Adds a login button to the Zoey Customer Login page with the text in Login Button Label (default "Login with SSO").

Auto-Create Customers
Customers who log in with your identity provider and whose email is not yet in Zoey are created as a Contact, in the Customer Group set in Customer Group for Auto-Created Customers.

Sign Out of Identity Provider on Logout
When Yes and an IdP Single Logout URL is set, logging out of the store also signs the customer out of the identity provider.

Account Attribute
Optional. The name of an attribute your identity provider sends (for example account_id) whose value matches an Account's External ID in Zoey. Customers who are not on any Account yet are added to that Account when they log in. Customers already on an Account are never moved.

Click Save.

Good to know

• Logins must start from the store (the login button). Logins started from the identity provider's own app dashboard are not accepted.
• Once a user has logged in, Zoey remembers which customer they are, even if their email changes later in the identity provider. Other users are matched to Zoey Contacts by email address.
• After logging in, customers return to the page they were on.