THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
https://issues.apache.org/jira/browse/KNOX-2067
https://issues.apache.org/jira/browse/KNOX-2071
Goal
The KnoxToken service (gateway-service-knoxtoken) currently hands out tokens (which include expiration information), which the various token-related providers validate when an
attempt is made to use those tokens to authorize the invocation of some other service.
There should be a way to renew (extend the ttl of) an existing token (e.g., to support long-running jobs) or to revoke a token (e.g., when a job is finished).
Renewal Endpoint
The /knoxtoken/api/v1/token/renew endpoint will accept POST requests with the tokens as the data.
If the token is a known token, then the service will update the expiration via the TokenStateService, extending it for some additional duration from the time of the renewal request.
There is a fixed renewal interval, which is the amount of time that is added upon each renewal request, up to a maximum lifetime, after which subsequent renewals will be denied (this
is modeled after other Hadoop renewable delegation token types).
The default for the renewal interval will be 24-hours (based on precedent), and the default maximum lifetime for a token will be 7 days (based on precedent), but both of these values
are configurable.
| Request Description | HTTP Response | JSON Response |
|---|---|---|
Valid token from authorized renewer | 200 | { "renewed": "true", "expiration": "UPDATED EXPIRATION TIME" } |
Unknown / Invalid token | 400 | { "renewed": "false", "error": "Unknown token." } |
User not authorized to renew | 400 | { "renewed": "false", "error": "Caller (AUTHENTICATED USER) not authorized to renew tokens." } |
Token has been revoked | 400 | { "renewed": "false", "error": "The specified token has been revoked." } |
Revocation Endpoint
The /knoxtoken/api/v1/token/revoke endpoint will accept POST requests with the tokens as the data.
If the token is a known token, then the service will update the expiration via the TokenStateService to -1, indicating that it has been revoked.
| Request Description | HTTP Response | JSON Response |
|---|---|---|
Valid token from authorized renewer | 200 | { |
| Token has already been revoked from authorized renewer | 200 | { "revoked": "true" } |
Unknown / Invalid token from authorized renewer | 400 | { |
User not authorized to revoke | 400 | { "revoked": "false", "error": "Caller (AUTHENTICATED USER) not authorized to revoke tokens." } |
Configuration
Each deployment (i.e., topology) of the KnoxToken service can be configured to employ the TokenStateService via a service parameter named knox.token.exp.server-managed,
with a value of true or false (default). If this property is unset or set to false, neither renewal nor revocation will be permitted for that deployment.
Since not every authenticated user should be permitted to renew or revoke tokens, the knox.token.renewer.whitelist configuration property will be used to specify a
comma-delimited list of principals who are permitted to do so.
Upon renewal, the token lifetime will be extended by the default amount or the value of the knox.token.exp.renew-interval configuration property (service parameter).
However, a token only be renewed if the new expiration will not extend the token's lifetime past the knox.token.exp.max-lifetime configuration value.
YARN limits the number of times a token may be renewed, or more accurately, the maximum lifetime of a token.
The KnoxToken service will do similarly, having a built-in default value for this limit, and probably should allow for the configuration thereof.
Service Parameter | Default Value | Description |
|---|---|---|
knox.token.exp.server-managed | false | True, if the TokenStateService should be employed by a particular deployment of the KnoxToken service. |
knox.token.exp.renew-interval | 24 hours | The amount of time for which the ttl of a token should be extended when renewal is requested. |
| knox.token.exp.max-lifetime | 7 days | The maximum allowable lifetime duration for tokens. |
knox.token.renewer.whitelist | N/A | A list of those principals who are permitted to renew/revoke tokens. |
KnoxToken Authentication Enhancements
The authentication/authorization providers responsible for validating Knox tokens (when they’re used to assert identity when invoking services) must be changed to optionally (via
provider configuration parameter) reference the TokenStateService for determining expiration or revocation conditions.
Configuration
To employ the TokenStateService, the provider configuration must include a param named knox.token.exp.server-managed, with a value of true, matching the corresponding service
param value for the issuing KnoxToken service.
TokenStateService
A new gateway service, called the TokenStateService, will serve as a central cache of token expiration information that is external to the token itself.
AliasService-based implementation
It is reasonable to employ the AliasService for storing this token state, especially when the ZooKeeper-based RemoteAliasService is configured.
Using the AliasService addresses the need for persistent state (e.g., when Knox must be restarted), which could be shared across multiple Knox instances (e.g., HA deployment).