Package com.atlassian.bamboo.accesstoken

Class AccessTokenGenerator

  • public class AccessTokenGenerator
extends Object
    Class ported from Bitbucket Server

    This is a helper class to take care of all the generating and verifying of access tokens. Since tokens are salted, encoded and stored in the database (with the salt as part of the encoded token) we need to be able to retrieve the encoded token from the database uniquely in order to validate it against the given token. Because of the possibility of bare tokens (tokens used in the header to authenticate without providing a username) we cannot use the username as this ID. As a solution, we generate an ID and embed it as part of the token given to the user.

    The token will be in the form base64.encode(id + ':' + secret), where the id a 12-digit random long and the secret is 20 bytes of random data. The caller of this class should not have to worry about the form of the token. The caller can extract the token ID of a token generated by generateToken() using getId(String) and can encode the token for storage using hashToken(String).

    Expected flow for generating new tokens:

    • Call generateToken() to generate a token
    • Pass the token into getId(String) to get the ID of the token
    • Pass the token into hashToken(String) to get the hashed token
    • Store the hashed token in the database, alongside the token ID, and return the token to the user

    Expected flow for authenticating tokens

    • The user provides a token with which they would like to authenticate
    • Pass the token into getId(String) and use the ID to retrieve the hashed token from the database
    • Pass the token and hashed token into authenticateToken(String, String) to determine whether the provide token is valid
    Since:
    6.10

    • Constructor Detail

      • AccessTokenGenerator

        public AccessTokenGenerator()

    • Method Detail

      • authenticateToken

        public boolean authenticateToken​(@NotNull
                                 @NotNull String token,
                                 @NotNull
                                 @NotNull String hashedToken)
        Given a token (such as that provided by the user) and its hashed token, return whether the given token matches the hashed token.
        Parameters:
        token - the token (as provided by the user
        hashedToken - the hashed token that was saved for the given token's ID
        Returns:
        true if the token is valid for the given hashed token. false otherwise.

      • generateToken

        @NotNull
public @NotNull String generateToken()
        Generate an access token which encapsulates its ID and only uses base64 characters. Note: This method returns an unencoded token, so it should never be saved anywhere (only returned to the user).

        In order to save the generated token, pass its value into hashToken(String) and store the resulting hashed token. To extract the token's ID from the token, call getId(String).

        Returns:
        token to use return to the user

      • getId

        @NotNull
public @NotNull String getId​(@NotNull
                             @NotNull String token)
                      throws IllegalArgumentException
        Since tokens generated with generateToken() encapsulate the token ID, it can be extracted from a token using this method.

        The ID of a token will always be 12 chars long and contain only integer characters.

        Parameters:
        token - The token (such as that provided by the user when authenticating or by generateToken())
        Returns:
        the ID of the given token
        Throws:
        IllegalArgumentException - if the provided token is not in the expected form (as validated by isValidToken(String)

      • hashToken

        @NotNull
public @NotNull String hashToken​(@NotNull
                                 @NotNull String token)
        Given a token, encode it so that it can be safely stored in a database. Encoding performs a one-way hashing operation provided by PasswordEncoder so that the unencoded token cannot be derived (in any practical time) by an attacker who obtains the Bamboo database. Note that this is not a repeatable action; calling this method with the same input more than once will not return the same hashed token. As such it is intended to be called once on initial token creation and then stored in the database alongside the token's ID
        Parameters:
        token - The token, as generated by generateToken()
        Returns:
        the hashed token, suitable to store in a database.
        Throws:
        IllegalArgumentException - if the provided token is not in the expected form (as validated by isValidToken(String)

      • isValidToken

        public boolean isValidToken​(@NotNull
                            @NotNull String token)
        Validates whether the given token is in the form of a valid access token. Other methods from this class may throw exceptions if it is not in the right form
        Parameters:
        token - the raw value of the token to validate
        Returns:
        true if the given token will not produce exceptions when calling other methods, false otherwise