Use case example

This example shows how Jane signs in to your site, receives a JWT in a login cookie, and accesses Zuora Experiences based on her mapped role.

This example follows Jane from signing in to accessing a Zuora Experience.

Assume that:

Your domain is acme.com.
The cookie name configured in Zuora is idp_session.
Your login system has been configured to issue a compatible JWT and publish its public key through a JWKS URL.

Jane visits https://app.acme.com/login.

This is your page and can use your own design. Jane enters her email address and password, then selects Sign in.

Step 2 — Your login form calls your authentication service

The login form sends Jane’s credentials to your authentication service. The exact request format depends on your authentication system. For example:

POST https://login.acme.com/api/login
Content-Type: application/json
{
  "email": "jane@acme.com",
  "password": "<Jane's password>"
}

Your authentication service validates the credentials. The service, rather than the browser, determines the claims to include in the JWT.

Step 3 — Your authentication service creates or obtains the JWT

After validating Jane’s credentials, your authentication service creates a signed JWT or obtains a compatible JWT from your identity provider.

The JWT can contain claims such as:

{
  "sub": "jane@acme.com",
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "roles": ["billing-admin"]
}

The preceding example shows the claims in the JWT. It does not represent the login request.

In Case 1, your login system signs the JWT with your private key. In Case 2, your identity provider can provide the JWT, provided that it meets the requirements described in this guide, including the required sub claim, compatible signing, expiration, and any required role claims.

Step 4 — Your authentication service sets the cookie

After creating or obtaining the JWT, your authentication service returns it to the browser in the agreed cookie format:

HTTP/1.1 200 OK
Set-Cookie: idp_session=eyJhbGciOiJSUzI1Ni...; Path=/; HttpOnly; SameSite=None; Domain=.acme.com; Secure; Max-Age=7200
Content-Type: application/json
{ "ok": true }

Use the cookie-domain format required by your deployment so that the cookie is available to the relevant application and Experience subdomains.

The browser stores the idp_session cookie and sends it with subsequent requests to destinations covered by the cookie settings.

Step 5 — Your authentication service redirects Jane

After setting the cookie, your authentication service redirects Jane to the destination selected by your application. Both of the following destinations are supported:

Option A — A full Experience page

Jane is redirected to https://experiences.acme.com/portal. The page is a Zuora Experience. When it loads, Zuora reads the idp_session cookie, verifies the JWT, maps Jane’s billing-admin role to the configured Zuora role, and loads the Experience.

Option B — Your page with embedded Experience components

Jane is redirected to https://app.acme.com/dashboard. This is your page and layout. It includes one or more Zuora Experience components. The components read the same idp_session cookie and verify the JWT using the same process.

The login flow is the same for both destinations. You do not need a separate authentication flow for a full Experience page and a page that embeds Experience components.

Step 6 — Zuora verifies the JWT

When the Experience loads, Zuora performs the following steps automatically:

Reads the configured login cookie.
Retrieves the public key that matches the JWT’s kid value from the configured JWKS URL, or uses a cached copy of that key.
Verifies the JWT signature and confirms that the token has not expired.
Reads the sub claim and any available profile claims.
Reads the roles from the configured role claim path and applies the configured role mappings.

If these checks succeed, Jane can access the Experience according to her mapped role.

When the JWT expires, your authentication system must provide a valid replacement token or require Jane to sign in again, according to your implementation.