# Package com.sas.lsaf.security.role

Service and class definitions for manipulating and creating roles, their availability in contexts, and their membership lists.

A role in SAS Life Science Analytics Framework 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 privilege is an identified right that grants users the ability to certain functions in the system. 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. Roles are generally defined by administrators and context leads and assigned to members of various contexts. Roles grant scoped privileges to perform privileged actions at that context and role contexts below.

In order to define a new role at a context, available scoped privileges can be obtained using the `ScopedPrivilegeService`. A new role can then be created using one or more privileges at the context. Roles are uniquely named within a context.

A role created at a context using `RoleService.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 `RoleService.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 which 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.

When a role is deleted, the role is deleted as well as all inherited roles that have been inherited at lower contexts.

To create a role and manage the members assigned to it:

1. Create the `Role` using `RoleService.createRole(String, String, String, Set, Set)`.
2. Modify the role's privilege list using `Role.setMembers(Set)`.
3. Modify the role's membership list using `Role.setMembers(Set)`.
4. Update the role changes using `RoleService.updateRole(Role)`.

To create an inherited role and manage the members assigned to it:

1. Get the role you would like to inherit by retrieving it, for example using `RoleService.getRoleByName(String, String)`.
2. Create the inherited `Role` using `RoleService.addInheritedRole(String, String, Set)`. by specifying the role and immediate child context.
3. Modify the role's membership list using `Role.setMembers(Set)`.
4. Update the role changes using `RoleService.updateRole(Role)`.

- Interface Summary
  Interface | Description
  --- | ---
  RoleService | Service for defining and managing the lifecycle of roles.

- Class Summary
  Class | Description
  --- | ---
  Role | A role is a logical grouping of privileges.
  RoleDescriptor | A lightweight representation of a role.

- Exception Summary
  Exception | Description
  --- | ---
  InvalidRoleMemberException | Thrown when a role is created or updated with new members that violate any membership contracts.
  RoleContextNotFoundException | Thrown when the specified role context could not be found.
  RoleException | Root of the hierarchy of all checked role exceptions within the SAS Life Science Analytics Framework Java API.
  RoleExistsException | Thrown when an attempt is made to define a role that is already defined; or add an inherited role that is already inherited.
  RoleNotFoundException | Thrown when the specified role was not found on the server.
  RoleUpdateException | Thrown when a role could not be updated.