Role-based access control in Environmental Credit Service (preview)

  • 아티클

Microsoft Cloud for Sustainability Technical Summit May 2024

Important

Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change. You can access the Environmental Credit Service (preview) sandbox environment for a 30-day trial. To use Environmental Credit Service (preview) in a production environment, complete the Environmental Credit Service (preview) sign up form.

Role-based access control allows you to control access to different operations in the application, based on the permissions present in the roles assigned to users in the organization. It allows you to grant and remove roles assigned to the users in the organization for fine-grained control.

Each voluntary ecological market ecosystem organization plays a specific role, called a market role in Environmental Credit Service (preview). Each organization will onboard users to Environmental Credit Service (preview) and assign user roles. Resources such as ecological projects or programs, modular benefit projects, claims, and tokens belong to an organization instead of a user.

Assign user roles

A user role is defined as a collection of permissions allowing specific operations in the application. You can assign these user roles at an organization level or at an asset level within context of a specific market role. The following user roles are supported by Environmental Credit Service (preview):

User role Permissions
Admin An admin can perform all supported data-plane operations on the associated resources, such as creating, updating, reading, and deleting. They can also perform management-plane operations such as onboarding users in the organization and creating or updating role assignments for them.
Contributor A contributor can perform all supported data-plane operations on the associated resources, such as creating, updating, reading, and deleting. They also receive read access at the management-plane level.
Reader A reader can perform read operations on the associated data-plane level and at the management-plane level resources.

Manage roles at the organization level in context of a market role

The following capabilities are supported for role-based access control at the organization level within the context of a specific market role level. For example, if an organization operates as a buyer, then it has one market role (buyer). At the organization level, a user at this organization could have a Buyer Admin, Buyer Contributor, or Buyer Reader user role.

One organization can have multiple market roles. For example, if another organization operates as both an issuing registry and a marketplace, it has two market roles. A user at this organization could have a Supplier Admin role in context of the supplier market role and an Issuing Registry Reader role in context of the issuing registry role.

Manage roles at the asset level

You can manage user privileges at an asset level within the organization. The organization-level admin or contributor can create new assets. The organization-level admin can also add users to the asset and assign them roles.

  • Asset-level admin: An asset-level admin is granted the admin user role at a specific granular scope of an asset in the organization. For example, a user is assigned a supplier admin role at the scope of the modular benefit project in the supplier market role of an organization. They can perform all supported data-plane operations on the asset, such reading and writing. They can also perform management-plane operations, such as onboarding users in the organization on the specific asset that they are an admin for.

  • Asset-level contributor: An asset-level contributor can perform all supported data-plane operations on the asset, such as reading and updating the asset. They can read the role assignments of the other users or groups at the scope of that asset.

  • Asset-level reader: An asset-level reader can perform read operations on the asset. They can read the role assignments of the other users or groups at the scope of that asset.

Note

The top-down access hierarchy will be maintained. For example, if a user has an admin user role in the supplier market role at the organization scope, then they will have admin-level access automatically on all the assets (such as ecological projects and modular benefit projects) for that supplier. If another user has asset-level admin access (for example, on an ecological project), then they will have access to all the assets under it.

Capabilities supported for role-based access control

Pre-requisites for using the Postman collection for APIs

You can set the Postman collection with the environment configuration of the organizations and their admins as follows:

  • Set the user details in the different variables (for example: <marketRole>_admin_username) of the postman collection for different market roles that you want to use, along with their respective passwords.

  • Create a new Postman environment and switch to it before executing any APIs in the collection.

  • Run the Setup Organizations folder for the specific market role that you want to use, to set up the properties of the organization (and their respective admins) in the Postman environment.

  • Run the Role definitions > Get all Role Definitions API to get the details of all the built-in user role definitions in the Postman environment. The response from the role definition API can be used to learn about the assignable scopes that can be assigned to the users.

Add users

You can add users and manage their roles within the organization by switching to the Settings menu on the left navigation.

Note

You can't add a user that has already been added.

  1. On the User access screen, select Add user.
  2. On the Add user pane, enter the User, select the Access level, and then select Save. Screenshot of adding a user in the Add user pane.

Via API:

Note

The Onboard Users folder of the Postman collection supports one-click execution. However, we recommend that you use individual APIs to try onboarding users and become familiar with the APIs.

  • For any organizational folder, such as Supplier, in the Onboard Users folder of the Postman collection, set up the organization and its admin by calling the Get organization details and Get Admin User details APIs.

  • To onboard a contributor user, you can verify that the authorization required for the API corresponds to the admin user. The payload of the request attempts to add a new user with the built-in contributor user role, such as the supplier contributor user role. Sending the request onboards the contributor.

  • Similarly, you can onboard a reader user in the organization with corresponding reader role, such as the supplier reader user role.

Change role assignments

After you add users, you can change the user role assigned to them.

Note

You can't edit your own access.

  1. On the User access screen, select the three dots next to the user, and then select Edit.
  2. On the Edit access pane, select the new role in the Access level dropdown, and then select Save. Screenshot of Edit access screen removing a user.

Via API:

  1. Navigate to the Role Assignments folder in the collection.

  2. Use the Create role assignment at an asset API. By default, the supplier contributor role is assigned to the supplier reader user using the supplier admins access token.

    Note

    This example highlights how the API for role assignment works. You can assign a different user role to users from different organizations by respective admin accounts. You can change the resource URI of the scope to a valid asset URI for the role definition. Replace the environment variables in the request payload (roleDefinitionId and userId), change the resourceUri request body parameter, and alter the admin access token environment variable to match the respective admin user account.

    You can send the role assignment creation API with different values of the role definition identifier (roleDefinitionId) to be assigned to the different users in the organization (userId) at a different scope (resourceUri). You can change the authorization header to correspond to the respective admin user's access token.

    Organization admins can’t assign user roles outside their organization, and they can’t assign roles to users outside their organization.

  3. Use the Update role assignment API to update a user's access. For example, you might elevate a user to supplier admin. Be sure to verify the roleassignment_id in the API parameter.

Delete role assignments

The admin user can delete existing role assignments for participants as required.

Note

You can't delete your own access.

  1. On the User access screen, select the three dots next to the user, and then select Edit.
  2. On the Edit access pane, select None in the Access level dropdown, and then select Save. Screenshot of Edit access screen removing a user.

Via API:

  1. Set up the admin role corresponding to the organization of the user whose role assignment needs to be deleted.

  2. Navigate to the Role Assignments folder and select the Delete Role Assignment API.

  3. Enter the correct roleassignment_id in the API parameter.

  4. Call DELETE /roleAssignments/{{roleassignment_id}} by setting the authorization header with the respective admin user's access token (variables from Postman environment can be used to try users with different roles from different organizations).

View and change profile details

To view your profile details, select My account on the left navigation.

To edit your preferences, select the Edit icon in the Preferences section and select the home page you want to use. The list will indicate the different market roles that the currently signed-in user has access.

Screenshot of editing preferences.

Via API:

  1. Use the POST /organizations/{organizationId}/users/{userId}/setMyDefaultMarketRole API to switch the default market role of a user. The authorization header must use the access token of the same user as passed in the userId URL parameter. The user must have some access in the new market role being set as the default.

View role definitions

A user with any role can view different role definitions.

To view all role definitions via API:

  1. Navigate to the Role definitions folder and select the Get all role definitions API.

  2. Call GET /roleDefinitions by setting the authorization header with the respective user's access token (variables from Postman environment can be used to try users with different roles from different organizations).

To view role definitions by ID:

  1. Navigate to the Role definitions folder and choose the Get role definition by ID API.

  2. Call GET /roleDefinitions/{{id}} by setting the role definition identifier in the request URL and the authorization header with the respective users access token (variables from Postman environment can be used to try users with different roles from different organizations).

View users and assigned roles

A user with any role can view the users of the organization along with their assigned roles.

  • Navigate to the User access screen and view the users who have access.

    Screenshot of User access screen showing users and their roles.

Via API:

  1. Navigate to the Users folder.
  2. Call Get all users in my organization by setting the authorization header with the users access token from the respective organziation (variables from Postman environment can be used to try users with different roles from different organizations).
  3. Navigate to the Role assignments folder.
  4. Call Get all role assignments in my default market role to get the role assignments in the default market role of caller identity based on the resourceUri query parameter.

Manage cross-organization access controls for your assets

The admin user can manage access for assets across organizations. This can be used in multiple scenarios, for example, if a supplier had pre-committed credits to a buyer and they don't want other buyers to view the credit. Another example is insets that are to be used within the same value chain.

To support these scenarios, Environmental Credit Service (preview) has the following capabilities:

  • An admin can manage if they want the asset to be visible to all market roles or not. For example, a supplier that wants to use the credits for insets can decide to hide the visibility of the credits from all buyers. By default, the asset will be visible to all market roles, which the admin can toggle.

  • An admin can manage whether they want the asset to be visible to all organizations of a market role or not. For example, a supplier may have pre-committed credits to a buyer. The admin can manage the visibility so that the credits aren't visible to any other buyers except the intended one.

By default, the assets like ecological projects, modular benefit projects, and credits will be visible to all organizations, which the admin can toggle. The admin can set a cross-org access policy for this at different levels from lowest to highest priority as follows:

  • Organizations: A cross-org policy at an organization level implies that the cross-org access control is applied for all the assets in the organizations.

  • Ecological projects: A cross-org policy at an ecological project level carries higher priority than the previous layer. It implies cross-org access control on the specific ecological project and all the assets within it. If a cross-org policy is set at this level, then it carries precedence over any policy set at the organization level. This can be set by a user with admin access eligible at the ecological project scope.

  • Modular benefit projects: A cross-org policy at a modular benefit project level carries higher priority than the previous layers. It implies cross-org access control on the specific modular benefit project and all the assets within it. If a cross-org policy is set at this level, then it carries precendence over any policy set at one of the above layers. This can be set by a user with admin access eligible at the modular benefit project scope.

  • Credits: A cross-org policy at a credit level carries higher priority than the previous layers. It implies cross-org access control on the specific credit. If a cross-org policy is set at this level, then it carries precendence over any policy set at one of the above layers. This can be set by a user with admin access eligible at the modular benefit project scope.

Note

Admins can set cross-organizational policy for the assets they own. Supplier and Buyer are the two market roles that can set cross-organizational policies. Supplier can set it on their ecological projects, modular benefit projects, and credits. Buyer can set it on their owned credits. When calling the APIs, the x-ms-marketRole header indicates the service about the market role context in which the admin user is calling them.

Via UX:

Currently, from UX the org-level admin can set the cross-org policy at the organization level.

  1. Select Organization access on the left navigation.

  2. Select the Edit for the organization you want to change and update as necessary.

    Screenshot of Organization access screen showing cross-org access changes.

Via API:

  1. Navigate to the Organizations folder in the Postman and use the API Set cross-org access policy at organization level to set a policy at the organization level under the default market role.
  2. Navigate to the Ecological project creation folder in the Postman and use the API Set cross-org access policy on ecological project to set a policy at the specific ecological project level.
  3. Navigate to the Ecological project creation folder in the Postman and use the API Set cross-org access policy on MBP to set a policy at the specific modular benefit project level.
  4. Navigate to the Credits folder in the Postman and use the API Set cross-org access policy on credit to set a policy at the specific credit level.

Leverage groups to manage access

An admin can create groups, manage the users in a group, and assign groups with roles. This feature is currently supported via APIs only.

  • Create a user group and add users to it:

    POST /organizations/{{organization_id}}/groups

  • Get all user groups in the organization:

    GET /organizations/{{organization_id}}/groups

  • Get a user group by id:

    GET /organizations/{{organization_id}}/groups/{{group_id}}

  • Get users in a user group:

    GET /organizations/{{organization_id}}/groups/{{group_id}}/users

  • Add users to a user group:

    POST /organizations/{{organization_id}}/groups/{{group_id}}/addUsers

  • Delete a user from a user group:

    DELETE /organizations/{{organization_id}}/groups/{{group_id}}/users/{{user_id}}

  • Onboard users to a user group:

    POST /organizations/{{organization_id}}/groups/{{group_id}}/addNewUsers

  • Create a role assignment for a user group:

    POST /roleAssignments

  • Delete a user group role assignment:

    DELETE /roleAssignments/{{roleAssignmentId}}

See also

Environmental Credit Service (preview) overview
Environmental Credit Service (preview) glossary
API reference overview for Environmental Credit Service (preview)