com.atlassian.bamboo.accesstoken

Class AccessTokenGenerator

java.lang.Object

com.atlassian.bamboo.accesstoken.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 Summary

Constructors

Constructor and Description
AccessTokenGenerator()

Method Summary

Modifier and Type	Method and Description
boolean	authenticateToken(String token, 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.
String	generateToken() Generate an access token which encapsulates its ID and only uses base64 characters.
String	getId(String token) Since tokens generated with generateToken() encapsulate the token ID, it can be extracted from a token using this method.
String	hashToken(String token) Given a token, encode it so that it can be safely stored in a database.
boolean	isValidToken(String token) Validates whether the given token is in the form of a valid access token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AccessTokenGenerator

public AccessTokenGenerator()

Method Detail

authenticateToken

public boolean authenticateToken(@NotNull
                                 String token,
                                 @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 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 String getId(@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 String hashToken(@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 Bitbucket 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
                            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