Package jetbrains.buildServer.serverSide.oauth

Class OAuthTokensStorage

  • All Implemented Interfaces:
    TokenRefresher
    public class OAuthTokensStorage
extends Object
implements TokenRefresher
    Maintains a set of access tokens generated for an OAuth provider. Each token has information about user who provided it and a scope for which the token has been generated. All tokens are stored in the Root project custom data storage.

    • Method Detail

      • isTokenRefreshSupported

        public boolean isTokenRefreshSupported​(@NotNull
                                       SProject project,
                                       @NotNull
                                       String connectionId)
        Parameters:
        project -
        connectionId -
        Returns:
        true if the connection supports the refreshable tokens

      • rememberPermanentToken

        @NotNull
public OAuthToken rememberPermanentToken​(@NotNull
                                         String tokenStorageId,
                                         @NotNull
                                         SUser user,
                                         @NotNull
                                         String oauthLogin,
                                         @NotNull
                                         String personalToken,
                                         @NotNull
                                         String scope)
        Store a new permanent token
        Parameters:
        tokenStorageId - token storage id, can be based on the client id of an OAuth connection, or on a connection id in other cases
        user - TeamCity user who to whom the token is issued
        oauthLogin - a third party system username that was used to issue the token by that system
        personalToken - actual access token
        scope - token scope (depends on the third party system API)
        Returns:
        a token object

      • rememberToken

        @NotNull
public OAuthToken rememberToken​(@NotNull
                                String tokenStorageId,
                                @NotNull
                                SUser user,
                                @NotNull
                                String oauthLogin,
                                @NotNull
                                String personalToken,
                                @NotNull
                                String scope,
                                int timeToLiveSeconds)
        Store a new token
        Parameters:
        tokenStorageId - token storage id, can be based on the client id of an OAuth connection, or on a connection id in other cases
        user - TeamCity user who to whom the token is issued
        oauthLogin - a third party system username that was used to issue the token by that system
        personalToken - actual access token
        scope - token scope (depends on the third party system API)
        timeToLiveSeconds - a TTL of the token, <=0 for a permanent token
        Returns:
        a token object

      • rememberToken

        @NotNull
public OAuthToken rememberToken​(@NotNull
                                SProject project,
                                @NotNull
                                String tokenStorageId,
                                @NotNull
                                SUser user,
                                @NotNull
                                String oauthLogin,
                                @NotNull
                                String personalToken,
                                @NotNull
                                String scope,
                                int timeToLiveSeconds)
        Store a new token and limit its project scope
        Parameters:
        project - a project where the token can be referred to by id
        tokenStorageId - token storage id, can be based on the client id of an OAuth connection, or on a connection id in other cases
        user - TeamCity user who to whom the token is issued
        oauthLogin - a third party system username that was used to issue the token by that system
        personalToken - actual access token
        scope - token scope (depends on the third party system API)
        timeToLiveSeconds - a TTL of the token, <=0 for a permanent token
        Returns:
        a token object

      • rememberToken

        @NotNull
public OAuthToken rememberToken​(@NotNull
                                String tokenStorageId,
                                @NotNull
                                OAuthToken token)
        remember an existing token object
        Parameters:
        tokenStorageId - token storage id, can be based on the client id of an OAuth connection, or on a connection id in other cases
        token - token
        Returns:
        the same token object

      • getUserTokens

        @Deprecated
@NotNull
public Set<OAuthToken> getUserTokens​(@NotNull
                                     String connectionId,
                                     @NotNull
                                     SUser user)
        Deprecated.
        since 2022.04, use getUserTokens(String, SUser, SProject, boolean) instead
        Get all tokens issued for a given user and under specific connection id
        Parameters:
        connectionId - connection id, it is used as token storage id by this method
        user - TeamCity user who to whom the token is issued
        Returns:
        a set of tokens

      • getUserTokens

        @NotNull
public Set<OAuthToken> getUserTokens​(@NotNull
                                     String connectionId,
                                     @NotNull
                                     SUser user,
                                     @NotNull
                                     SProject project,
                                     boolean refreshIfNecessary)
        Get all tokens for a given user and under a specific connection id within a project context
        Parameters:
        connectionId - connection id, it will not be used directly as token storage id, but the token storage id will be returned by the connection itself
        user - TeamCity user who to whom the token is issued
        project - a project to determine the context of the connection
        refreshIfNecessary - if true the method will attempt to refresh each expired token
        Returns:
        a set of tokens

      • getUserTokens

        @NotNull
public Set<OAuthToken> getUserTokens​(@NotNull
                                     String connectionId,
                                     @NotNull
                                     SUser user,
                                     @NotNull
                                     SProject project,
                                     @NotNull
                                     TokenIntent intent,
                                     boolean refreshIfNecessary)
        Get all tokens that satisfy certain usage intent for a given user and under a specific connection id within a project context
        Parameters:
        connectionId - connection id, it will not be used directly as token storage id, but the token storage id will be returned by the connection itself
        user - TeamCity user who to whom the token is issued
        project - a project to determine the context of the connection
        tokenIntent - used to select a token by scope
        refreshIfNecessary - if true the method will attempt to refresh each expired token
        Returns:
        a set of tokens

      • getUserTokens

        @NotNull
public Set<OAuthToken> getUserTokens​(@NotNull
                                     String connectionId,
                                     long userId,
                                     @NotNull
                                     SProject project,
                                     @NotNull
                                     TokenIntent intent,
                                     boolean refreshIfNecessary)
        Get all tokens that satisfy certain usage intent for a given user and under a specific connection id within a project context
        Parameters:
        connectionId - connection id, it will not be used directly as token storage id, but the token storage id will be returned by the connection itself
        userId - TeamCity user ID who to whom the token is issued
        project - a project to determine the context of the connection
        tokenIntent - used to select a token by scope
        refreshIfNecessary - if true the method will attempt to refresh each expired token
        Returns:
        a set of tokens

      • getAnyNonExpiredUserToken

        @Nullable
public OAuthToken getAnyNonExpiredUserToken​(@NotNull
                                            TokenStorageUserQuery query)
        Gets any user token that matches the query and is not expired. Encountered matching tokens will potentially be refreshed. It is not guaranteed that all matching tokens will be encountered. The first matching and non-expired token will be returned immediately.
        Parameters:
        query - query conditions
        Returns:
        any mathing and non-expired token, or null if nothing matches

      • isTokenPermittedInProject

        public boolean isTokenPermittedInProject​(@NotNull
                                         SProject project,
                                         @NotNull
                                         String tokenFullId)

      • getToken

        @Nullable
public OAuthToken getToken​(@Nullable
                           SProject project,
                           @NotNull
                           String tokenFullId,
                           boolean checkProjectScope,
                           boolean refreshIfExpired)
        Description copied from interface: TokenRefresher
        Retrieve a token object from storage by its full id. If the token is expired, the method may attempt to refresh it, store and return a new token.
        Specified by:
        getToken in interface TokenRefresher
        Parameters:
        project - a project used as a context to locate a relevant connection and check project scope
        tokenFullId - a token full id in the form of oauth2:CONNECTION_ID:USER_ID:UUID_OF_TOKEN
        checkProjectScope - if true the method checks the project scope before returning the tocken
        refreshIfExpired - if the token is expired, attempt to refresh it
        Returns:
        access token object, null if such a token is not found in the storage or failed to get refreshed

      • getToken

        @Nullable
public OAuthToken getToken​(@NotNull
                           String vcsRootExtId,
                           @NotNull
                           String tokenFullId,
                           boolean checkProjectScope,
                           boolean refreshIfExpired)
        Description copied from interface: TokenRefresher
        Retrieve a token object from storage by its full id. If the token is expired, the method may attempt to refresh it, store and return a new token.
        Specified by:
        getToken in interface TokenRefresher
        Parameters:
        vcsRootExtId - an external id of the relevant VCS root
        tokenFullId - a token full id in the form of oauth2:CONNECTION_ID:USER_ID:UUID_OF_TOKEN
        checkProjectScope - if true the method checks the project scope before returning the tocken
        refreshIfExpired - if the token is expired, attempt to refresh it
        Returns:
        access token object, null if such a token is not found in the storage or failed to get refreshed

      • buildProjectContextKey

        public static String buildProjectContextKey​(@NotNull
                                            SProject project)

      • removeToken

        @Deprecated
public boolean removeToken​(@NotNull
                           String tokenStorageId,
                           @NotNull
                           OAuthToken token)
        Deprecated.
        This method can lead to unintended removal of tokens, potentially breaking any existing configuration if it references the removed token's IDs. See the ticket TW-87758 for more information. Use removeSingleToken(String, OAuthToken) instead. Deprecated since 2024.07
        This method removes all tokens which have the same TeamCity user id and the same access token value.
        Parameters:
        tokenStorageId - an id of the token storage where to search for tokens
        token - token instance from where user id and access token will be taken
        Returns:
        true if at least one token was removed

      • removeSingleToken

        public void removeSingleToken​(@NotNull
                              String tokenStorageId,
                              @NotNull
                              OAuthToken token)
        This method removes exactly the supplied token record by its ID value.
        Parameters:
        tokenStorageId - an ID of the token storage where to search for the token
        token - token instance from where the token ID will be taken

      • isRefreshableTokensEnabled

        public static boolean isRefreshableTokensEnabled​(SProject project)

      • allowTokenInProject

        @Deprecated
public void allowTokenInProject​(@NotNull
                                SProject project,
                                @NotNull
                                String fullTokenId)
        Deprecated.
        use allowTokenInProjectIfNecessary(SProject, String) instead
        Adds the project to the token's project scope. The token is only modified if necessary.
        Parameters:
        project - the project
        fullTokenId - full token ID of the token to modify

      • allowTokenInProjectIfNecessary

        public boolean allowTokenInProjectIfNecessary​(@NotNull
                                              SProject project,
                                              @NotNull
                                              String fullTokenId)
        Adds the project to the token's project scope. The token is only modified if necessary.
        Parameters:
        project - the project
        fullTokenId - full token ID of the token to modify
        Returns:
        true if the token was modified
        Since:
        2024.12

      • allowTokenInProject

        public void allowTokenInProject​(@NotNull
                                SProject project,
                                @NotNull
                                String tokenStorageId,
                                @NotNull
                                OAuthToken oauthToken)

      • allowTokenInProjects

        public void allowTokenInProjects​(@NotNull
                                 Collection<SProject> projects,
                                 @NotNull
                                 String tokenFullId)