"The user is authenticated, therefore the tenant is implied."

How do we prove that every identity, token, request, resource, policy decision,
query, event, cache entry, and audit record is bound to the correct tenant boundary?

Given an enterprise API platform, you can identify every tenant boundary,
define a deterministic tenant resolution strategy, enforce tenant-aware authorization,
prevent cross-tenant reads/writes/events/caches, and design tests that catch tenant escape.

You stop asking, "Where do I put tenant_id?"
and start asking, "What tenant assertion is trusted at this boundary, and how is it verified?"

Authentication establishes who/what the caller is.
Tenant resolution establishes which isolation boundary the request claims to operate in.
Authorization proves that the caller may perform the requested action inside that tenant boundary.

GET /cases?tenantId=tenant-a

request tenant assertion
        ↓
trusted tenant resolution
        ↓
token/issuer/client validation against tenant
        ↓
active tenant context
        ↓
resource tenant check
        ↓
query predicate / data partition
        ↓
audit record includes tenant decision evidence

permit = authenticated
      AND token_trusted_for_tenant
      AND subject_member_of_tenant
      AND client_allowed_for_tenant
      AND action_allowed_in_tenant
      AND resource_belongs_to_tenant
      AND data_access_constrained_to_tenant

{
  "iss": "https://idp.example.com",
  "sub": "user-123",
  "aud": "case-api",
  "tenant_id": "tenant-a",
  "scope": "case:read case:write",
  "roles": ["case-manager"]
}

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

Default to a shared platform issuer or hybrid federation unless tenant isolation requirements justify issuer-per-tenant complexity.
But regardless of issuer strategy, never rely on issuer alone as the full authorization decision.

Which tenant is this request attempting to operate in?

Is the caller allowed to operate in that tenant?

If path says tenant-a and token says tenant-b, reject.
Do not silently choose one.

Invariant 1: Active tenant must be explicit for tenant-scoped operations.
Invariant 2: Active tenant must come from a configured resolution strategy.
Invariant 3: Conflicting tenant assertions must fail closed.
Invariant 4: Tenant context must not be inferred only from a user-controlled object ID.
Invariant 5: Tenant context must not be stored only in ThreadLocal without cleanup.
Invariant 6: Tenant context must be included in authorization, data access, cache, events, logs, and traces.

public record TenantId(String value) {
    public TenantId {
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("tenant id is required");
        }
        if (!value.matches("[a-zA-Z0-9._-]{3,100}")) {
            throw new IllegalArgumentException("invalid tenant id format");
        }
    }
}

public record TenantContext(
        TenantId activeTenant,
        TenantResolutionSource source,
        boolean tenantSwitch,
        String correlationId
) {
}

public enum TenantResolutionSource {
    HOST,
    PATH,
    TOKEN_CLAIM,
    SERVER_SESSION,
    CLIENT_REGISTRATION,
    GATEWAY_SIGNED_HEADER
}

String tenant;

public record TenantAwarePrincipal(
        String subject,
        String issuer,
        String clientId,
        TenantId activeTenant,
        Set<TenantMembership> memberships,
        Set<String> activeTenantAuthorities,
        AssuranceLevel assuranceLevel
) {
    public boolean memberOf(TenantId tenantId) {
        return memberships.stream().anyMatch(m -> m.tenantId().equals(tenantId) && m.active());
    }
}

public record TenantMembership(
        TenantId tenantId,
        String accountId,
        Set<String> roles,
        Set<String> entitlements,
        boolean active
) {
}

A role without tenant scope is rarely safe in a multi-tenant product.

tenant-a:case-manager
tenant-b:viewer

ROLE_CASE_MANAGER

{
  "iss": "https://idp.example.com",
  "sub": "user-123",
  "aud": "case-api",
  "tenant_id": "tenant-a",
  "scope": "case:read case:write",
  "exp": 1782600000
}

{
  "iss": "https://idp.example.com",
  "sub": "user-123",
  "aud": "case-api",
  "tenants": [
    { "id": "tenant-a", "roles": ["case-manager"] },
    { "id": "tenant-b", "roles": ["viewer"] }
  ]
}

For high-value enterprise APIs, prefer short-lived access tokens with explicit active tenant,
then validate membership/resource ownership at runtime for sensitive operations.

request -> resolve tenant/issuer -> choose JwtDecoder/AuthenticationManager -> validate token -> build Authentication

@Configuration
@EnableWebSecurity
class SecurityConfig {

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

@Component
final class TenantAuthenticationManagerResolver
        implements AuthenticationManagerResolver<HttpServletRequest> {

    private final TenantResolver tenantResolver;
    private final TenantIssuerRegistry issuerRegistry;
    private final ConcurrentMap<TenantId, AuthenticationManager> managers = new ConcurrentHashMap<>();

    TenantAuthenticationManagerResolver(TenantResolver tenantResolver,
                                        TenantIssuerRegistry issuerRegistry) {
        this.tenantResolver = tenantResolver;
        this.issuerRegistry = issuerRegistry;
    }

    @Override
    public AuthenticationManager resolve(HttpServletRequest request) {
        TenantId tenantId = tenantResolver.resolve(request)
                .orElseThrow(() -> new BadCredentialsException("Tenant is required"));

        TenantIssuer issuer = issuerRegistry.findActiveIssuerForTenant(tenantId)
                .orElseThrow(() -> new BadCredentialsException("Unknown tenant issuer"));

        return managers.computeIfAbsent(tenantId, ignored -> managerFor(issuer));
    }

    private AuthenticationManager managerFor(TenantIssuer issuer) {
        NimbusJwtDecoder decoder = NimbusJwtDecoder
                .withIssuerLocation(issuer.issuerUri())
                .build();

        OAuth2TokenValidator<Jwt> validator = new DelegatingOAuth2TokenValidator<>(
                JwtValidators.createDefaultWithIssuer(issuer.issuerUri()),
                new AudienceValidator(issuer.allowedAudiences()),
                new TenantClaimValidator(issuer.tenantId())
        );

        decoder.setJwtValidator(validator);

        JwtAuthenticationProvider provider = new JwtAuthenticationProvider(decoder);
        provider.setJwtAuthenticationConverter(new TenantJwtAuthenticationConverter());
        return provider::authenticate;
    }
}

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

@Component
final class StrictTenantResolver implements TenantResolver {

    @Override
    public Optional<TenantId> resolve(HttpServletRequest request) {
        Optional<TenantId> pathTenant = fromPath(request);
        Optional<TenantId> hostTenant = fromHost(request);
        Optional<TenantId> signedHeaderTenant = fromSignedGatewayHeader(request);

        Set<TenantId> candidates = Stream.of(pathTenant, hostTenant, signedHeaderTenant)
                .flatMap(Optional::stream)
                .collect(Collectors.toSet());

        if (candidates.size() > 1) {
            throw new BadCredentialsException("Conflicting tenant assertions");
        }

        return candidates.stream().findFirst();
    }

    private Optional<TenantId> fromPath(HttpServletRequest request) {
        // Example only: use routing metadata rather than fragile string parsing in real systems.
        String uri = request.getRequestURI();
        Matcher matcher = Pattern.compile("^/tenants/([^/]+)/.*").matcher(uri);
        return matcher.matches() ? Optional.of(new TenantId(matcher.group(1))) : Optional.empty();
    }

    private Optional<TenantId> fromHost(HttpServletRequest request) {
        String host = request.getServerName();
        if (host.endsWith(".api.example.com")) {
            String subdomain = host.substring(0, host.length() - ".api.example.com".length());
            return Optional.of(new TenantId(subdomain));
        }
        return Optional.empty();
    }

    private Optional<TenantId> fromSignedGatewayHeader(HttpServletRequest request) {
        String tenant = request.getHeader("X-Verified-Tenant");
        String signature = request.getHeader("X-Verified-Tenant-Signature");

        if (tenant == null) {
            return Optional.empty();
        }
        if (!verifyGatewaySignature(tenant, signature)) {
            throw new BadCredentialsException("Invalid tenant header signature");
        }
        return Optional.of(new TenantId(tenant));
    }

    private boolean verifyGatewaySignature(String tenant, String signature) {
        // Example only. Use HMAC or mTLS-authenticated gateway metadata in real systems.
        return signature != null && !signature.isBlank();
    }
}

If the public internet can set X-Tenant-Id, it is not a trusted tenant assertion.

String issuer = request.getHeader("X-Issuer");
JwtDecoder decoder = JwtDecoders.fromIssuerLocation(issuer);

public interface TenantIssuerRegistry {
    Optional<TenantIssuer> findActiveIssuerForTenant(TenantId tenantId);
}

public record TenantIssuer(
        TenantId tenantId,
        String issuerUri,
        Set<String> allowedAudiences,
        Set<String> allowedClientIds,
        boolean active
) {
}

- tenant must exist;
- tenant must be active;
- issuer URI must be allowlisted;
- allowed audiences must be explicit;
- allowed clients must be explicit for sensitive APIs;
- disabled tenant must stop accepting tokens quickly;
- registry changes must be audited.

final class TenantClaimValidator implements OAuth2TokenValidator<Jwt> {

    private final TenantId expectedTenant;

    TenantClaimValidator(TenantId expectedTenant) {
        this.expectedTenant = expectedTenant;
    }

    @Override
    public OAuth2TokenValidatorResult validate(Jwt token) {
        String claim = token.getClaimAsString("tenant_id");

        if (claim == null) {
            OAuth2Error error = new OAuth2Error(
                    "invalid_token",
                    "Missing tenant_id claim",
                    null
            );
            return OAuth2TokenValidatorResult.failure(error);
        }

        if (!expectedTenant.equals(new TenantId(claim))) {
            OAuth2Error error = new OAuth2Error(
                    "invalid_token",
                    "Token tenant does not match request tenant",
                    null
            );
            return OAuth2TokenValidatorResult.failure(error);
        }

        return OAuth2TokenValidatorResult.success();
    }
}

return new SimpleGrantedAuthority("ROLE_ADMIN");

return new SimpleGrantedAuthority("TENANT_" + tenantId.value() + "_ROLE_ADMIN");

final class TenantJwtAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {

    @Override
    public AbstractAuthenticationToken convert(Jwt jwt) {
        TenantId tenantId = new TenantId(jwt.getClaimAsString("tenant_id"));
        String subject = jwt.getSubject();
        String issuer = jwt.getIssuer().toString();
        String clientId = jwt.getClaimAsString("client_id");

        Set<String> roles = Optional.ofNullable(jwt.getClaimAsStringList("roles"))
                .orElse(List.of())
                .stream()
                .collect(Collectors.toUnmodifiableSet());

        TenantAwarePrincipal principal = new TenantAwarePrincipal(
                subject,
                issuer,
                clientId,
                tenantId,
                Set.of(new TenantMembership(tenantId, subject, roles, Set.of(), true)),
                roles,
                AssuranceLevel.UNKNOWN
        );

        Collection<GrantedAuthority> authorities = roles.stream()
                .map(role -> new SimpleGrantedAuthority("TENANT_ROLE_" + role))
                .map(GrantedAuthority.class::cast)
                .toList();

        return new JwtAuthenticationToken(jwt, authorities, subject);
    }
}

GET /tenants/tenant-a/cases/case-999

active tenant == resource tenant

public CaseView getCase(TenantAwarePrincipal principal, TenantId tenantId, UUID caseId) {
    authorization.requireTenantMember(principal, tenantId);

    CaseEntity caze = caseRepository.findVisibleByTenantAndId(tenantId, caseId)
            .orElseThrow(NotFoundException::new);

    authorization.requireCanReadCase(principal, caze);

    return CaseView.from(caze);
}

@Query("""
       select c
       from CaseEntity c
       where c.tenantId = :tenantId
         and c.id = :caseId
       """)
Optional<CaseEntity> findVisibleByTenantAndId(TenantId tenantId, UUID caseId);

POST /tenants/tenant-a/cases

CaseEntity entity = new CaseEntity(request.tenantId(), request.title());

CaseEntity entity = CaseEntity.open(
        tenantIdFromRouteAndSecurityContext,
        request.title(),
        principal.subject()
);

For tenant-scoped create operations, tenant comes from verified security/routing context, not from request body.

@Transactional
public void assignCase(TenantAwarePrincipal principal,
                       TenantId tenantId,
                       UUID caseId,
                       String assigneeAccountId) {
    CaseEntity caze = caseRepository.findByTenantIdAndIdForUpdate(tenantId, caseId)
            .orElseThrow(NotFoundException::new);

    decisionService.require(principal, "case.assign", caze);

    if (!membershipRepository.isActiveMember(tenantId, assigneeAccountId)) {
        throw new DomainRuleViolation("Assignee is not active in tenant");
    }

    caze.assignTo(assigneeAccountId);

    audit.log(AuditEvent.caseAssigned(
            tenantId,
            caseId,
            principal.subject(),
            assigneeAccountId
    ));
}

Optional<Invoice> findByTenantIdAndInvoiceId(TenantId tenantId, UUID invoiceId);

Optional<Invoice> findByInvoiceId(UUID invoiceId);

alter table cases
add constraint uq_cases_tenant_external_ref unique (tenant_id, external_ref);

create table case_tasks (
    tenant_id text not null,
    case_id uuid not null,
    task_id uuid not null,
    primary key (tenant_id, task_id),
    foreign key (tenant_id, case_id) references cases (tenant_id, case_id)
);

- Every indexed document includes tenant_id.
- Every search query includes tenant filter.
- Every facet/count/aggregation includes tenant filter.
- Reindex jobs preserve tenant_id.
- Cross-tenant admin search is separate and audited.

@Cacheable("caseSummary")
public CaseSummary summary(UUID caseId) { ... }

@Cacheable(cacheNames = "caseSummary", key = "#tenantId.value() + ':' + #caseId")
public CaseSummary summary(TenantId tenantId, UUID caseId) { ... }

public record TenantCacheKey(TenantId tenantId, String namespace, String key) {
    public TenantCacheKey {
        Objects.requireNonNull(tenantId);
        Objects.requireNonNull(namespace);
        Objects.requireNonNull(key);
    }
}

cache.evict(new TenantCacheKey(tenantId, "case", caseId.toString()));

{
  "eventId": "evt-123",
  "tenantId": "tenant-a",
  "type": "case.assigned",
  "subject": "case-999",
  "occurredAt": "2026-06-28T12:00:00Z",
  "actor": {
    "type": "user",
    "subject": "user-123"
  }
}

- Every tenant-scoped event includes tenantId.
- Consumers reject tenant-scoped events without tenantId.
- Consumer authorization uses event tenant, not consumer default tenant.
- Dead-letter queues preserve tenantId.
- Replay jobs preserve tenantId.
- Event subscriptions are tenant-scoped unless explicitly platform-scoped.

void handle(CaseAssigned event) {
    TenantContext.set(currentTenantFromThreadLocal());
    projection.update(event.caseId(), event.assignee());
}

void handle(CaseAssigned event) {
    TenantId tenantId = event.tenantId();
    try (TenantScope ignored = tenantContext.open(tenantId)) {
        projection.update(tenantId, event.caseId(), event.assignee());
    }
}

public final class TenantContextHolder {
    private static final ThreadLocal<TenantContext> CURRENT = new ThreadLocal<>();

    public static TenantContext current() {
        TenantContext context = CURRENT.get();
        if (context == null) {
            throw new IllegalStateException("No tenant context bound");
        }
        return context;
    }

    public static TenantScope open(TenantContext context) {
        TenantContext previous = CURRENT.get();
        CURRENT.set(context);
        return () -> {
            if (previous == null) {
                CURRENT.remove();
            } else {
                CURRENT.set(previous);
            }
        };
    }
}

@FunctionalInterface
public interface TenantScope extends AutoCloseable {
    @Override
    void close();
}

try (TenantScope ignored = TenantContextHolder.open(context)) {
    chain.doFilter(request, response);
}

@Scheduled(cron = "0 0 * * * *")
void closeExpiredCases() {
    caseRepository.findExpiredCases().forEach(caseService::close);
}

@Scheduled(cron = "0 0 * * * *")
void closeExpiredCases() {
    tenantRepository.findActiveTenants().forEach(tenant -> {
        JobActor actor = JobActor.system("case-expiry-job");
        TenantContext context = new TenantContext(tenant.id(), TenantResolutionSource.CLIENT_REGISTRATION, false, correlationId());

        try (TenantScope ignored = tenantContextHolder.open(context)) {
            caseRepository.findExpiredCases(tenant.id())
                    .forEach(caze -> caseService.closeExpired(actor, tenant.id(), caze.id()));
        }
    });
}

- no tenant-scoped job runs without tenant context;
- job actor is explicit;
- job permissions are limited;
- job emits audit events;
- job failure is attributable to tenant;
- job retry preserves tenant;
- tenant disabled/offboarded state is respected.

@PostMapping("/session/active-tenant")
public ResponseEntity<SwitchTenantResponse> switchTenant(@AuthenticationPrincipal CurrentUser user,
                                                         @RequestBody SwitchTenantRequest request) {
    TenantId target = new TenantId(request.tenantId());

    TenantMembership membership = membershipService.findActiveMembership(user.subject(), target)
            .orElseThrow(() -> new AccessDeniedException("Not a member of tenant"));

    SessionToken newSession = sessionService.rotateActiveTenant(user.sessionId(), target);

    audit.log(AuditEvent.tenantSwitched(user.subject(), target, membership.roles()));

    return ResponseEntity.ok(new SwitchTenantResponse(target.value(), newSession.expiresAt()));
}

ROLE_SUPER_ADMIN

public enum AccessMode {
    NORMAL_USER,
    PLATFORM_ADMIN,
    SUPPORT_ACTING_AS_TENANT,
    USER_IMPERSONATION,
    BREAK_GLASS
}

public enum TenantStatus {
    PROVISIONING,
    ACTIVE,
    SUSPENDED,
    READ_ONLY,
    OFFBOARDING,
    DISABLED,
    DELETED
}

public record SecurityDecisionAudit(
        String eventId,
        Instant occurredAt,
        TenantId tenantId,
        String subject,
        String clientId,
        String issuer,
        String action,
        String resourceType,
        String resourceId,
        String decision,
        String policyId,
        String reasonCode,
        AccessMode accessMode,
        String correlationId
) {
}

actor home tenant / staff org
and target tenant

{
  "actorSubject": "staff-123",
  "actorOrg": "platform-security",
  "targetTenant": "tenant-a",
  "accessMode": "SUPPORT_ACTING_AS_TENANT",
  "action": "case.read",
  "resource": "case-999",
  "reasonCode": "customer-ticket-456",
  "decision": "PERMIT"
}

security_authentication_failures_total{reason="unknown_tenant"}
security_token_validation_failures_total{reason="issuer_mismatch"}
security_authorization_denied_total{reason="tenant_membership_missing"}
security_tenant_conflict_total{source="path_token"}
api_requests_total{tenant_tier="enterprise", outcome="success"}

GET /cases
X-Tenant-Id: victim-tenant
Authorization: Bearer valid-token-for-attacker

1. Every tenant-scoped request has exactly one active tenant.
2. Tenant assertions from multiple sources must match or fail.
3. Public request headers cannot define tenant unless cryptographically/internal-gateway verified.
4. Token issuer must be trusted for the active tenant.
5. Token audience must include the target API.
6. Client must be allowed for the tenant and operation.
7. Subject must have active membership or delegated authority for tenant.
8. Resource tenant must equal active tenant for tenant-scoped operations.
9. Data queries must constrain tenant before returning result sets.
10. Cache keys must include tenant for tenant-scoped data.
11. Events must include tenant and consumers must preserve it.
12. Jobs must run under explicit tenant context.
13. Audit logs must include tenant, actor, client, action, resource, decision, and access mode.
14. Tenant status changes must affect authorization even if tokens remain cryptographically valid.
15. Cross-tenant admin access must use explicit mode, justification, and enhanced audit.

tenant-a: case-001
tenant-b: case-001

@Test
void userCannotReadCaseFromAnotherTenant() throws Exception {
    TenantId tenantA = new TenantId("tenant-a");
    TenantId tenantB = new TenantId("tenant-b");
    UUID caseId = fixtures.caseInTenant(tenantB);

    Jwt jwt = jwtFor("user-a", tenantA, "case-api", List.of("case:read"));

    mvc.perform(get("/tenants/{tenantId}/cases/{caseId}", tenantA.value(), caseId)
                    .with(jwt().jwt(jwt)))
            .andExpect(status().isNotFound());
}

@Test
void conflictingTenantAssertionsFailClosed() throws Exception {
    Jwt jwt = jwtFor("user-a", new TenantId("tenant-a"), "case-api", List.of("case:read"));

    mvc.perform(get("/tenants/tenant-b/cases")
                    .with(jwt().jwt(jwt)))
            .andExpect(status().isUnauthorized());
}

@Test
void cacheKeyIncludesTenant() {
    UUID caseId = UUID.fromString("00000000-0000-0000-0000-000000000001");

    fixtures.caseWithId(new TenantId("tenant-a"), caseId, "A secret");
    fixtures.caseWithId(new TenantId("tenant-b"), caseId, "B secret");

    CaseSummary a = service.summary(new TenantId("tenant-a"), caseId);
    CaseSummary b = service.summary(new TenantId("tenant-b"), caseId);

    assertThat(a.title()).isEqualTo("A secret");
    assertThat(b.title()).isEqualTo("B secret");
}

@Test
void eventReplayPreservesTenantContext() {
    CaseAssigned event = new CaseAssigned(
            new TenantId("tenant-a"),
            caseId,
            "assignee-1",
            Instant.now()
    );

    eventHandler.handle(event);

    assertThat(projection.find(new TenantId("tenant-a"), caseId)).isPresent();
    assertThat(projection.find(new TenantId("tenant-b"), caseId)).isEmpty();
}

A regulatory case management SaaS serves multiple agencies.
Some agencies use platform login.
Some agencies require their own enterprise IdP.
Users can belong to multiple agencies.
Support staff may help an agency only after a ticket is approved.
Cases, tasks, attachments, audit records, and exports are tenant-scoped.
A nightly job closes stale draft cases.
A search service indexes case summaries.