[
https://issues.apache.org/jira/browse/KAFKA-13757?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17510492#comment-17510492
]
RivenSun commented on KAFKA-13757:
----------------------------------
Hi [~omkreddy] [~guozhang] and [~showuon]
Could you give some advice?
Thanks.
> 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.
> // 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.
>
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
