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

Class ServiceProviderToken

java.lang.Object
com.atlassian.bitbucket.jenkins.internal.applink.oauth.Token
com.atlassian.bitbucket.jenkins.internal.applink.oauth.serviceprovider.token.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:

  • Field Details

    • 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 Details

    • 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)

    • getSession

      public ServiceProviderToken.Session getSession()
      Returns the Session associated with the token.

    • hasSession

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