Access Management & fine-grained permissions

Overview

The Access Management application is a centralized place to provision access for users to all Willow products and applications. It also enables provisioning access for 3rd party applications and integrations to the Willow API. Administrators assign fine-grained permissions, ensuring that users have access to the appropriate resources and functionalities based on their roles. This feature allows for precise role-based assignments, supporting complex organizational structures and varying levels of access. By streamlining access management, it improves security while enhancing the user experience by tailoring access to individual needs.

The diagram above illustrates the key entities and relationships in Access Management.

1. User: Represents an individual who can login to Willow applications. Users can belong to one or more groups. Users can be directly assigned roles, but this is not the recommended way to manage users. Instead, it is preferable to add users to a group which gets a role assignment.

2. Group: A collection of users. Groups help organize users and simplify role management by allowing multiple users to be administered access together. Groups can have one or more assignments.

3. Permission: Represents an action that a user can perform for a specific Willow Application such as WillowApp.CanViewInsights. Permissions can belong to one or more roles.

4. Role: A collection of permissions that defines what actions a user or group can perform across the Willow applications. An individual role can be used for one or more assignments. Each assignment connects a user or group to a single role.

5. Assignment: Connects a group (or user) to a single role with an optional scope. While an assignment consists of a single group and role, the same group and role can be used for another assignment. When a group has more than one assignment, the permissions are additive for the users in that group.
6. Scope: Optionally limits all of the permissions in an assignment to a Location. For example, let's say there is a role with two permissions WillowApp.CanViewInsights and WillowApp.CanViewDashboards. If a group is given an assignment with that role and a scope of Building A, each user in that group has effectively been granted two limited permissions: 1) WillowApp.CanViewInsights for Building A and 2) WillowApp.CanViewDashboards for Building A.

Getting Started with Access Management

There are two methods for navigating to Access Management:

1. When the new Access Management is enabled on your organization's Willow account, the Admin section within Willow App includes an option to open the Access Management application. Administrators will see an option under the Users tab, indicating that user administration has moved. By clicking Open Access Management, they can access the new app to add, edit, or remove users as needed.

2. The Access Management application has an organization-specific URL.

For example, if your customer-specific URL is https://xxxx.app.willowinc.com, you can login to Access Management by adding /access-management at the end of the URL, like this:

Example:
https://xxxx.app.willowinc.com/access-management

Using this URL will take you directly to the Access Management login page where admin users can sign in and manage users, groups, roles, and assignments.

Add a New User

Follow these steps to add a new user to the and assign them to specific groups.

1. Open the Add User form

• Navigate to the Users page within the side navigation menu. 
• Click on the Add User button to open the user creation form.

2. Fill in user details

• Enter user details by filling in the user's First Name, Last Name, and Email Address.
• By default, the Status checkbox is set to Active. Leave this checked to ensure the user is immediately active upon creation. If you wish to create the user but not activate them yet, uncheck this box.

3. Add user to group(s)

• In the Groups field, add the user to one or more groups so they can be provisioned access with their peers that also belong to the group.
• Groups (e.g., "101 Ridley Square Viewers") can be assigned as necessary by typing the group name and selecting from the dropdown list.

4. Finalize the user creation

• Once all fields are filled out, click Add to save the new user.
• If you need to cancel the operation, click Cancel to close the dialog without saving.

Note: Users will log in via Single Sign-On (SSO), and authentication will happen through your 
organization's identity provider. No password is required during user creation in Willow App.

Welcome Email

After the user is successfully added, if the group they were added to has already been provisioned with an assignment to a role that includes permissions to the Willow App, they will receive a welcome email with instructions on how to log in and get started with the Willow App. Ensure the email address is correct so that the user can receive this communication.

The steps above should be sufficient for a new user to get started with Willow App as long as 
the groups they are assigned to are already connected to the relevant roles via assignments.

Managing Users 

The Users page allows administrators to view, edit, and delete user accounts. Follow the steps below to manage users effectively.

1. Viewing the users list

• Navigate to the Users page within the side navigation menu. 

• The users page displays all users, showing their email address, first name, last name, and status (Active or Inactive).

• To access a user’s profile, click on the user’s email address in the Email column. This will open their User Profile page, where you can view and edit their details, groups, and assignments.

2. Editing user profiles

• In the User Profile page, you can:
  • Edit User Details: Modify the user’s first name, last name, email, and status (Active or Inactive).
  • View Groups: Click on the Groups tab to view and manage the groups to which the user belongs.
  • View Assignments: Click on the Assignments tab to view and manage role assignments and scope for the user.

3. Deleting a User

• From the User Profile page, you can delete the user by clicking the Delete User button in the upper-right corner of the page. Warning: Deleting a user is permanent and will revoke all associated roles and permissions.

Note: When a user's permissions change either by being added or removed from a group or assignment,
it may take up to 5 minutes to be reflected in Willow applications. 

Managing Groups 

The Groups page allows administrators to view, create, edit, or delete groups within the system. Groups are critical for managing user access and permissions based on roles. Follow these steps to manage groups effectively.

1. Viewing the groups list

• Navigate to the Groups page within the side navigation menu.
• The groups page displays a list of all existing groups with the following details:
  • Name: The name of each group.
  • Group Type: This indicates whether the group is managed within the application.
  • Users: Displays avatars or initials representing the users assigned to each group.

2. Creating a group

• Click the Add Group button in the upper right corner of the page.
• Fill in the details for the new group:
  • Group Name: Provide a descriptive name for the group.
  • Group Type: Choose Application as type to indicate that the group is managed within the application.
• Click Save to create the group.

3. Assigning users to a group

• To assign or remove users from a group, click View Group from the action column, which opens the group details page.
• Use the Assign button to add new users to the group by searching for their name or email. You can also remove users from this view.

4. Managing groups

• On the far-right side of each row, there is an Actions column with three vertical dots (⋮). Clicking on this will show the following options:
  • Edit Group: Allows you to modify the group name or other group-specific settings.
  • View Group: Opens the group's details, including the list of users assigned to it.
  • Delete Group: Removes the group from the system entirely. Note: Deleting a group will also remove all user associations with that group.

Managing Roles and Permissions 

Roles define a set of permissions that control what users can do across the system. Follow the steps below to create roles, assign permissions, and manage roles effectively.

1. Viewing the roles list

• Navigate to the Roles page within the side navigation menu.
• This page displays all existing roles along with a summary of their permissions. Each role includes:
  • Role Name: The name of the role (e.g., TLM Reader, WillowApp Viewer).
  • Permissions: A summary of key permissions assigned to the role is shown. Examples of permissions include CanViewInsights, CanViewTwinDetails and others.
    
    • To view all permissions assigned to a role, click on the role name in the Name column. This will take you to the role’s detail page where all permissions are listed.

2. Creating a role

• Click the Add Role button in the upper-right corner of the Roles page.
• A dialog will appear titled Add Role:
  • Name: Enter a descriptive name for the role.
  • Description: Optionally, provide a brief description that explains the purpose of this role.
• Once the details are filled out, click Add to create the role. If you wish to cancel, click Cancel to exit without creating a role.

3. Managing roles

• In the Actions column (⋮) next to each role, you will find options to manage the role:
  • Edit Role: Select this option to edit the role’s name and description.
  • View Role: This option takes you to the role’s detail page, where you can see all assigned permissions.
  • Delete Role: This allows you to permanently delete the role. 

4. Assigning permissions to a role

• To assign permissions, first click View Role from the Actions column.
• On the role’s detail page, click the Assign button to add permissions to the role.
• In the Assign Permission dialog that appears, search and select permissions. Permissions are grouped into categories (e.g., WillowApp, ActiveControl, TLM).
• Once you’ve selected the appropriate permissions (e.g., CanViewInsights, CanViewTwinDetails), click Add to assign them to the role.

5. Managing Role Permissions

• After permissions have been assigned, they will appear in a list on the role details page.
• You can remove these permissions by using the trash icon (🗑️) next to each permission to remove it if necessary.

Managing Assignments

Assignments connect a user or group to one or more roles, scoped to specific locations or expressions. Here’s how to manage assignments, including creating and customizing them.

1. Viewing the assignments list

• Navigate to the Assignments page within the side navigation menu.
• This page shows all existing assignments, including:
  • User or Group: The user or group assigned to a role.
  • Role: The role assigned to the user or group.
  • Scope: The specific location or area to which the user is restricted and where their roles/permissions are applied (e.g. US Region > 104 Bedford Campus). This defines the scope within which the user has access.

2. Creating an assignment

• Click the Add Assignment button in the upper-right corner of the Assignments page.
• In the Add Assignment dialog, provide the following details:
  • User or Group: Select the user or group for whom the assignment is being created by typing in the search box.
  • Role: Choose the role that will be assigned to the selected user or group by typing in the search box.
  • Location (Scope): Choose the location (scope) where the role will apply, such as buildings or specific locations within buildings (e.g., 101 Ridley Square, Retail Store #7). This limits the role's permissions to that specific area. Note: This is an optional field, leaving this blank will apply the role across the platform. 
  • Condition: Optionally, you can apply a custom condition.

3. Using expressions for assignment

• If the role assignment requires a condition that is not based on a pre-selected location, enable the Expression toggle:
  • When Expression is enabled, manually enter a twin expression (e.g., [WIL-EU-Region]). 

4. Finalizing the assignment

• Once all the necessary fields are completed, click Add to create the assignment.
• If you wish to cancel the operation, click Cancel to exit without saving.