Entities¶

An entity offers a framework for managing a group of users that we grant autonomy for handling its own accounts based on a predefined set of rules. An entity can help to model a subdivision of an organization; or it could be used for allowing a company to expose services to partners (modelled as entities).

With an entity we can:

• Define a set of users that belongs to a same team. Linking this entity to a main security group.
• Define security templates for creating and managing those users: memberships and user types.
• Allow delegated management of user within an entity to "delegated entity admin" users.
• Driven creation of users based on templates.
• Limited management of users: change first, last names and some membership changes.
• Relate the entity to an "OwnerId" in the Eclipse system.
• Entity data support ACLs.

Data model¶

An Entity has been modelled as described below:

Entity¶

Defines an entity.

Entity Membership¶

Defines the available memberships for this entity. This information will be used later for:

• Creating a new user in an entity will automatically assign those memberships.
• Editing users in an entity will allow to manage just those memberships defined in this collection. Mandatory memberships cannot be changed; neither, other memberships assigned to a user that are not defined in this collection.

By design, we cannot assume that users in an entity will have the same memberships that defined here; also, memberships are not synchronized with users.

Entity User Type Assignment¶

Defines the available user types for this entity. This information will be used later for:

• Creating a new user in an entity will automatically assign those user types.

• Editing users in an entity will allow to manage just those user types defined in this collection.

By design, we cannot assume that users in an entity will have the same user types that defined here; also, user types are not synchronized with users.

Entity User¶

Stores the list of user included in an entity. From a persistence point of view, we support that a single user will be assigned to multiple entities (open design). However, this is not supported yet by the system.

The information offered about a user in the context of an entity doesn't contain all information in the user. It's a reduced view of the user by design; containing some editable information like: first and last name, email, active end date; and other information about the state of the user in read only mode.

Use cases¶

Obviously, entities can be managed by a "super security admin" user. However, makes more sense if we manage it and define the use cases based on two roles: an Entity Admin and a Delegated Entity Admin.

Below diagram shows all uses cases that we are covering with Entities:

Entity Admin represents a user with full permissions for managing entities; without any control of ACLs. This role, in term of security, is defined in Sec.EntityAdmin role; key setting here is full permission for Sec.Entity and Sec.EntityAdmin. This roles contains below permissions:

Delegated Entity Admin Represents a user that belongs to an entity and has been granted with permissions for managing users in this entity. This role, in term of security, is defined in Sec.DelegatedEntityAdmin role. Key setting here is don't add Sec.EntityAdmin permissions, allow just read for Sec.Entity and allow full permissions for Sec.EntityUser* securables. This roles contains below permissions:

We recommend to use those roles to configure the users for managing both scenarios; as those roles contains the required permissions already configured.

Entity management use cases¶

Read Entity Information¶

As a user with permission for [Sec.Entity|Read]
   And with permission for [Sec.EntityAdmin]
   When I navigate to Entity page
   Then I can see all entities

As a user with permission for [Sec.Entity|Read]
   And without permission for [Sec.EntityAdmin]
   And with ACLs permissions for some X entities
   When I navigate to Entity page
   Then I can see just X entities

Selecting any entity; we will be able to open the entity screen. In read-only mode; the pencil for editing the entity is managed by [Sec.Entity|Update]

Create Entity¶

As a user with permission for [Sec.Entity|Create]
  And with permission for [Sec.EntityAdmin]
  When I navigate to Entity page
  Then I can create a new entity

There are no restrictions on assigning a group. So, we can use public ones and reuse the same group with different entities. A good design of entities and groups are important. However, keep in mind that permissions for the user are not defined by this value. Permissions for the users are defined in the membership collection.

Concerns and future work: there are some conversations about the benefits of allowing multiple groups assigned to an entity or maybe define default groups by application for driving logic in the downstream of other applications. Nothing of this was included in the first version, considered the MVP.

Update Entity details¶

As a user with permission for [Sec.Entity|Update]
  And with permission for [Sec.EntityAdmin] or ACLs access to entity E
  When I navigate to entity E page
  Then I can edit  entity E

Delete Entities¶

As a user with permission for [Sec.Entity|Delete]
  And with permission for [Sec.EntityAdmin] or ACLs access to entity E
  When I navigate to entity E page
  Then I can edit  entity E

Deletion of entities is not allowed if there are users assigned to this entity.

Define Available Memberships for an entity¶

As a user with permission for [Sec.Entity|Update]
  And  with permission for
          [Sec.EntityMembership|Create] or/and
          [Sec.EntityMembership|Update] or/and
          [Sec.EntityMembership|Delete]
  And with permission for [Sec.EntityAdmin]
  When I navigate to entity drawer
  Then I can add/edit/delete memberships

Memberships included in the entity will drive the creation of users later and also the available (and editable) memberships for users within the context of the entity. Those limitations don't affect to user management screen and API endpoints.

Membership can be flagged as mandatory; this will prevent to Sec.DelegatedEntityAdmin users to remove those memberships; so we can protect the configuration against invalid options.

Define Available User Types for an entity¶

As a user with permission for [Sec.Entity|Update]
  And  with permission for
           [Sec.EntityUserType|Create] or/and
          [Sec.EntityUserType|Update] or/and
          [Sec.EntityUserType|Delete]
  And with permission for [Sec.EntityAdmin]
  When I navigate to entity drawer
  Then I can add/edit/delete user types

User types included in the entity will drive the creation of users later and also the available (and editable) user types for users within the context of the entity. Those limitations don't affect to user management screen and API endpoints. Just one user type per application can be configured

Concerns and future work: Allow to define multiple user types per application at entity level will allow to configure users in the entity with different user types. This is not possible currently.

Users of an entity¶

Users assigned to an entity are displayed in the "user assigned to this entity" tab. There are some basic filtering options.

Create user is protected by Sec.EntityUser-Create permission.

Clicking on a user, we will be able to access to the read only screen of this user. From this screen, we can edit it; in case this is allowed.

Concerns and future work:

• Deletion of users is not supported from the UI. Currently, this will mimic using active/inactive users.
• Unlink user from an entity is not supported. Requires analysis to decide the desired behaviour and implications of this action.

Create new users¶

Common use case¶

As a user with permission for [Sec.Entity|Read]
  And with permission for [Sec.EntityUser|Create]
  And with permission for [Sec.EntityAdmin] or ACLs access to entity E
  When I navigate to entity E
  Then I can create a new user U associated to entity E

Creation of new users inside the entity will create a new user (similar to a user created from user screen) and also will:

• Include the user in the entity (EntityUser model)

• Populate the memberships of the user with all memberships defined in the entity membership list

• Populate the user types assignments of the user with the user types defined in the entity

User creation applies the same validations that regular user creation; plus maximum number of active users per entity.

Concerns and future work:

• There are no option to add existing users to the entity (further analysis about implications is required).

• There are no support for assigning the same user to multiple entities.

Assigned to any entity¶

For an EntityAdmin user, it will be possible to create users for any entity; doing this from the entity screen.

Assigned to my entity¶

For a DelegatedEntityAdmin, it will be possible to create user just for those entities with ACLs permissions.

Update users¶

Common use case¶

As a user with permission for [Sec.Entity|Read]
  And with permission for [Sec.EntityUser|Update]
  And with permission for [Sec.EntityAdmin] or ACLs access to entity E
  When I navigate to entity E
  Then I can update a user U associated to entity E

Assigned to any entity¶

For an EntityAdmin user, it will be possible to update users for any entity; doing this from the entity screen.

Assigned to my entity¶

For a DelegatedEntityAdmin, it will be possible to update user just for those entities with ACLs permissions.

Assign memberships to a user¶

In this section, an EntityAdmin or DelegatedAdmin user, can configure the memberships of a user. The information presented in this screen contains:

• All available memberships defined in the entity

• Plus any other membership assigned to this user; that it's not defined for the entity. This will allow to add special memberships to some users (ie DelegatedEntityAdmin role).

The memberships displayed show two columns:

• Assigned: if this user has this membership or not.

• Editable: Indicates when this membership can be assigned or removed. A membership is editable if the membership is defined in the entity and is not mandatory.

Entering in the edit mode will present below screen:

Just selecting/deselecting the assigned field the membership is assigned/removed from the user.

Assign user types to a user¶

Works in a similar way than membership, with the different there is no concept of mandatory user type.

Request reset password for users¶

As a user with permission for [Sec.Entity|Read]
  And with permission for [Sec.EntityUser|Read]
  And with permission for [Sec.EntityAdmin] or ACLs access to entity E
  When I navigate to entity E
  Then I can request a reset password for a user U associated to entity E

We can do this from the context menu in the section of available users:

Bulk insert¶

Security Service offers the ability of bulk insert user assigned to an entity. This functionality will be exposed in the SecurityAPI, in the DataExchange specs (in swagger); in a new resource: EntityUserBulkAction. There will be two endpoints:

• For bulk import users in a json format
• For bulk import users from a XLSX file

The bulk import will need to deal with potentially large sets of data; so, each item included will be committed independently. It's possible that a request with 10 items will save 6 and it will fail for 4. So, the response will always contain information about which entry failed (due to validations or any other error) and which one worked.

These action are protected by Sec.EntityUser securable and Create action; plus Sec.EntityAdmin and create action. Only EntityAdmin users can bulk insert users; this is not open for delegated admin users or any other roles with lower permissions.

Adding UI for supporting this action is out of the scope because the first final users of this option will be Sequel Support team and they have expressed their desire of automate this process; so UI is not required in this first version.

API definition with OpenAPI - Swagger¶

All actions defined in this EntityUserBulkAction resource are defined in the context of an entity (parameter key). So, all request will create the users in the entity {key} passed as parameter in the path:

Bulk insert using json¶

Request:

• key: Entity key. The entity must exists.
• entityUsers: collection of EntityUser.

Response:

• Collection of BulkActionResult.

Response contains the same number of items than request; order is the same as request. So, first EntityUser has the result in the first element of response and so on.

BulkActionResult: key contains the username, isSucceeded informs if the element was saved or not, and errors contains information when element couldn't be saved (due to validations or due to unexpected errors). When an internal error occurs, the validation error should contain a single element with message: 'Unexpected internal error. Please, review logs for further information' -details are logged and cannot be exposed in the API-

Bulk insert using XLSX file¶

The file expected must be similar to this one:

The request allows to define the mappings (column names where information is stored):

Request:

• key: Entity key. The entity must exists.

• file: xlsx file.

• mapping parameters (*ColumnName): allows to define the name of the column that contains this property. This is not required, and Swagger shows default values that matches with attached document.

• UsernameColumnName: contains the name of the column where username is expected.
• FirstNameColumnName: contains the name of the column where First Name is expected.
• LastNameColumnName: contains the name of the column where Last Name is expected.
• EmailAddressColumnName: contains the name of the column where Email Address is expected.
• AzureIdColumnName: contains the name of the column where Azure Id is expected.
• SsoUsernameColumnName: contains the name of the column where the SsoUsername is expected.

Response:

• Similar to Bulk insert using json

How-To¶

In this section, we will cover some basic configurations that we will expect our clients will do.

Create a new Entity¶

This action must be done by an Entity Admin user.

For creating a new entity, first of all we need to design the configuration. We will need:

• Determine a unique key for the entity.

• Collect basic details: name, eclipse owner id (if required)

• Determine the main group we will assign to the entity.

Once we have the information; we will follow below steps:

1. Go to Groups and create the group if doesn't exist yet.

2. Go to Entities page

3. Click on create new entity.

   1. Populate basic details: key, name
   2. Save

4. Edit the recently created entity for populating the memberships:

   1. Include mandatory memberships required for all users (traditionally related to public groups). Mark them as mandatory; because if those memberships are removed the user won't be able to access to the application.

   2. Add specific memberships for the user, related to the main group.

   3. Add other memberships related to groups different to the main group.

      This is the most important part of the configuration and must be designed by each product to fulfil the requirements.

5. Edit user types if required.

Create a Delegated Entity Admin User for an existing Entity¶

This action must be done by a user with permissions for editing users.

For creating a Delegated Entity Admin; we need to create a user assigned to this entity and later add it to the Sec.DelegatedEntityAdmin role for Sec.Public group.

Steps are:

1. Go to an Entity page

2. Go to users assigned to this entity

3. Click on add new user

4. Populate all information

5. Save

6. User will be created and configured with all memberships defined

7. Go to user page

8. Edit recently created user.

9. Add membership: Sec.DelegatedEntityAdmin and Sec.Public.

Concerns and future work:

• Allow to an Entity Admin user to automatically assign/revoke roles of DelegatedEntityAdmin to a user in an entity.