User email is globally unique.
Tenant can be inferred from subdomain.
All tenants use the same IdP.
Token issuer is enough.
One session can switch tenant safely.
Admin in tenant A is admin everywhere.

Which tenant is this authentication attempt for?
Which identity provider is authoritative for that tenant?
Which account/membership does the external identity map to?
Which tenant boundary is bound to the resulting session/token?

No authenticated principal exists without an explicit tenant context
unless the operation is intentionally tenant-discovery or global-admin scoped.

account berbeda di tenant berbeda
external identity berbeda per enterprise tenant
email sama tapi issuer berbeda
membership aktif di tenant A, suspended di tenant B
MFA requirement berbeda per tenant

(issuer, subject)

(tenant_id, account_id)

Pre-auth browser login:
  subdomain/custom domain/identity-first discovery

API request with token:
  issuer + audience + tenant claim validation

Internal service call:
  mTLS/service identity + explicit tenant context

Admin/global operation:
  explicit global scope + audited tenant selection

state must bind tenant id
redirect_uri must match tenant/client registration
issuer must match tenant policy
subject must map to account
membership must be active for tenant
session must be bound to tenant

TenantResolvedUnauthenticated

External identity is valid, but not valid for this tenant.

public record TenantAuthenticatedPrincipal(
        String accountId,
        String tenantId,
        String subject,
        String issuer,
        String sessionId,
        String assuranceLevel,
        Set<String> roles,
        Instant authenticatedAt
) implements Serializable {}

Every authenticated session is bound to exactly one active tenant context,
or is a clearly marked global-admin session with explicit tenant switching controls.

login tenant-a -> session tenant-a
switch tenant-b -> new auth/session or verified tenant switch event

login once -> account session
select active tenant -> tenant-bound context inside session

Set-Cookie: SESSION=abc; Domain=.app.com; Path=/; Secure; HttpOnly; SameSite=Lax

tenant-a.app.com
tenant-b.app.com

Cookie scope must not be broader than the trust boundary you can enforce.

{
  "iss": "https://idp.example.com/realms/tenant-a",
  "sub": "f7b4a9d2-...",
  "aud": "case-api",
  "azp": "web-bff",
  "exp": 1783070400,
  "iat": 1783066800,
  "tenant_id": "tenant-a",
  "org_id": "tenant-a",
  "membership_id": "mbr_123",
  "membership_version": 42,
  "acr": "aal2",
  "amr": ["pwd", "otp"],
  "scope": "case:read case:write"
}

tenant_id is a claim.
issuer + signature + audience + trust config make it meaningful.

https://idp.example.com/realms/tenant-a
https://idp.example.com/realms/tenant-b

strong isolation
separate keys/policies/clients
enterprise customization
simple tenant inference from iss

operational overhead
many realms/clients
cross-tenant user journey harder
key rotation/config scaling

iss=https://idp.example.com/realms/saas
org_id=tenant-a

simpler operations
shared login UX
shared clients
better for many small tenants

tenant isolation relies on claims/policy
misconfiguration can leak roles
custom enterprise federation harder

small tenants -> shared realm/org model
enterprise tenants -> dedicated realm/issuer
regulated tenants -> dedicated IdP or brokered federation

If tenant-specific identity policy, federation, keys, compliance, or blast-radius isolation matters strongly, prefer dedicated issuer/realm.
If operational scale and uniform policy matter more, use shared issuer with strong organization/tenant claim controls.

public interface TenantResolver {
    Optional<TenantAuthConfig> resolve(HttpServletRequest request);
}

public record TenantAuthConfig(
        String tenantId,
        String issuer,
        String jwkSetUri,
        Set<String> audiences
) {}

@Bean
AuthenticationManagerResolver<HttpServletRequest> tenantAuthenticationManagerResolver(
        TenantResolver tenantResolver,
        JwtDecoderFactory<TenantAuthConfig> decoderFactory
) {
    ConcurrentMap<String, AuthenticationManager> managers = new ConcurrentHashMap<>();

    return request -> {
        TenantAuthConfig tenant = tenantResolver.resolve(request)
                .orElseThrow(() -> new BadCredentialsException("Unknown tenant"));

        return managers.computeIfAbsent(tenant.tenantId(), key -> {
            JwtAuthenticationProvider provider = new JwtAuthenticationProvider(decoderFactory.createDecoder(tenant));
            provider.setJwtAuthenticationConverter(tenantAwareJwtAuthenticationConverter(tenant));
            return provider::authenticate;
        });
    };
}

@Bean
SecurityFilterChain apiSecurity(
        HttpSecurity http,
        AuthenticationManagerResolver<HttpServletRequest> resolver
) throws Exception {
    return http
            .csrf(csrf -> csrf.disable())
            .oauth2ResourceServer(oauth2 -> oauth2.authenticationManagerResolver(resolver))
            .authorizeHttpRequests(auth -> auth
                    .requestMatchers("/actuator/health").permitAll()
                    .anyRequest().authenticated()
            )
            .build();
}

public final class TenantJwtDecoderFactory implements JwtDecoderFactory<TenantAuthConfig> {

    @Override
    public JwtDecoder createDecoder(TenantAuthConfig tenant) {
        NimbusJwtDecoder decoder = NimbusJwtDecoder.withJwkSetUri(tenant.jwkSetUri()).build();

        OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer(tenant.issuer());
        OAuth2TokenValidator<Jwt> withAudience = jwt -> {
            boolean ok = jwt.getAudience().stream().anyMatch(tenant.audiences()::contains);
            return ok
                    ? OAuth2TokenValidatorResult.success()
                    : OAuth2TokenValidatorResult.failure(new OAuth2Error("invalid_token", "Invalid audience", null));
        };
        OAuth2TokenValidator<Jwt> withTenant = jwt -> {
            String tenantId = jwt.getClaimAsString("tenant_id");
            return tenant.tenantId().equals(tenantId)
                    ? OAuth2TokenValidatorResult.success()
                    : OAuth2TokenValidatorResult.failure(new OAuth2Error("invalid_token", "Invalid tenant", null));
        };

        decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(withIssuer, withAudience, withTenant));
        return decoder;
    }
}

Tenant resolution and token validation must agree.

public final class TenantContextHolder {
    private static final ThreadLocal<String> TENANT = new ThreadLocal<>();

    public static void set(String tenantId) {
        TENANT.set(Objects.requireNonNull(tenantId));
    }

    public static String requireTenantId() {
        String tenantId = TENANT.get();
        if (tenantId == null) {
            throw new IllegalStateException("Tenant context missing");
        }
        return tenantId;
    }

    public static void clear() {
        TENANT.remove();
    }
}

public final class TenantContextFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        try {
            Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
            if (authentication instanceof JwtAuthenticationToken jwtAuth) {
                String tenantId = jwtAuth.getToken().getClaimAsString("tenant_id");
                TenantContextHolder.set(tenantId);
            }
            filterChain.doFilter(request, response);
        } finally {
            TenantContextHolder.clear();
        }
    }
}

ThreadLocal tenant context must be cleared exactly like SecurityContext.

login request tenant -> client registration -> state -> callback -> session tenant

state=randomOnly

state = signed(random + tenantId + redirectIntent + issuedAt)

state tenant must equal tenant from callback route/session
issuer must equal tenant expected issuer
token nonce must match original login request

email=alice@example.com from issuer A
email=alice@example.com from issuer B

same verified issuer+subject already known
or explicit admin-approved federation mapping
or user-authenticated linking ceremony with step-up

create table account_login_identifier (
    tenant_id text not null,
    identifier_normalized text not null,
    account_id uuid not null,
    primary key (tenant_id, identifier_normalized)
);

create table account_password_credential (
    credential_id uuid primary key,
    tenant_id text not null,
    account_id uuid not null,
    password_hash text not null,
    password_version int not null default 1,
    status text not null,
    created_at timestamptz not null,
    updated_at timestamptz not null,
    unique (tenant_id, account_id)
);

resolve tenant
normalize identifier
lookup (tenant_id, identifier)
if missing -> synthetic password verification
if found -> verify credential
check membership status
check tenant policy/MFA
create tenant-bound session

Invalid username or password.

unknown tenant
unknown email in this tenant
email exists in another tenant
membership suspended
federated-only user

source_ip
tenant_id
identifier_hash
tenant_id + identifier_hash
client_id
device_fingerprint
asn/country risk bucket

auth:rl:ip:203.0.113.10
auth:rl:tenant:tenant-a:ip:203.0.113.10
auth:rl:tenant:tenant-a:identifier:sha256(email)
auth:rl:client:web-bff

public record AuthenticatedTenantPrincipal(
        String accountId,
        String tenantId,
        String membershipId,
        int membershipVersion,
        Set<String> authorities,
        String issuer,
        String subject
) {}

Authentication validates identity and tenant membership.
Authorization evaluates permissions only within that authenticated tenant boundary.

@GetMapping("/tenants/{tenantId}/cases/{caseId}")
public CaseDto get(@PathVariable String tenantId, @PathVariable String caseId) {
    return caseService.get(tenantId, caseId);
}

@GetMapping("/cases/{caseId}")
public CaseDto get(@AuthenticationPrincipal AuthenticatedTenantPrincipal principal,
                   @PathVariable String caseId) {
    return caseService.get(principal.tenantId(), caseId);
}

if (!pathTenantId.equals(principal.tenantId())) {
    throw new AccessDeniedException("Tenant mismatch");
}

create table regulatory_case (
    tenant_id text not null,
    case_id uuid not null,
    title text not null,
    status text not null,
    created_by_account_id uuid not null,
    created_at timestamptz not null,
    primary key (tenant_id, case_id)
);

Optional<CaseEntity> findByTenantIdAndCaseId(String tenantId, UUID caseId);

Optional<CaseEntity> findByCaseId(UUID caseId);

{
  "tenant_id": "tenant-a",
  "acr": "aal2",
  "amr": ["federated", "webauthn"]
}

if (!principal.assuranceLevel().atLeast("aal2")) {
    throw new StepUpRequiredException("AAL2 required for enforcement decision");
}

User is admin in tenant A.
Request includes tenantId=tenant B.
Service checks user has ADMIN somewhere.
Service mutates tenant B.

User has ADMIN membership in tenant B.

ROLE_ADMIN

TENANT_ADMIN scoped to tenant_id=tenant-b

@PreAuthorize("hasRole('ADMIN')")

@PreAuthorize("@tenantAuthz.canManageCase(authentication, #caseId)")

Request host: tenant-a.app.com
Authorization token: valid token for tenant-b

resolvedTenantFromRequest == token.tenant_id == expected issuer mapping

public void assertTenantConsistency(HttpServletRequest request, Jwt jwt) {
    String routeTenant = tenantResolver.resolveFromRequest(request)
            .orElseThrow(() -> new BadCredentialsException("Unknown tenant"));

    String tokenTenant = jwt.getClaimAsString("tenant_id");

    if (!routeTenant.equals(tokenTenant)) {
        throw new BadCredentialsException("Tenant mismatch");
    }
}

Enter your email to continue

No enterprise SSO configured for alice@example.com

If this account can sign in, we will continue to the appropriate sign-in method.

generic response text
rate limiting per IP/email hash
delayed response normalization
tenant domain verification
optional email magic link for ambiguous routing
admin-controlled domain-to-tenant mapping
no disclosure of tenant membership before proof

example.com -> tenant-a IdP

support_actor_id = employee_123
acting_tenant_id = tenant-a
impersonated_account_id = user_456 optional
reason_code = support_ticket_789
approval_id = approval_abc optional
expires_at = short TTL

{
  "actor_type": "SUPPORT_OPERATOR",
  "actor_id": "employee_123",
  "tenant_id": "tenant-a",
  "on_behalf_of_account_id": "user_456",
  "reason": "support_ticket_789"
}

Support access must never erase the real authenticated operator.

auth.tenant_resolution.failure.count{method,reason}
auth.login.success.count{tenant,provider}
auth.login.failure.count{tenant,reason_class}
auth.token_rejected.count{reason,issuer,route_tenant}
auth.cross_tenant_mismatch.count{route_tenant,token_tenant}
auth.membership_rejected.count{tenant,status}

sudden spike in tenant mismatch
unknown issuer tokens appear
login failures concentrated on one tenant
same account tries many tenants
support access outside business hours

known subdomain -> tenant resolved
unknown subdomain -> generic reject
custom domain unverified -> reject
header tenant from public internet -> reject
host tenant A + path tenant B -> reject

token issuer A on tenant A route -> accept
token issuer B on tenant A route -> reject
token valid signature but wrong audience -> reject
token valid issuer but missing tenant claim -> reject
token tenant claim mismatch -> reject
expired token -> reject
unknown kid -> reject or refresh JWKS under bounded policy

valid external identity but no tenant membership -> reject
suspended membership -> reject
membership version stale -> refresh or reject
admin in tenant A accessing tenant B -> reject
user belongs to A and B but active session A accessing B route -> reject unless explicit switch

session tenant A used on tenant B host -> reject
tenant switch rotates session or records switch event
logout tenant A does not leave active tenant A session elsewhere unless intended
cookie domain does not leak across tenant subdomains

same email from two issuers does not auto-link
issuer subject change handled through explicit migration
SAML assertion audience mismatch rejected
OIDC state tenant mismatch rejected

1. Introduce tenant table and explicit default tenant.
2. Add tenant_id to auth/account/session tables.
3. Change identity keys from email/global user to tenant-aware account/membership.
4. Add tenant resolver at request boundary.
5. Bind sessions/tokens to tenant.
6. Update repositories to require tenant_id.
7. Add tenant mismatch detection logs in shadow mode.
8. Enforce tenant mismatch rejection.
9. Add per-tenant IdP/federation support.
10. Add operational dashboards and runbooks.

legacy account without tenant -> mapped to default tenant
legacy session -> upgraded to tenant-bound session at next request
legacy token -> short TTL, migration-only acceptance

[ ] Tenant is treated as a security boundary, not only a UI filter.
[ ] Tenant resolution is explicit before login routing.
[ ] OIDC/SAML state binds tenant and redirect intent.
[ ] Token issuer, audience, tenant claim, and request tenant are validated together.
[ ] Account mapping uses issuer+subject, not email alone.
[ ] Session is bound to tenant.
[ ] Cookie domain/path matches tenant isolation model.
[ ] Local password credential lookup is tenant-aware.
[ ] Rate limiting includes tenant, identifier, IP/device, and global dimensions.
[ ] Authorization receives tenant-bound principal from authentication.
[ ] Data repositories require tenant_id for tenant-owned objects.
[ ] Admin/support access records real operator and target tenant.
[ ] Logs and metrics include tenant context without leaking tokens.
[ ] Test suite includes wrong issuer, wrong tenant, wrong audience, same email/different issuer, and unscoped admin cases.

This subject, from this trusted identity authority,
is authenticated into this tenant boundary,
with this account membership,
under this assurance level,
for this session/token/client.

JWT valid.

Every authenticated principal must be tenant-bound before it can touch tenant-owned state.