Tenant Authentication Failure Handler (S2R-AUTH-0401)

Overview

The UnboundTenantExceptionAdvice is a component within the Admin API that acts as a global exception handler. Its purpose is to provide a consistent, secure error response when an API request that requires a tenant context is received without one.

This handler specifically intercepts the UnboundTenantException. This situation occurs when a request reaches a part of the system that requires tenant-scoping, but no tenant has been associated with the request. The handler ensures that such a request is gracefully rejected with a standard 401 Unauthorized HTTP status and a JSON error payload, preventing the propagation of internal exceptions to the API consumer.

How it works

The UnboundTenantExceptionAdvice component uses Spring's @RestControllerAdvice annotation, which allows it to intercept exceptions thrown from any controller within the Admin API.

The operational flow is as follows:

1. An API request is processed by an endpoint that requires a tenant context. The system attempts to resolve the tenant for the request.
2. If no tenant can be associated with the request, an UnboundTenantException is thrown.
3. The @ExceptionHandler(UnboundTenantException.class) annotation directs the framework to invoke the handleUnboundTenant method in this component.
4. The handleUnboundTenant method performs two actions:
   • It writes a warning to the server-side logs. This log entry includes the code S2R-AUTH-0401, a static reason UNBOUND_TENANT, and the URI of the rejected request. The detailed exception message from the original UnboundTenantException is included in the server log but is not sent to the client.
   • It constructs and returns a 401 Unauthorized HTTP response with a Content-Type of application/json. The response body contains a fixed error message, detailed in the sections below.

This mechanism ensures that failures in tenant resolution are handled as a form of authentication failure, providing a clear and secure response to the API consumer.

API Response Format

When an UnboundTenantException is handled, the API responds with an HTTP 401 Unauthorized status code.

Response Body

The body of the response is a JSON object containing a structured error message.

Field	Type	Description
error	Object	A container for the error details.
error.code	String	A fixed error code identifying the nature of the failure. For this handler, the value is always S2R-AUTH-0401.
error.message	String	A fixed, human-readable message. For this handler, the value is always Tenant authentication failed.

Example Response

The following is an example of the exact JSON payload returned to the API consumer.

{
  "error": {
    "code": "S2R-AUTH-0401",
    "message": "Tenant authentication failed"
  }
}

Troubleshooting

Error: 401 Unauthorized with code S2R-AUTH-0401

If an API consumer receives an HTTP 401 Unauthorized response with the error code S2R-AUTH-0401 and the message Tenant authentication failed, it indicates that the request could not be associated with a specific tenant.

• Cause: This error is triggered when a request is made to a tenant-scoped endpoint without providing valid credentials or context that the platform can use to identify the target tenant.
• Resolution for API Consumers: The API consumer must review their authentication method and ensure that their requests are correctly formed to establish a tenant context.
• Information for Platform Operators: When this error occurs, a corresponding warning is written to the server logs. Operators can search for log entries containing the string S2R-TENANCY-AUTH reject reason=UNBOUND_TENANT to find the specific request URI and timestamp associated with the failure. The log entry will look similar to this: S2R-AUTH-0401 S2R-TENANCY-AUTH reject reason=UNBOUND_TENANT path=/path/to/endpoint.

---

All SOAP-to-REST docs