Tenant Selection Page
When tenant selection is configured, AuthProxy serves a tenant-selection page after login until the user chooses a tenant.
The page receives tenant data through a cookie, not by calling your tenant endpoint directly.
- Authenticated request arrives without a
.cratis-tenantcookie. - AuthProxy calls the configured
Selection.Options.TenantsEndpoint. If the endpoint is unavailable or returns an unusable answer, AuthProxy returns503withservice-unavailable.htmlfor a browser navigation (a bare503for other callers); no tenant cookie is written. - If exactly one tenant is returned, AuthProxy sets
.cratis-tenantimmediately, removes any.cratis-tenantscookie, and redirects to the original URL (no selection page shown). - If more than one tenant is returned, AuthProxy writes
.cratis-tenants(URL-encoded JSON array) as a session cookie and servesselect-tenant.html— but only to a browser navigating to a page. Every other caller is refused with403instead, because a chooser page delivered as200reads as the data they asked for. See Unauthenticated responses. - User clicks a tenant option.
- Browser navigates to
/.cratis/select-tenant?tenantId=<id>&returnUrl=<path>. - AuthProxy validates the selected
tenantIdagainstTenantsEndpointand sets.cratis-tenant. If the endpoint is unavailable or returns an unusable answer, AuthProxy returns503withservice-unavailable.htmlinstead; no tenant cookie is written. - AuthProxy redirects back to
returnUrl. The.cratis-tenantscookie is retained so the application can offer an in-app tenant switcher.
Switching tenants after selection
Section titled “Switching tenants after selection”For a user with more than one tenant, .cratis-tenants is written as a session cookie and is
not deleted when a tenant is selected. It therefore remains available for the rest of the browser
session, which lets the application’s toolbar decide whether to show a “switch tenant” control (show it
only when the cookie lists more than one tenant).
To switch, the toolbar navigates to the same selection endpoint used by the selection page:
/.cratis/select-tenant?tenantId=<id>&returnUrl=<current path>Every switch re-validates the requested tenantId against TenantsEndpoint, so a stale cookie can
never grant access to a tenant the user is no longer a member of — an unknown tenantId is rejected
with 400 Bad Request.
Periodic re-validation of the selected tenant
Section titled “Periodic re-validation of the selected tenant”.cratis-tenant is a session cookie, but it is also not trusted indefinitely within a session:
AuthProxy re-validates the selected tenant against TenantsEndpoint when the configured
Cratis:AuthProxy:Session:TenantRevalidationInterval (default 10 minutes) has lapsed. A successful
re-validation is cached in memory, so the endpoint is not called on every request.
When the endpoint answers authoritatively that the tenant is no longer available to the user, the
.cratis-tenant and .cratis-tenants cookies are deleted and the request is replayed without them —
the user lands back in the regular selection flow (or the no-tenant handling when nothing remains).
Revoked tenant access therefore takes effect within the interval, without waiting for the browser
session to end. The selection is confirmed again on every request, including anonymous, invitation and registration paths,
and a tenant is forwarded only after it was confirmed for the signed-in account.
The cookie is tied to the account
Section titled “The cookie is tied to the account”.cratis-tenant is signed with the application’s Data Protection keys and tied to the account that selected
it, so a value copied from another browser or account is not accepted and is removed. Deployments with more
than one replica need a shared Data Protection key ring, as they already do for sessions. A cookie written by an
earlier version is confirmed against TenantsEndpoint on first use and reissued in the new form, which costs one
call per user after the upgrade.
When the endpoint cannot answer
Section titled “When the endpoint cannot answer”A tenant that has not been confirmed within the window is not forwarded while TenantsEndpoint cannot answer.
A normal request receives 503; on an anonymous or registration path the request continues with no tenant.
Setting TenantRevalidationInterval to zero means the signed selection is trusted until it changes, rather than
being checked again.
A user with exactly one tenant never receives .cratis-tenants (it is removed when the single
tenant is auto-selected), so no switcher is shown for single-tenant users.
Signed identity at the tenant endpoint
Section titled “Signed identity at the tenant endpoint”To call a tenant endpoint that requires Arc v1 signed identity, configure ForwardedIdentity with Audience, KeyId and secret-provider SecretBase64 on the selection resolver’s Options. Service-level signing does not cover this separate flow. Without this block, tenant calls retain unsigned legacy behavior. Signed calls do not follow redirects; signing refusal uses the existing unavailable response without confirming a tenant. See Forwarded identity signing for configuration and rollout order.
Endpoint response shape
Section titled “Endpoint response shape”TenantsEndpoint must return JSON with one object per selectable tenant:
[ { "id": "some string", "name": "some string" }]Cookie shape used by the page
Section titled “Cookie shape used by the page”AuthProxy writes .cratis-tenants with the same shape:
[ { "id": "studio", "name": "Cratis Studio" }, { "id": "sales", "name": "Sales Portal" }]Building a custom select-tenant.html
Section titled “Building a custom select-tenant.html”select-tenant.html is a normal overridable page in PagesPath, exactly like the other built-in pages.
Minimum requirements:
- Read
.cratis-tenantsfromdocument.cookie. - Parse JSON and render
name. - Link each item to
/.cratis/select-tenant?tenantId=<id>&returnUrl=<current path>.
Example:
<!DOCTYPE html><html lang="en"><head> <meta charset="utf-8" /> <title>Select tenant</title></head><body> <h1>Select tenant</h1> <ul id="tenants"></ul> <p id="error" hidden>Unable to load tenant options.</p>
<script> (function () { function getCookie(name) { var pattern = new RegExp('(?:^|; )' + name.replace(/([.*+?^=!:${}()|[\]\/\\])/g, '\\$1') + '=([^;]*)'); var match = document.cookie.match(pattern); return match ? decodeURIComponent(match[1]) : null; }
var json = getCookie('.cratis-tenants'); var tenants; try { tenants = JSON.parse(json); } catch (_) { tenants = null; }
if (!tenants || tenants.length === 0) { document.getElementById('error').hidden = false; return; }
var returnUrl = window.location.pathname + window.location.search; var list = document.getElementById('tenants');
tenants.forEach(function (tenant) { var li = document.createElement('li'); var a = document.createElement('a'); a.href = '/.cratis/select-tenant?tenantId=' + encodeURIComponent(tenant.id) + '&returnUrl=' + encodeURIComponent(returnUrl); a.textContent = tenant.name; li.appendChild(a); list.appendChild(li); }); }()); </script></body></html>