Skip to navigation
ExtensibilityExperience BuilderExternal authentication with a custom login system

Quick checklist to go live

View as Markdown

Use this checklist to configure JWT-based single sign-on for Zuora Experience, whether you are creating new keys and a JWKS or using an existing identity provider.

Case 1 - You are creating the keys and JWKS

  • Create an RSA key pair. Keep the private key secret.
  • Publish the public key at a /.well-known/jwks.json URL that Zuora can reach. Include a kid value so Zuora can identify the key.
  • Build a login endpoint that validates the user, creates a signed JWT containing at least sub, and includes exp to define the token lifetime.
  • Set the login cookie from your server by using the cookie name and attributes defined in Section 5.
  • Choose a cookie domain that is a common parent domain for the login and destination hosts. For example, use Domain=yourdomain.com. A leading dot is not required.
  • Configure the Zuora tenant settings: JWKS URL, cookie name, role claim path, and role mappings.
  • Redirect the user to the destination. This can be a full Experience page or your own page with embedded Experience components.

Case 2 - You already have a JWKS URL or identity provider

  • Give Zuora your existing JWKS URL and the settings defined in Section 4.
  • Confirm that the JWT placed in the configured cookie contains the required sub claim.
  • Include an exp claim so the token has a defined expiration time.
  • Confirm that the JWT is signed by a key published in the configured JWKS and that its kid identifies the correct key.
  • Point the role claim path to the location of the roles in the JWT, such as realm_access.roles, and add mappings for your role names.
  • After the identity provider authenticates the user, set the JWT in the browser as the configured cookie by using the exact cookie name and server-side Set-Cookie format defined in Section 5.
  • Ensure that every destination host is within the cookie’s domain scope. A cookie cannot be shared across different registrable domains.
  • You do not need to create new keys or publish a new JWKS. Skip those steps.
  • Redirect the user to the destination. This can be a full Experience page or your own page with embedded Experience components.

Test the following scenarios:

  • A valid JWT signs the user in successfully.
  • A JWT without sub is rejected.
  • An expired JWT is rejected.
  • Role claims are mapped to the expected Experience roles.
  • An unmapped role falls back to the configured default role.
  • Key rotation works as expected when the kid changes.
  • The cookie is available on every supported destination host.