[
https://issues.apache.org/jira/browse/KAFKA-13757?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
RivenSun updated KAFKA-13757:
-----------------------------
Description:
DelegationToken is a great and lightweight feature, but when users actually use
it, they get confused.
>From the existing official documents/comments on methods/comments on method
>parameters, the user cannot know what is the specific processing logic of the
>server and what is the meaning of the returned fields after he calls the
>XXXDelegationToken(...) method.
After reading the source code, I briefly sorted out the processing logic of the
XXXDelegationToken(...) method on the server side.
1. createDelegationToken：
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the renewers principal type is not KafkaPrincipal.USER_TYPE, throw
InvalidPrincipalTypeException
// 4. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// maxLifeTime = `maxLifeTimeMs` <= 0 ? brokerConfig.delegationTokenMaxLifeMs
: Math.min(`maxLifeTimeMs`, brokerConfig.delegationTokenMaxLifeMs)
// maxLifeTimestamp = currentTimeMillis + maxLifeTime
// expiryTimestamp = Math.min(maxLifeTimestamp, currentTimeMillis +
brokerConfig.delegationTokenExpiryTimeMs)
// update tokenInfo and return createTokenResult {code}
2. renewDelegationToken
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the authenticated user is not owner/renewer of the token, throw
DelegationTokenOwnerMismatchException
// 4. if the delegation token is expired, throw DelegationTokenExpiredException
// 5. if the delegation token is not found on server, throw
DelegationTokenNotFoundException
// 6. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// renewLifeTime = `renewTimePeriodMs` < 0 ?
brokerConfig.delegationTokenExpiryTimeMs : `renewTimePeriodMs`
// renewTimestamp = currentTimeMillis + renewLifeTime
// expiryTimestamp = Math.min(tokenInfo.maxTimestamp, renewTimestamp)
// update tokenInfo.expiryTimestamp
// return expiryTimestamp {code}
3. expireDelegationToken
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the authenticated user is not owner/renewer of the token, throw
DelegationTokenOwnerMismatchException
// 4. if the delegation token is expired, throw DelegationTokenExpiredException
// 5. if the delegation token is not found on server, throw
DelegationTokenNotFoundException
// 6. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// if `expiryTimePeriodMs` < 0, delete tokenInfo immediately, return
currentTimeMillis.
// otherwise update tokenInfo expiryTimestamp:
// expiryTimestamp = Math.min(tokenInfo.maxTimestamp,
currentTimeMillis + `expiryTimePeriodMs`)
// update tokenInfo.expiryTimestamp
// return expiryTimestamp
//
// Note: Tokens can be cancelled explicitly. If a token is not renewed by
the token’s expiration time or if token is
// beyond the max life time, it will also be deleted from all broker caches
as well as from zookeeper. {code}
4. describeDelegationToken
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// if `owners` is EmptyList(note: exclude `null`), return List() immediately.
// if `owners` size > 0, First discard all tokens whose token.ownerOrRenewer
does not contain any element in `owners`
// then return all tokens that satisfies any of the following conditions:
// 1) the authenticated user is token.ownerOrRenewer
// 2) the authenticated user has `DESCRIBE` permission on `Token`
Resource
// for non-owned tokens{code}
I think we can add some comments on the XXXDelegationToken method: how the
server handles the parameters passed by the user, which can better help the
user to use these methods reasonably.
was:
DelegationToken is a great and lightweight feature, but when users actually use
it, they get confused.
>From the existing official documents/comments on methods/comments on method
>parameters, the user cannot know what is the specific processing logic of the
>server and what is the meaning of the returned fields after he calls the
>XXXDelegationToken(...) method.
After reading the source code, I briefly sorted out the processing logic of the
XXXDelegationToken(...) method on the server side.
1. createDelegationToken：
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the renewers principal type is not KafkaPrincipal.USER_TYPE, throw
InvalidPrincipalTypeException
// 4. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// maxLifeTime = `maxLifeTimeMs` <= 0 ? brokerConfig.delegationTokenMaxLifeMs
: Math.min(`maxLifeTimeMs`, brokerConfig.delegationTokenMaxLifeMs)
// maxLifeTimestamp = currentTimeMillis + maxLifeTime
// expiryTimestamp = Math.min(maxLifeTimestamp, currentTimeMillis +
brokerConfig.delegationTokenExpiryTimeMs)
// update tokenInfo and return createTokenResult {code}
2. renewDelegationToken
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the authenticated user is not owner/renewer of the token, throw
DelegationTokenOwnerMismatchException
// 4. if the delegation token is expired, throw DelegationTokenExpiredException
// 5. if the delegation token is not found on server, throw
DelegationTokenNotFoundException
// 6. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// renewLifeTime = `renewTimePeriodMs` < 0 ?
brokerConfig.delegationTokenExpiryTimeMs : `renewTimePeriodMs`
// renewTimestamp = currentTimeMillis + renewLifeTime
// expiryTimestamp = Math.min(tokenInfo.maxTimestamp, renewTimestamp)
// update tokenInfo.expiryTimestamp
// return expiryTimestamp {code}
3. expireDelegationToken
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the authenticated user is not owner/renewer of the token, throw
DelegationTokenOwnerMismatchException
// 4. if the delegation token is expired, throw DelegationTokenExpiredException
// 5. if the delegation token is not found on server, throw
DelegationTokenNotFoundException
// 6. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// if `expiryTimePeriodMs` < 0, delete tokenInfo immediately, return
currentTimeMillis.
// otherwise update tokenInfo expiryTimestamp:
// expiryTimestamp = Math.min(tokenInfo.maxTimestamp,
currentTimeMillis + `expiryTimePeriodMs`)
// update tokenInfo.expiryTimestamp
// return expiryTimestamp
//
// Note: Tokens can be cancelled explicitly. If a token is not renewed by
the token’s expiration time or if token is
// beyond the max life time, it will also be deleted from all broker caches
as well as from zookeeper. {code}
4. describeDelegationToken
{code:java}
// 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
authenticated channels,
// throw UnsupportedByAuthenticationException
// 2. if the delegation token feature is disabled, throw
DelegationTokenDisabledException
// 3. if the request was not completed in within the given timeoutMs(), throw
TimeoutException
//processing logic:
// if `owners` is EmptyList(note: exclude `null`), return List() immediately.
// otherwise return all tokens that satisfies any of the following
conditions:
// 1) if `owners` size > 0, at least one element in `owners` is
token.ownerOrRenewer
// 2) the authenticated user is token.ownerOrRenewer
// 3) the authenticated user has `DESCRIBE` permission on `Token`
Resource
// for non-owned tokens {code}
I think we can add some comments on the XXXDelegationToken method: how the
server handles the parameters passed by the user, which can better help the
user to use these methods reasonably.
> Improve the annotations of all related methods of DelegationToken in the
> Admin class
> ------------------------------------------------------------------------------------
>
> Key: KAFKA-13757
> URL: https://issues.apache.org/jira/browse/KAFKA-13757
> Project: Kafka
> Issue Type: Improvement
> Components: admin
> Reporter: RivenSun
> Priority: Major
>
> DelegationToken is a great and lightweight feature, but when users actually
> use it, they get confused.
> From the existing official documents/comments on methods/comments on method
> parameters, the user cannot know what is the specific processing logic of the
> server and what is the meaning of the returned fields after he calls the
> XXXDelegationToken(...) method.
> After reading the source code, I briefly sorted out the processing logic of
> the XXXDelegationToken(...) method on the server side.
> 1. createDelegationToken：
> {code:java}
> // 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
> authenticated channels,
> // throw UnsupportedByAuthenticationException
> // 2. if the delegation token feature is disabled, throw
> DelegationTokenDisabledException
> // 3. if the renewers principal type is not KafkaPrincipal.USER_TYPE, throw
> InvalidPrincipalTypeException
> // 4. if the request was not completed in within the given timeoutMs(), throw
> TimeoutException
> //processing logic:
> // maxLifeTime = `maxLifeTimeMs` <= 0 ?
> brokerConfig.delegationTokenMaxLifeMs : Math.min(`maxLifeTimeMs`,
> brokerConfig.delegationTokenMaxLifeMs)
> // maxLifeTimestamp = currentTimeMillis + maxLifeTime
> // expiryTimestamp = Math.min(maxLifeTimestamp, currentTimeMillis +
> brokerConfig.delegationTokenExpiryTimeMs)
> // update tokenInfo and return createTokenResult {code}
> 2. renewDelegationToken
> {code:java}
> // 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
> authenticated channels,
> // throw UnsupportedByAuthenticationException
> // 2. if the delegation token feature is disabled, throw
> DelegationTokenDisabledException
> // 3. if the authenticated user is not owner/renewer of the token, throw
> DelegationTokenOwnerMismatchException
> // 4. if the delegation token is expired, throw
> DelegationTokenExpiredException
> // 5. if the delegation token is not found on server, throw
> DelegationTokenNotFoundException
> // 6. if the request was not completed in within the given timeoutMs(), throw
> TimeoutException
> //processing logic:
> // renewLifeTime = `renewTimePeriodMs` < 0 ?
> brokerConfig.delegationTokenExpiryTimeMs : `renewTimePeriodMs`
> // renewTimestamp = currentTimeMillis + renewLifeTime
> // expiryTimestamp = Math.min(tokenInfo.maxTimestamp, renewTimestamp)
> // update tokenInfo.expiryTimestamp
> // return expiryTimestamp {code}
> 3. expireDelegationToken
> {code:java}
> // 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
> authenticated channels,
> // throw UnsupportedByAuthenticationException
> // 2. if the delegation token feature is disabled, throw
> DelegationTokenDisabledException
> // 3. if the authenticated user is not owner/renewer of the token, throw
> DelegationTokenOwnerMismatchException
> // 4. if the delegation token is expired, throw
> DelegationTokenExpiredException
> // 5. if the delegation token is not found on server, throw
> DelegationTokenNotFoundException
> // 6. if the request was not completed in within the given timeoutMs(), throw
> TimeoutException
> //processing logic:
> // if `expiryTimePeriodMs` < 0, delete tokenInfo immediately, return
> currentTimeMillis.
> // otherwise update tokenInfo expiryTimestamp:
> // expiryTimestamp = Math.min(tokenInfo.maxTimestamp,
> currentTimeMillis + `expiryTimePeriodMs`)
> // update tokenInfo.expiryTimestamp
> // return expiryTimestamp
> //
> // Note: Tokens can be cancelled explicitly. If a token is not renewed by
> the token’s expiration time or if token is
> // beyond the max life time, it will also be deleted from all broker
> caches as well as from zookeeper. {code}
> 4. describeDelegationToken
> {code:java}
> // 1. if the request sent on PLAINTEXT/1-way SSL channels or delegation token
> authenticated channels,
> // throw UnsupportedByAuthenticationException
> // 2. if the delegation token feature is disabled, throw
> DelegationTokenDisabledException
> // 3. if the request was not completed in within the given timeoutMs(), throw
> TimeoutException
> //processing logic:
> // if `owners` is EmptyList(note: exclude `null`), return List()
> immediately.
> // if `owners` size > 0, First discard all tokens whose
> token.ownerOrRenewer does not contain any element in `owners`
> // then return all tokens that satisfies any of the following conditions:
> // 1) the authenticated user is token.ownerOrRenewer
> // 2) the authenticated user has `DESCRIBE` permission on
> `Token` Resource
> // for non-owned tokens{code}
> I think we can add some comments on the XXXDelegationToken method: how the
> server handles the parameters passed by the user, which can better help the
> user to use these methods reasonably.
>
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
