Package com.atlassian.bitbucket.jenkins.internal.applink.oauth.serviceprovider.token

Class ServiceProviderToken

  • @Immutable
public final class ServiceProviderToken
extends Token
    Representation of an OAuth token for use by service providers. A token can be either a request token or an access token. Tokens always have a token value, a token secret and the Consumer the token belongs to. A request token that has been authorized will also contain the user that authorized the request. An access token will always contain user that gave permission to the Consumer to make requests on their behalf.

    Tokens instances are immutable. To create a new ServiceProviderToken instance, use builder. To build an unauthorized request token, use the newRequestToken(String) as follows 

       ServiceProviderToken unauthorizedRequestToken = ServiceProviderToken.newRequestToken("bb6dd1391ce33b5bd3ecad1175139a39")
          .tokenSecret("29c3005cc5fbe5d431f27b29d6191ea3")
          .consumer(consumer)
          .build();

    An authorized request token can be built by calling authorize(String, String) method on an unauthorized request token 

       ServiceProviderToken authorizedRequestToken = unauthorizedRequestToken.authorize(fred);
    or from scratch in a similar way to unauthorized request tokens, but also setting the authorizedBy attribute by calling ServiceProviderToken.ServiceProviderTokenBuilder.authorizedBy(String) before calling build() 
       ServiceProviderToken authorizedRequestToken = ServiceProviderToken.newRequestToken("bb6dd1391ce33b5bd3ecad1175139a39")
          .tokenSecret("29c3005cc5fbe5d431f27b29d6191ea3")
          .consumer(consumer)
          .authorizedBy(fred)
          .build();

    To build an access token, use the newAccessToken(String) method as the starting point 

       ServiceProviderToken accessToken = ServiceProviderToken.newAccessToken("bb6dd1391ce33b5bd3ecad1175139a39")
          .tokenSecret("29c3005cc5fbe5d431f27b29d6191ea3")
          .consumer(consumer)
          .authorizedBy(fred)
          .build();

    ServiceProviderTokens also have two additional attributes that control when they expire: the creationTime and timeToLive. If these values are not specified when building a token, the defaults are used. The default value for creationTime is when the ServiceProviderToken.ServiceProviderTokenBuilder.build() method is called and the token constructed. The default value for timeToLive depends on the type of token being constructed. For request tokens, the default value is 10 minutes. For access tokens, the default value is 1 week. When a token has been around for longer than its timeToLive, any attempts to use it should result in an OAuth problem of token_expired, as described in the

    See Also:
    OAuth problem reporting spec

    • Field Detail

      • DEFAULT_REQUEST_TOKEN_TTL

        public static final long DEFAULT_REQUEST_TOKEN_TTL
        The default value for request token time to live. Value corresponds to 10 minutes in ms.

      • DEFAULT_ACCESS_TOKEN_TTL

        public static final long DEFAULT_ACCESS_TOKEN_TTL
        The default value for access token time to live. Value corresponds to 5 years in ms.

      • DEFAULT_SESSION_TTL

        public static final long DEFAULT_SESSION_TTL
        The default value for session time to live. Value corresponds to 5 years + 30 days in ms. This value is supposed to be longer than DEFAULT_ACCESS_TOKEN_TTL so that the session is still live while the access token has just expired.

    • Method Detail

      • newRequestToken

        public static ServiceProviderToken.ServiceProviderTokenBuilder newRequestToken​(String token)
        Static factory method that starts the process of building a request ServiceProviderToken instance. Returns a ServiceProviderTokenBuilder so the additional attributes of the token can be set.
        Parameters:
        token - unique token used to the ServiceProviderToken to be used in OAuth operations
        Returns:
        builder to set additional attributes and build the ServiceProviderToken

      • newAccessToken

        public static ServiceProviderToken.ServiceProviderTokenBuilder newAccessToken​(String token)
        Static factory method that starts the process of building an access ServiceProviderToken instance. Returns a ServiceProviderTokenBuilder so the additional attributes of the token can be set.
        Parameters:
        token - unique token used to the ServiceProviderToken to be used in OAuth operations
        Returns:
        builder to set additional attributes and build the ServiceProviderToken

      • authorize

        public ServiceProviderToken authorize​(String user,
                                      String verifier)
        If this is an unauthorized request token, this method will return a request token that has been authorized by the user.
        Parameters:
        user - name of the user that has authorized the request token
        verifier - value used to prove the user authorizing the token is the same as the one swapping it for an access token
        Returns:
        authorized request token
        Throws:
        IllegalStateException - thrown if the token is not a request token or has already been authorized or denied

      • hasBeenAuthorized

        public boolean hasBeenAuthorized()
        Returns true if this token has been authorized, false otherwise. This is a short-cut for calling getAuthorization() and checking the return type. As such, it has the same condition that it will always return true if the token is an access token.
        Returns:
        true if this token has been authorized, false otherwise

      • deny

        public ServiceProviderToken deny​(String user)
        If this is an unauthorized request token, this method will return a request token that has been denied by the user.
        Parameters:
        user - name of the user that has denied the request token
        Returns:
        denied request token
        Throws:
        IllegalStateException - thrown if the token is not a request token or has already been authorized or denied

      • hasBeenDenied

        public boolean hasBeenDenied()
        Returns true if this token has been denied, false otherwise. This is a short-cut for calling getAuthorization() and checking the return type. As such, it has the same condition that it will always return false if the token is an access token.
        Returns:
        true if this token has been denied, false otherwise

      • getAuthorization

        public ServiceProviderToken.Authorization getAuthorization()
        Returns the authorization status of this token. If the token is a request token, it will return Authorization.NONE if it the user has not yet approved or denied the request, Authorization.APPROVED if the user approved the access request, or Authorization.DENIED if the user denied the access request. For access tokens, Authorized.APPROVED will always be returned.
        Returns:
        authorization status of this token

      • getUser

        @Nullable
public String getUser()
        If this is an authorized request token, returns the user that authorized the token. If this is an access token, it's the user the Consumer is making requests on behalf of. Returns null otherwise.
        Returns:
        name of the user that authorized the Consumer to make requests on behalf of themselves

      • getVerifier

        @Nullable
public String getVerifier()
        If this is an authorized request token, returns the verification code that is used to verify the user that authorized the token is the same one that is swapping it for an access token. Returns null otherwise.
        Returns:
        verification code that is used to verify the user that authorized the token is the same one that is swapping it for an access token

      • getCreationTime

        public long getCreationTime()
        Returns the time the token was originally created for the user, in milliseconds.
        Returns:
        time the token was originally created for the user, in milliseconds

      • getTimeToLive

        public long getTimeToLive()
        Returns the maximum amount of time the token is considered valid, in milliseconds.
        Returns:
        maximum amount of time the token is considered valid, in milliseconds

      • hasExpired

        public boolean hasExpired​(Clock clock)
        Returns true if the time to live has been exceeded, false otherwise.
        Parameters:
        clock - a way to determine the current time
        Returns:
        true if the time to live has been exceeded, false otherwise

      • getCallback

        public URI getCallback()
        Returns the URI the consumer should be redirected to after the user has completed authorization. It will be null if the URI was communicated out-of-band via another form of communication between the service provider and consumer. It will also be null if the token is a version 1.0 request token.
        Returns:
        URI the consumer should be redirected to after the user has completed authorization

      • isValidCallback

        public static boolean isValidCallback​(URI callback)

      • hasSession

        public boolean hasSession()
        Returns true if there is a Session associated with the token.