phantom_token_realm
The `phantom_token_realm` directive defines the realm for the WWW-Authenticate header when using phantom tokens in NGINX.
Description
The phantom_token_realm directive is part of the Phantom Token NGINX Module, which functions to enhance API security by managing access tokens in web requests. By configuring the phantom_token_realm, administrators can specify the authentication realm that will be included in the WWW-Authenticate header, adhering to the OAuth 2.0 Bearer Token specification laid out in RFC 6750.
In practice, when this directive is set, it configures a specified realm that serves to inform clients about the scope of authentication required. Should a request fail due to lack of valid authorization, the NGINX server will subsequently respond with a 401 Unauthorized status, embedding the defined realm in the response’s WWW-Authenticate header. This informs the client of the authentication realm that is needed to proceed, paving the way for token acquisition prior to re-attempting the request.
This directive should be employed in combination with other configurations within the module to ensure proper handling and introspection of the access tokens. Its behavior is straightforward in that it primarily serves as a descriptive label for the security context, but it must be correctly aligned with the expected values of client applications for optimal functionality.
Config Example
location /api {
phantom_token_realm "mySecureRealm";
phantom_token_enable on;
phantom_token_introspection_endpoint "https://introspection.example.com/";
}Ensure the realm name does not contain special characters that may invalidate the syntax.
The phantom_token_realm directive must be properly set in a location context; otherwise, it may not apply as intended.
Be aware that multiple realms cannot be specified; ensure to set the realm that accurately reflects your security context.