Interface ISecurityService


  • public interface ISecurityService
    The entry point for authentication and authorization tasks. The ISecurityService manages both the users, roles and their relationship as well as permissions and their relationship to users and roles.
    Author:
    dobisekm
    • Method Detail

      • getCurrentSubject

        javax.security.auth.Subject getCurrentSubject()
        Returns:
        The Subject under which we operate right now.
      • getSystemUserSubject

        javax.security.auth.Subject getSystemUserSubject()
        Returns:
        The subject representing the system user.
      • getSubjectUser

        java.lang.String getSubjectUser​(javax.security.auth.Subject subj)
        Parameters:
        subj -
        Returns:
        the ID of the user represented by the given subject or null if subj==null or it does not represent a user.
      • getCurrentUserCredentials

        IUserCredentials getCurrentUserCredentials​(java.lang.String credentialsKey)
        Shortcut for

        getSubjectUserCredentials(getCurrentSubject(), credentialsKey).

        Parameters:
        credentialsKey -
        Returns:
        the credentials or null if no user is logged on.
        See Also:
        getSubjectCredentials(Subject, String)
      • getSubjectCredentials

        IUserCredentials getSubjectCredentials​(javax.security.auth.Subject subj,
                                               java.lang.String credentialsKey)
        Returns the credentials of the logged on user. This method is used for interactions with other systems, like SVN.
        Parameters:
        credentialsKey - This is a string identification of the target system. This is a preparation for setups, where a single user will have different sets of credentials for different resources (e.g. for different SVN repositories). If the key is not recognized or is null, then the default credentials are returned.
        Returns:
        the credentials or null if no user is logged on.
      • authenticate

        @Deprecated
        void authenticate​(@NotNull
                          java.lang.String userName,
                          @Nullable
                          java.lang.String password,
                          @NotNull
                          java.lang.String source)
                   throws AuthenticationFailedException
        Deprecated.
        Verifies the provided user's credentials, but does not log them on.

        Requires only one configured authentication provider. If more than one is configured, use the method with authenticatorId parameter
        Parameters:
        userName -
        password -
        source - the authentication source, (e.g. "portal/IP" or "system"), used for writing to logs.
        Throws:
        AuthenticationFailedException - if the provided credentials are invalid.
        java.lang.IllegalArgumentException - if userName or source are null
        java.lang.IllegalStateException - if Polarion is configured to use more than one authentication provider.
        Since:
        3.17.0
      • login

        @Deprecated
        javax.security.auth.Subject login​(java.lang.String userName,
                                          java.lang.String password,
                                          java.lang.String source)
                                   throws AuthenticationFailedException
        Checks the given credentials and creates the Subject representing the logged on user. This subject can then be used as a parameter for other methods.

        Requires only one configured authentication provider. If more than one is configured, use the method with authenticatorId parameter
        Parameters:
        userName -
        password -
        source - the login source (e.g. "portal/IP" or "system"), only used for writing to logs.
        Returns:
        authenticated subject (not null)
        Throws:
        AuthenticationFailedException
        java.lang.IllegalArgumentException - if userName or source are null
        java.lang.IllegalStateException - if Polarion is configured to use more than one authentication provider.
      • loginWithToken

        @Deprecated
        @NotNull
        javax.security.auth.Subject loginWithToken​(@NotNull
                                                   java.lang.String token,
                                                   @NotNull
                                                   java.lang.String source)
                                            throws AuthenticationFailedException
        Checks the given token using the underlying security mechanism and creates the Subject representing the logged on user. This subject can then be used as a parameter to other methods.

        To have Teamcenter Security Services (TCSS) login with a token, you need to first use the following method to create a Base64 encoded token TcssToken.create(String, String).

        Alternatively, to use Kerberos/SPNEGO to login, you need to encode a token into Base64 and then pass it directly.

        Requires only one configured authentication provider. If more than one is configured, use the method with authenticatorId parameter
        Parameters:
        token - The Token used for validation. Cannot be null. The token must be encoded using the Base64 encoding scheme.
        source - The login source (e.g. "portal/IP" or "system"), used only for writing to logs.
        Returns:
        The authenticated subject (not null).
        Throws:
        AuthenticationFailedException - If the given token is invalid.
        java.lang.IllegalArgumentException - If the mechanism, token or the source are null.
        java.lang.IllegalStateException - if Polarion is configured to use more than one authentication provider.
        Since:
        3.17.0
      • loginUserFromVault

        @Deprecated
        javax.security.auth.Subject loginUserFromVault​(java.lang.String userVaultKey,
                                                       java.lang.String source)
                                                throws AuthenticationFailedException
        Deprecated.
        Checks the given credentials and creates the Subject representing the logged on user. The subject can be then used as a parameter to other methods.
        Parameters:
        userVaultKey -
        source - The login source (e.g. "portal/IP" or "system"), used only for writing to logs.
        Returns:
        authenticated subject (not null)
        Throws:
        AuthenticationFailedException
        java.lang.IllegalArgumentException - if userName or source are null
        Since:
        3.5.2
      • login

        @NotNull
        ILogin login()
        Create a login flow builder
        Returns:
        new login flow builder
        Since:
        3.21.1
      • logout

        void logout​(javax.security.auth.Subject subj)
        Removes the credentials from the subject and logs it out.
        Parameters:
        subj -
      • doAsSystemUser

        <T> T doAsSystemUser​(java.security.PrivilegedExceptionAction<T> action)
                      throws java.lang.Exception
        Performs the given operation on behalf of the system user.
        Parameters:
        action - The action to run.
        Throws:
        java.lang.Exception
      • doAsSystemUser

        <T> T doAsSystemUser​(java.security.PrivilegedAction<T> action)
        Parameters:
        action - The action to run.
        Returns:
        the value returned by the action
        See Also:
        doAsSystemUser(PrivilegedExceptionAction)
      • doAsUser

        <T> T doAsUser​(javax.security.auth.Subject user,
                       java.security.PrivilegedExceptionAction<T> action)
                throws java.lang.Exception
        Makes the given operation on behalf of the given user. The user must be logged on.
        Parameters:
        user -
        action - The action to run.
        Returns:
        the value returned by the action
        Throws:
        java.lang.Exception
      • doAsUser

        <T> T doAsUser​(javax.security.auth.Subject user,
                       java.security.PrivilegedAction<T> action)
        Parameters:
        user -
        action - The value returned by the action.
        Returns:
        The value returned by the action.
        See Also:
        doAsUser(Subject, PrivilegedExceptionAction)
      • canManageUsers

        boolean canManageUsers()
      • createUser

        void createUser​(java.lang.String userName,
                        java.lang.String password)
                 throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • changePassword

        void changePassword​(java.lang.String userName,
                            java.lang.String password)
      • removeUser

        void removeUser​(@NotNull
                        java.lang.String userName)
      • constructPermission

        IPermission constructPermission​(java.lang.String permissionName)
        Construct IPermission class based on the permission name.
        Parameters:
        permissionName -
        Returns:
        IPermission (not null)
        Throws:
        java.lang.IllegalArgumentException - if no such permission exists.
      • hasPermission

        boolean hasPermission​(IPermission permission,
                              IContextId contextId)
        Has the current user been given permission in the given context?
        Parameters:
        permission - permission (not null)
        contextId - context id (can be null)
        Returns:
        true if permission is granted.
      • hasPermission

        boolean hasPermission​(javax.security.auth.Subject user,
                              IPermission permission,
                              IContextId contextId)
        Has the given user been given permission in the given context?
        Parameters:
        user - The user's Subject
        permission - permission
        contextId - context id (can be null)
        Returns:
        true if permission is granted.
      • hasPermission

        boolean hasPermission​(java.lang.String user,
                              IPermission permission,
                              IContextId contextId)
        Has the given user been given permission in the given context?
        Parameters:
        user - id
        permission - permission
        contextId - context id (can be null)
        Returns:
        true if permission is granted.
      • hasPermission

        boolean hasPermission​(java.util.Collection<java.lang.String> roles,
                              IPermission permission,
                              IContextId contextId)
        Since:
        3.5.0
      • checkPermission

        void checkPermission​(javax.security.auth.Subject user,
                             IPermission permission,
                             IContextId contextId)
                      throws PermissionDeniedException
        Check that given user has given permission in given context.
        Parameters:
        user - user's Subject
        permission - permission
        contextId - The context id (can be null)
        Throws:
        PermissionDeniedException - if permission is denied.
      • checkPermission

        void checkPermission​(java.lang.String user,
                             IPermission permission,
                             IContextId contextId)
                      throws PermissionDeniedException
        Check that the given user has been given permission in the given context.
        Parameters:
        user - id
        permission - permission
        contextId - context id (can be null)
        Throws:
        PermissionDeniedException - if permission is denied.
      • getGlobalRoles

        @NotNull
        java.util.Collection<java.lang.String> getGlobalRoles()
        Returns:
        The immutable Collection of role Ids, that exist in the system.
      • createGlobalRole

        void createGlobalRole​(@NotNull
                              java.lang.String roleId)
        Creates a global role. Does nothing if the role already exists.
        Parameters:
        roleId -
      • removeGlobalRole

        void removeGlobalRole​(@NotNull
                              java.lang.String roleId)
        Removes the global role. Does nothing, if no such role exists.

        Roles 'admin' and 'user' can't be removed. The method is returned without doing any action in such cases.

        Parameters:
        roleId -
        Throws:
        java.lang.IllegalArgumentException - if roleId is null.
      • getContextRoles

        @NotNull
        java.util.Collection<java.lang.String> getContextRoles​(@NotNull
                                                               IContextId ctx)
        Parameters:
        ctx -
        Returns:
        The immutable Collection of role IDs, that exist in the given context.
      • createContextRole

        void createContextRole​(@NotNull
                               java.lang.String roleId,
                               @NotNull
                               IContextId ctx)
        Creates a context role. Does nothing if the role already exists.

        The context role will exist in the given context and the whole context tree below.

        Parameters:
        roleId -
      • removeContextRole

        void removeContextRole​(@NotNull
                               java.lang.String roleId,
                               @NotNull
                               IContextId ctx)
        Removes a global role. Does nothing, if no such role exists.

        Note: The existence of a context role might be inherited from the parent context. If so then the deletion in the current context might have no impact.

        Parameters:
        roleId -
        Throws:
        java.lang.IllegalArgumentException - if roleId is null.
      • getUsersForGlobalRole

        @NotNull
        java.util.Collection<java.lang.String> getUsersForGlobalRole​(@NotNull
                                                                     java.lang.String roleId)
        Returns the IDs of all users, that do have the given role.
        Parameters:
        roleId -
        Returns:
        A collection of Strings. Returns an empty collection for an unknown role. Never returns null.
      • getUsersForContextRole

        @NotNull
        java.util.Collection<java.lang.String> getUsersForContextRole​(@NotNull
                                                                      java.lang.String roleId,
                                                                      @NotNull
                                                                      IContextId ctx)
        Returns the IDs of all users, that have the given role for the given context. (Project or Global level roles.)
        Parameters:
        roleId -
        ctx -
        Returns:
        A collection of Strings. Returns an empty collection for an unknown role. Never returns null.
      • getUsersWithContextRole

        @NotNull
        java.util.Collection<java.lang.String> getUsersWithContextRole​(@NotNull
                                                                       IContextId ctx)
        Returns the IDs of all users, that have some role in the given context.
        Parameters:
        ctx -
        Returns:
        A collection of String user IDs. Never returns null.
      • addGlobalRoleToUser

        void addGlobalRoleToUser​(@NotNull
                                 java.lang.String userName,
                                 @NotNull
                                 java.lang.String roleId)
      • removeGlobalRoleFromUser

        void removeGlobalRoleFromUser​(@NotNull
                                      java.lang.String userName,
                                      @NotNull
                                      java.lang.String roleId)
      • addContextRoleToUser

        void addContextRoleToUser​(@NotNull
                                  java.lang.String userName,
                                  @NotNull
                                  java.lang.String roleId,
                                  @NotNull
                                  IContextId ctx)
      • removeContextRoleFromUser

        void removeContextRoleFromUser​(@NotNull
                                       java.lang.String userName,
                                       @NotNull
                                       java.lang.String roleId,
                                       @NotNull
                                       IContextId ctx)
      • getRolesForUser

        @NotNull
        java.util.Collection<java.lang.String> getRolesForUser​(@NotNull
                                                               java.lang.String userName)
        Returns all global roles assigned to the given user.
        Parameters:
        userName -
        Returns:
        mutable Collection of String roles
      • getRolesForUser

        @NotNull
        java.util.Collection<java.lang.String> getRolesForUser​(@NotNull
                                                               java.lang.String userName,
                                                               @Nullable
                                                               IContextId context)
        Returns all global + context roles assigned to the user.
        Parameters:
        userName -
        context - The contextId, might be null, only global roles are returned in such cases.
        Returns:
        mutable Collection of String roles
      • getContextRolesForUser

        @NotNull
        java.util.Collection<java.lang.String> getContextRolesForUser​(@NotNull
                                                                      java.lang.String userName,
                                                                      @NotNull
                                                                      IContextId context)
        Returns the context roles assigned to the user.
        Parameters:
        userName -
        context - The contextId, might not be null.
        Returns:
        mutable Collection of String roles.
      • getRolesForUser

        @NotNull
        java.util.Map<IContextId,​java.util.Collection<java.lang.String>> getRolesForUser​(@NotNull
                                                                                               java.lang.String userName,
                                                                                               @NotNull
                                                                                               IContextId... contextIds)
        Returns all global + context roles assigned to the user for specified contexts.
        Parameters:
        userName -
        contextIds - The contextIds, might not be null
        Returns:
        mutable Map of IContextId and Collection of roles.
        Since:
        3.7.2
      • getContextRolesForUser

        @NotNull
        java.util.Map<IContextId,​java.util.Collection<java.lang.String>> getContextRolesForUser​(@NotNull
                                                                                                      java.lang.String userName,
                                                                                                      @NotNull
                                                                                                      IContextId... contextIds)
        Returns context roles assigned to the user for specified contexts.
        Parameters:
        userName -
        contextIds - The contextIds, might not be null.
        Returns:
        mutable Map of IContextId and Collection of roles.
        Since:
        3.7.2
      • findPermissionFactory

        IPermissionFactory findPermissionFactory​(java.lang.String permissionName)
        Since:
        3.5.0
      • getParentPermissions

        @NotNull
        java.util.List<IPermission> getParentPermissions​(@NotNull
                                                         IPermission permission)
        Since:
        3.5.0
      • setDefaultHatForGlobalRole

        void setDefaultHatForGlobalRole​(java.lang.String role,
                                        java.lang.String hatId)
      • getDefaultHatForGlobalRole

        java.lang.String getDefaultHatForGlobalRole​(java.lang.String role)
      • setDefaultHatForContextRole

        void setDefaultHatForContextRole​(IContextId ctx,
                                         java.lang.String role,
                                         java.lang.String hatId)
      • getDefaultHatForContextRole

        java.lang.String getDefaultHatForContextRole​(IContextId ctx,
                                                     java.lang.String role)
      • synchronizeBackendSecurity

        ISecurityService.IBackendSecuritySynchronizationResult synchronizeBackendSecurity​(java.util.Collection<java.lang.String> users,
                                                                                          java.util.Collection<IContextId> contexts)
        Synchronizes the back-end's, that is the repository's security, with the current state.

        Actual behaviour is implementation-dependent.

        Parameters:
        users - The names of users to be synchronized (not null)
        contexts - ids of contexts to be synchronized (not null)
        Returns:
        result of synchronization (not null)
        Since:
        3.1.1
      • hasAddonLicense

        boolean hasAddonLicense​(@NotNull
                                java.lang.String addonId)
        Checks whether the current user has a license for a specific add-on.
        Parameters:
        addonId -
        Returns:
        true if the user has the add-on license.
        Since:
        3.9.0