Package com.sas.lsaf.security.role

Interface RoleService

public interface RoleService
Service for defining and managing the lifecycle of roles.

A role is a logical grouping of privileges and members. A role is comprised of a set of privileges that are required to perform actions by a user or group assigned to that role. A role is associated with and scoped to a context where it is defined. All repository context types that are configured with the membership capability are available for role management features.

A role created at a context using createRole(String, String, String, Set, Set) is considered a defined role and therefore the metadata, privileges and members can all be modified with this instance. An existing role can also be inherited by additional role contexts that are immediate descendants of the context. By creating the role using addInheritedRole(String, String, Set) the role is considered inherited at the context and therefore the metadata and privileges cannot be modified since the role is defined at a higher level and is only referenced at this lower level. The members assigned to the role at this context are the only items that can be modified. This inheritance model promotes the reuse of higher-level role definitions so security constraints can be managed in more global manner. A change in a higher-level role definition is automatically reflected in any lower inherited roles. The memberships for these roles are never shared; memberships within roles are always managed at the context the role was created. To determine if an existing role is defined or inherited please refer to RoleDescriptor.isInherited().

Members (users and groups) of the context may be assigned to the roles associated with the context. This will grant them all the privileges included in the role. Once a privilege is granted within the repository hierarchy, the member has that privilege at that point where it was granted as well as all descendant contexts.

Since:
2.1

  • Method Details

    • createRole

      Role createRole(String contextId, String name, String description, Set<String> scopedPrivilegeIds, Set<Principal> members) throws RoleExistsException, PrivilegeNotFoundException, InvalidRoleMemberException
      Creates a defined role at the specified context. For a given context, defined role names must be unique but this does not include inherited roles. Roles created in this manner allow name, description, privileges and members to be updated at any time.
      Parameters:
      contextId - the context where the role definition will be created.
      name - the name of the role.
      description - the description of the role.
      scopedPrivilegeIds - the scoped privileges to be included in the role.
      members - the principals to assign to this role.
      Returns:
      The newly created defined role.
      Throws:
      RoleExistsException - thrown when a role already exists with this name at the specified context.
      PrivilegeNotFoundException - thrown when a privilege provided is not defined or is not a scoped privilege.
      InvalidRoleMemberException - thrown if a principal being added is not a member of the context.

    • addInheritedRole

      Role addInheritedRole(String contextId, String inheritedRoleId, Set<Principal> members) throws RoleExistsException, RoleNotFoundException, InvalidRoleMemberException
      Adds an inherited role at the specified context. An inherited role is a role added to a child context from the parent context. A role can only be inherited once for a specific context. Roles created in this manner inherit the name, description and privileges assigned to this role but not the members. Inherited roles allow members to be updated at any time.
      Parameters:
      contextId - the context to assign the inherited role.
      inheritedRoleId - the role identifier of the parent context role definition.
      members - the principals to assign to this inherited role.
      Returns:
      the newly created inherited role.
      Throws:
      RoleExistsException - thrown if this role is already inherited at this context.
      RoleNotFoundException - thrown if the role specified does not exist or does not exist at the parent context.
      InvalidRoleMemberException - thrown if a principal being added is not a member of the context.

    • updateRole

      Role updateRole(Role role) throws RoleNotFoundException, RoleExistsException, RoleUpdateException, PrivilegeNotFoundException, InvalidRoleMemberException
      Updates the name, description, privileges or members of the specified role. The context of a role can never be modified on a role; any changes to the context will be ignored. If an inherited role is being updated only the membership can be changed. If the name, description or privileges of an inherited role are updated with this method a RoleUpdateException will be thrown.
      Parameters:
      role - the role to update.
      Returns:
      The updated role.
      Throws:
      RoleNotFoundException - thrown if the role specified does not exist.
      RoleExistsException - thrown when a new name specified in the update request already exists for the specified context.
      RoleUpdateException - thrown when the name, description or privileges are updated on an inherited role.
      PrivilegeNotFoundException - thrown when a privilege provided is not defined or is not a scoped privilege.
      InvalidRoleMemberException - thrown if a principal being added is not a member of the context.

    • deleteRole

      void deleteRole(String roleId) throws RoleNotFoundException
      Deletes the role as well as all inherited roles created from the role. This method acts on both defined as well as inherited roles and in both cases will remove all inherited instances as well.
      Parameters:
      roleId - the identifier of the role to delete.
      Throws:
      RoleNotFoundException - thrown if the specified role does not exist.

    • roleExists

      boolean roleExists(String contextId, String name)
      Indicates whether a defined role exists at the specified context with the specified name. Only defined roles can be tested with this method since inherited roles can allow duplicate names if there are roles inherited from multiple contexts with the same name.
      Parameters:
      contextId - the context to test.
      name - the name of the role to test.
      Returns:
      true if a role with the specified name is defined at the context, false otherwise.

    • inheritedRoleExists

      boolean inheritedRoleExists(String contextId, String roleId)
      Indicates whether an inherited role exists at the specified context with the specified parent role.
      Parameters:
      contextId - the context to search.
      roleId - the role identifier to search for.
      Returns:
      true if an inherited role exists at the specified context, false otherwise.

    • getRoleByName

      Role getRoleByName(String contextId, String name) throws RoleNotFoundException
      Gets a defined role by specifying its context and name. This method will not return inherited roles since inherited role names can be duplicated.
      Parameters:
      contextId - the context to search.
      name - the name of the role to search for.
      Returns:
      The role if it exists.
      Throws:
      RoleNotFoundException - thrown if the specified role does not exist.

    • getRoleDescriptorByName

      RoleDescriptor getRoleDescriptorByName(String contextId, String name) throws RoleNotFoundException
      Gets a defined role descriptor by specifying its context and name. This method will not return inherited roles since inherited role names can be duplicated.
      Parameters:
      contextId - the context to search.
      name - the name of the role to search for.
      Returns:
      The role descriptor if it exists.
      Throws:
      RoleNotFoundException - thrown if the specified role does not exist.

    • getRoleById

      Role getRoleById(String roleId) throws RoleNotFoundException
      Get a role given its identifier.
      Parameters:
      roleId - the identifier of the desired role.
      Returns:
      The role if it exists.
      Throws:
      RoleNotFoundException - thrown when the specified role does not exist.

    • getRoleDescriptorById

      RoleDescriptor getRoleDescriptorById(String roleId) throws RoleNotFoundException
      Gets a role descriptor given its identifier.
      Parameters:
      roleId - the identifier of the desired role descriptor.
      Returns:
      The role descriptor if it exists.
      Throws:
      RoleNotFoundException - thrown when the specified role does not exist.

    • getRolesByIds

      Set<Role> getRolesByIds(Set<String> roleIds)
      Gets set of roles given their identifiers. Only the roles found will be returned. If none are found then an empty set is returned.
      Parameters:
      roleIds - the identifiers of the roles to search for.
      Returns:
      The set of roles found with the specified identifiers.

    • getRolesByContext

      Set<Role> getRolesByContext(String contextId)
      Gets all of the roles that exist at the specified context. This includes roles that are defined as well as inherited roles.
      Parameters:
      contextId - the context to search..
      Returns:
      The set of roles that exist at the specified context.

    • getRoleDescriptorsByContext

      Set<RoleDescriptor> getRoleDescriptorsByContext(String contextId)
      Gets the lightweight representations of all roles that exist at the specified context.
      Parameters:
      contextId - the context to search.
      Returns:
      The set of role descriptors for all roles defined in that context.

    • removePrincipalFromRoles

      void removePrincipalFromRoles(String contextId, Principal member)
      Removes the specified principal from all roles at the specified context.
      Parameters:
      contextId - the context to search.
      member - the principal to remove from all roles at the specified context.

    • removePrincipalsFromRoles

      void removePrincipalsFromRoles(String contextId, Set<Principal> members)
      Removes the specified principals from all roles at the specified context.
      Parameters:
      contextId - the context to search.
      members - the set of principals to remove from all roles at the specified context.

    • isPrincipalInRole

      boolean isPrincipalInRole(String roleId, Principal principal)
      Indicates whether the principal is a member of the specified role.
      Parameters:
      roleId - the role identifier to search.
      principal - the principal to search for.
      Returns:
      true if the principal is a member of the specified role at the specified context, false otherwise.

    • getRoleDescriptorsByContextAndPrincipal

      Set<RoleDescriptor> getRoleDescriptorsByContextAndPrincipal(String contextId, Principal member)
      Gets all of the roles at the specified context that the specified principal is a member of.
      Parameters:
      contextId - the context to search.
      member - the principal to search for.
      Returns:
      The set of role descriptors at the specified context that the principal is a member of.

    • getRoleDescriptorsByContextAndPrivilege

      Set<RoleDescriptor> getRoleDescriptorsByContextAndPrivilege(String contextId, String scopedPrivilegeId) throws PrivilegeNotFoundException
      Gets all of the roles at a given context that include the specified privilege. If none are found then an empty set is returned.
      Parameters:
      contextId - the context to search.
      scopedPrivilegeId - the scoped privilege in question.
      Returns:
      The set of role descriptors for all roles in that context that includes the specified scoped privilege.
      Throws:
      PrivilegeNotFoundException - thrown when the privilege provided is not defined or is not a scoped privilege.

    • getInheritedRoleDescriptorsByRole

      Set<RoleDescriptor> getInheritedRoleDescriptorsByRole(String roleId) throws RoleNotFoundException
      Gets all inherited roles across contexts that are associated with the specified role.
      Parameters:
      roleId - the role identifier to search for.
      Returns:
      The set of all inherited roles for that role in the system. If no inherited roles exist an empty set will be returned.
      Throws:
      RoleNotFoundException - thrown when the specified role does not exist.

    • hasPrivilege

      boolean hasPrivilege(String contextId, String scopedPrivilegeId, Principal member)
      Indicates whether the specified principal has the scoped privilege at the given context. If a global privilege is provided, a PrivilegeNotFoundException will be thrown as those are not context-based privileges. Will return true if the member has been granted the privilege at a higher context.
      Parameters:
      contextId - the context to search.
      scopedPrivilegeId - the scoped privilege to search for.
      member - the principal to check.
      Returns:
      true if the specified principal has the scoped privilege assigned to them at the specified context or above, false otherwise.