Skip to main content

Product Requirements Document

Mission​

Our mission is to enhance our Empower's UI with an Identity and Access Management (IAM) integration, ensuring secure and efficient access to our system. We aim to provide a better user experience while maintaining the highest level of security and privacy.

Background​

Previously, our system depended on manual user role assignments (admin only) and had limited access controls, resulting in inefficient management and potential security risks. The catalyst for this project was the exponential growth in our user base and a need for a more streamlined, secure, and efficient access control mechanism.

Current Behavior​

Existing design of access is too fine-grained. It provides full control of access to assigned user. However, due to huge amount of permissions for each type of operation it is confusing for admins to properly distribute assignments and requires knowledge of the system.

Outcomes / Goals​

To improve user experience IAM will be moved to RBAC, where admin operates with user-friendly role names on multiple levels like Enterprise, Organization or Environment. Authorization is not a feature to be split into phased release, thus core functionality of it must be delivered once for all. Tweaks and improvements can be kept for future iterations.

User Stories​

Refresh Tokens on Permission Change​

  • Primary Actor: Authorized User
  • Description: When an authorized user changes permissions, the system should refresh the tokens for users whose permissions have changed. This ensures that the users have immediate access to the updated permissions.
  • Preconditions: User must be authorized and have permission to change roles.
  • Postconditions: Tokens are refreshed for affected users, granting them access based on the updated permissions.
  • Flow:
    • User changes the permissions for a particular user or group.
    • System identifies the affected users whose permissions have been modified.
    • For each affected user, the system forcibly logs them out.
    • The front-end system logs the user back in, generating new tokens.
    • The user now has access with the updated permissions.

Role Management Modal - View and Modify Roles​

  • Primary Actor: Administrator (if allowed) or Non-admin User
  • Description: The system provides a role management modal that allows authorized users to view and, if permitted, modify roles assigned to other users.
  • Preconditions: User must be authorized and have access to the role management feature.
  • Postconditions: Users can view role assignments and, if allowed, modify roles for other users.
  • Flow:
    • User opens the role management modal from the user interface.
    • The modal displays a title and an exit icon.
    • User can search for a specific user using the search field.
    • The modal lists users with their associated roles in a drop-down format.
    • If the user has permission, they can select a different role from the drop-down for any user.
    • The drop-down also includes a delete option to remove a user's role.
    • Information or help text is provided to guide the user in understanding the role management process.
    • Buttons: The user can cancel the changes or update the roles.
    • The modal includes a link to navigate to higher-level role management if available.

Use cases​

Admin Adding Roles Successfully​

  1. Enterprise Admin
    1. Primary Actor: Enterprise Admin
    2. Description: Assigning the Organization Admin role to a user.
    3. Preconditions: The user does not currently hold the Organization Admin role.
    4. Postconditions: The user now holds the Organization Admin role.
    5. Flow:
      1. Enterprise Admin opens role management modal.
      2. Searches and selects user.
      3. Selects Organization Admin role from the drop-down menu.
      4. Updates the roles.
      5. System confirms role assignment.
  2. Organization Admin
    1. Primary Actor: Organization Admin
    2. Description: Assigning the Environment Admin role to a user.
    3. Preconditions: The user does not currently hold the Environment Admin role.
    4. Postconditions: The user now holds the Environment Admin role.
    5. Flow:
      1. Organization Admin opens role management modal.
      2. Searches and selects user.
      3. Selects Environment Admin role from the drop-down menu.
      4. Updates the roles.
      5. System confirms role assignment.
  3. Environment Admin
    1. Primary Actor: Environment Admin
    2. Description: Granting specific privileges to a user within the environment.
    3. Preconditions: The user does not currently hold these specific privileges.
    4. Postconditions: The user now holds these specific privileges.
    5. Flow:
      1. Environment Admin opens role management modal.
      2. Searches and selects user.
      3. Assigns specific privileges from the drop-down menu.
      4. Updates the roles.
      5. System confirms privilege assignment.

Admin Adding Roles Unsuccessfully​

  1. Organization Admin
    1. Primary Actor: Organization Admin
    2. Description: Attempting to assign the Enterprise Admin role to a user.
    3. Preconditions: The user does not currently hold the Enterprise Admin role.
    4. Postconditions: The user still does not hold the Enterprise Admin role.
    5. Flow:
      1. Organization Admin opens role management modal.
      2. Searches and selects user.
      3. Tries to assign Enterprise Admin role from the drop-down menu.
      4. System blocks action and gives an error message.
  2. Environment Admin
    1. Primary Actor: Environment Admin
    2. Description: Attempting to assign the Organization Admin role to a user.
    3. Preconditions: The user does not currently hold the Organization Admin role.
    4. Postconditions: The user still does not hold the Organization Admin role.
    5. Flow:
      1. Environment Admin opens role management modal.
      2. Searches and selects user.
      3. Tries to assign Organization Admin role from the drop-down menu.
      4. System blocks action and gives an error message.

Admin Removing Roles Successfully​

  1. Enterprise Admin
    1. Primary Actor: Enterprise Admin
    2. Description: Revoking the Organization Admin role from a user.
    3. Preconditions: The user currently holds the Organization Admin role.
    4. Postconditions: The user no longer holds the Organization Admin role.
    5. Flow:
      1. Enterprise Admin opens role management modal.
      2. Searches and selects user.
      3. Selects delete option from the drop-down menu to remove Organization Admin role.
      4. System confirms role revocation.
  2. Organization Admin
    1. Primary Actor: Organization Admin
    2. Description: Revoking the Environment Admin role from a user.
    3. Preconditions: The user currently holds the Environment Admin role.
    4. Postconditions: The user no longer holds the Environment Admin role.
    5. Flow:
      1. Organization Admin opens role management modal.
      2. Searches and selects user.
      3. Selects delete option from the drop-down menu to remove Environment Admin role.
      4. System confirms role revocation.
  3. Environment Admin
    1. Primary Actor: Environment Admin
    2. Description: Revoking specific privileges from a user.
    3. Preconditions: The user currently holds these specific privileges.
    4. Postconditions: The user no longer holds these specific privileges.
    5. Flow:
      1. Environment Admin opens role management modal.
      2. Searches and selects user.
      3. Selects delete option from the drop-down menu to remove specific privileges.
      4. System confirms privilege revocation.

Admin Removing Roles Unsuccessfully​

  1. Organization Admin
    1. Primary Actor: Organization Admin
    2. Description: Attempting to revoke the Enterprise Admin role from a user.
    3. Preconditions: The user currently holds the Enterprise Admin role.
    4. Postconditions: The user still holds the Enterprise Admin role.
    5. Flow:
      1. Organization Admin opens role management modal.
      2. Searches and selects user.
      3. Tries to select delete option from the drop-down menu to remove Enterprise Admin role.
      4. System blocks action and gives an error message.
  2. Environment Admin
    1. Primary Actor: Environment Admin
    2. Description: Attempting to revoke the Organization Admin role from a user.
    3. Preconditions: The user currently holds the Organization Admin role.
    4. Postconditions: The user still holds the Organization Admin role.
    5. Flow:
      1. Environment Admin opens role management modal.
      2. Searches and selects user.
      3. Tries to select delete option from the drop-down menu to remove Organization Admin role.
      4. System blocks action and gives an error message.

Non-Admin Adding Roles Unsuccessfully:​

  1. Writer/Executor Role
    1. Primary Actor: Writer/Executor Role
    2. Description: Attempting to assign an Admin role to another user.
    3. Preconditions: The targeted user does not currently hold an Admin role.
    4. Postconditions: The targeted user still does not hold an Admin role.
    5. Flow:
      1. Writer/Executor User opens role management modal.
      2. Searches and selects user.
      3. Tries to assign Admin role from the drop-down menu.
      4. System blocks action and gives an error message.
  2. Read-Only Role
    1. Primary Actor: Read-Only User
    2. Description: Attempting to grant privileges to another user.
    3. Preconditions: The targeted user does not currently hold the intended privileges.
    4. Postconditions: The targeted user still does not hold the intended privileges.
    5. Flow:
      1. Read-Only User opens role management modal.
      2. Searches and selects user.
      3. Tries to assign privileges from the drop-down menu.
      4. System blocks action and gives an error message.

Non-Admin Removing Roles Unsuccessfully​

  1. Writer/Executor Role
    1. Primary Actor: Writer/Executor User
    2. Description: Attempting to revoke an Admin role from another user.
    3. Preconditions: The targeted user currently holds an Admin role.
    4. Postconditions: The targeted user still holds an Admin role.
    5. Flow_:
      1. Writer/Executor User opens role management modal.
      2. Searches and selects user.
      3. Tries to select delete option from the drop-down menu to remove Admin role.
      4. System blocks action and gives an error message.
  2. Read-Only Role
    1. Primary Actor: Read-Only User
    2. Description: Attempting to revoke privileges from another user.
    3. Preconditions: The targeted user currently holds the intended privileges.
    4. Postconditions: The targeted user still holds the intended privileges.
    5. Flow:
      1. Read-Only User opens role management modal.
      2. Searches and selects user.
      3. Tries to select delete option from the drop-down menu to remove privileges.
      4. System blocks action and gives an error message.

Requirements​

Functional​

  • If user switches between enterprises, then the user should go through Keycloak (KC) re-auth cycle
  • If the user switches between organizations, then no re-auth should happen as it is within the same KC realm
    There is 1 KC realm per enterprise as it is the SSO boundary, as well as an Hitachi shared realm for all the required Hitachi users (applied only to internal services)
  • When the authorized user changes the permission for other users, token is refreshed and force-logs out the user to re-auth with updated permissions/role
  • Group management will not be supported at this time, other than the existing user groups maintained in Azure Active Directory
  • All roles and permissions mapped in KC
  • User list is populated at Enterprise, Organization, and Environment level to be sorted by permissions (highest to lowest) as well as alphabetically (by user first name)
  • Front door service that hosts user information and their access across potentially multiple Empower products
  • All names are obfuscated in JWT or global ids should be used instead of plain names

Roles​

Roles in Identity and Access Management (IAM) are a way to define a set of permissions or privileges within a system. They are typically used to establish different user access levels and assign specific privileges to each user group.

Claims​

Claims in Identity and Access Management (IAM) refer to key-value pairs that contain information about the user's identity and attributes. These claims are usually provided by the Identity Provider (IdP) during the authentication and authorization process. The IdP could be an internal directory service like LDAP or Active Directory.

Policies​

Policies in Identity and Access Management (IAM) are sets of rules that define the specific permissions and access granted to users, groups, or roles within a system. Policies provide a flexible and scalable way to manage access to resources in your environment.

Access level hierachy​

  • Enterprise ----- Enterprise admin
    • Organization ----- Organization Admin
      • Environment ----- Environment Admin
Hierarchy RolesEnterpriseOrganizationEnvironment
AdminEnterprise AdminOrganization AdminEnvironment Admin
WriterEnterprise WriterOrganization WriterEnvironment Writer
ExecutorEnterprise ExecutorOrganization ExecutorEnvironment Executor
ReaderEnterprise ReaderOrganization ReaderEnvironment Reader

Policies​

RolesPoliciesAccess Management
Enterprise AdminRead, write and Execute access within an EnterpriseAccess Management within an Enterprise
Enterprise WriterRead and write access within an EnterpriseNo
Enterprise ExecutorRead and execute access within an EnterpriseNo
Enterprise ReaderRead access within an EnterpriseNo
Organization AdminRead, write and Execute access within an OrganizationAccess Management within an Organization
Organization WriterRead and write access within an OrganizationNo
Organization ExecutorRead and execute access within an OrganizationNo
Organization ReaderRead access within an OrganizationNo
Environment Environment AdminRead, write and Execute access within an EnvironmentAccess Management within an Environment
Environment WriterRead and write access within an EnvironmentNo
Environment ExecutorRead and execute access within an EnvironmentNo
Environment ReaderRead access within an EnvironmentNo

Non-functional requirements​

  • Solution should be scalabale and extandable to support adding or removing any amount of clients w/o consequences
  • UI should be responsive and performant

Out of Scope​

  • We will not support any group management in our application, only users and groups that already exists in Entra will be provided appropriate permission, we will use Postman as a reference.
  • Changing identity broker, since Keycloak is existing tool of choice
  • Granting access to groups from client's tenant (Entra ID)
  • Importing groups from client's tenant (Entra ID)
  • When the authorized user changes the permission for other users, we should be refreshing their token and forcibly logging them out to make the user login again into the application with the changed permissions.

Dependencies & Constraints​

  • Frontend developer availability
  • Frontend <-> Backend team coordination for API integration
  • Potential need for third-party IAM libraries and/or services
  • All Keycloak's functionality is supported by terraform provider

Assumptions​

  • Safe and secure access controls
  • Streamlined access management, improved user experience, and reduced security and access risks

Risks​

  • Difficult transition from existing auth to RBAC
  • IAM integration may not achieve the intended outcome due to technical or integration challenges
  • Scope creep and/or misaligned stakeholder expectations
  • Meeting compliance and/or security requirements

Timeline and Milestones​

Phase I​

  • Release 1.18
  • UX delivered, but API does not yet respect assigned roles.

Phase II​

  • Release 1.19
  • Defined Roles are Respected but only when feature flagged:
    • This flag is defaulted to “off” but can be set to “on” on an environment basis.
  • Usability documentation delivered:
    • Especially about “who is the first admin”
    • Who is the first DA System Admin from the enterprise level?

Phase III​

  • Release 1.20
  • UX is FULLY functional, but feature flags retained to suspend functionality in client environment(s) in case errors are encountered or more user training is needed
  • Feature flags are defaulted to “on” but can be set to “off” on an environment basis

Phase IV​

  • Release TBD
  • Feature flags removed and new Access Management regime is Empower gospel

Questions?​