Use this guide for any OpenID Connect (OIDC) identity provider, such as Auth0, Microsoft Entra ID (Azure AD), Google, Keycloak, OneLogin, Ping Identity or your own OIDC server. Using Okta? Follow Okta OpenID instead.

Setup in your identity provider

Every identity provider names these screens a little differently, but the steps are the same.

Create a new application (sometimes called an App Registration, Client or App Integration):

Application type
Web Application (a confidential client that has a Client Secret)

Sign-in method / protocol
OpenID Connect

Grant type
Authorization Code

Sign-in redirect URI (also called Callback URL or Reply URL)

https://yourzoeystore.com/singlesignon_router/callback/openidconnect/

Zoey also shows this exact address, ready to copy, when you choose Type OpenID Connect in Zoey.

Sign-out redirect URI (needed only for Sign Out of Identity Provider on Logout)

https://yourzoeystore.com/customer/account/logout

PKCE
Make sure Proof Key for Code Exchange (PKCE) is allowed for the application. Most providers allow it by default.

Scopes
Allow the scopes openid, email and profile.

Controlled access
Assign the users or groups who should be able to log in to the store.

Save the application and copy its Client ID and Client Secret. You will also need your provider's Issuer URL.

---

Setup OpenID Connect in Zoey

In your Zoey Admin, open the Settings menu and click Single Sign-On.

Click Add Identity Provider.

Provide an Identity Provider Name and select Type OpenID Connect. This will prompt the configuration fields to appear. Enter the following values:

Issuer URL
The Issuer URL of your identity provider. It must start with https://.

Client ID
The Client ID of the application you created.

Client Secret
The Client Secret of the application you created.

Additional Settings

Show on Login Form
This will trigger a login link to appear on the Zoey Customer Login page with the text provided in Login Button Label (default "Login with SSO").

Auto-Create Customers
This will allow customers who log in with your identity provider whose email is not yet in Zoey to automatically be created as a Contact in Zoey. Automatically created Contacts will be assigned to the Customer Group specified in the Customer Group for Auto-Created Customers setting.

Sign Out of Identity Provider on Logout
When Yes, logging out of the store also signs the customer out of your identity provider (if it supports sign-out). Register the sign-out redirect URI above.

Account Attribute
Optional. The name of a claim 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. Zoey contacts your identity provider to check the Issuer URL. If the save fails, check that the Issuer URL is correct and that the /.well-known/openid-configuration page opens.

Good to know

• 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.
• If your identity provider reports a user's email as not verified, Zoey will not log them in.
• Your identity provider must support the Authorization Code flow with PKCE, accept the Client Secret in the token request body (client_secret_post, the default for most providers) and return the user's email from its userinfo endpoint. given_name and family_name are used as the name of auto-created customers.