auth_jwt_validate_sub
The `auth_jwt_validate_sub` directive validates the `sub` claim in a JWT during authorization checks.
Description
The auth_jwt_validate_sub directive is utilized in NGINX configurations to enforce validation of the sub (subject) claim within a JSON Web Token (JWT). The sub claim typically identifies the principal that is the subject of the JWT, such as a user ID. This directive can be set to on to ensure that the value of the sub claim matches expected values, adding a layer of security against unauthorized access. When enabled, the directive will ensure that the claims within the JWT are in line with the authorization strategies defined by the server, enhancing the integrity of access controls.
When configuring this directive, its presence has implications for both the successful and failed validation scenarios. If the check is performed and the claim does not validate successfully, NGINX can be instructed to apply specific response actions, such as redirecting to a login page if integrated with other authentication mechanisms defined by directives like auth_jwt_redirect. The handling of validation is encapsulated in the NGINX module that processes the JWT, making it essential to understand the surrounding JWT settings to ensure seamless functionality.
The context in which this directive can be applied includes http, server, and location, providing flexibility in its use throughout the server configuration. Setting auth_jwt_validate_sub to off or not defining it at all implies no validation of the sub claim will be performed, which could lead to unauthorized access risks if not managed properly.
Config Example
location /protected {
auth_jwt_enabled on;
auth_jwt_validate_sub on;
auth_jwt_key my_jwt_secret;
auth_jwt_loginurl /login;
}Ensure that JWTs being validated actually contain a sub claim; absent claims may lead to failed authentication.
Setting the directive to on without appropriate claim checks might result in unwanted access being inadvertently granted if not properly configured.