World Modeler Server API Programmers Reference Section 9

9. Access Control

Unlike privately owned assets which are implicitly available to the user who owns them, organization owned assets are only available to organization members who are given permission to the asset, and the operation being performed on it.

To generalize the permission system, assets are considered a type of resource, and asset operations (such as getting or evaluating a dataReader) are considered an operation that acts on that resource. Every resource/operation pair is granted its own permission, and for a member of an organization to be allowed to act on a resource or asset, they must have first have the particular permission acting on that resource/operation pair.

To accommodate the permission needs of both World Modeler™ and dependant applications, resources and operations are fundamentally dynamic. The resources and operations we will be discussing later in this section are considered static, and are automatically provided (and required) when a WMServer instance is initialized. Any number of resources, operations, and permissions can be defined by the developer using World Modeler™ in their application.

Types of Permissions

Permissions are broken up into three groups:

  • User Permissions:
    • These are granted on a user by user basis, per resource-operation.
  • Role Permissions:
    • These are granted to a class of users, each member of the organization who possess the role. Generally, roles encapsulate more than one resource-operation permission. Role permissions also possess a priority among other roles. If a role grants permission, but a higher priority role denies it, the permission will be denied to the user. Additionally if there are two roles with the same priority, denials are prioritized over grants.
  • Organization Permissions:
    • These are granted to every member of an organization, and act as a basis upon which role and user permissions modify.

The three groups of permissions have a hierarchy. User permissions will be preferred to Role Permissions, and Role Permissions will be preferred to Organization Permissions. Permissions can both grant and deny a resource. If a User permission denies a resource that a Role grants, the user is denied the permission overall.

The full set of permissions a user possesses is as follows:

  • Every User Permission granted, and not denied.
  • Among the remaining permissions, every Role Permission of the highest priority that is granted, and not denied.
  • And among the remaining permissions, every Organization Permission that is granted, and not denied.

Types of Privileges

In addition to permissions, which are dynamic and handle the entire set of resources and operations, there are privileges which encapsulate everything. Privileged users have access to every resource-operation regardless of what permissions they have. There are two privilege types:

  • SysAdmin
    • As a system administrator, this user has access to every resource and operation for every organization, regardless of whether they have permission, or are even a member of that organization.
  • OrgAdmin
    • As an organization administrator, this user has access to every resource and operation for every organization they are an OrgAdmin in, regardless of what permissions they possess.

There is no endpoint to assign a SysAdmin, this has to be done in the database. SysAdmins may assign organization members to be OrgAdmins, but OrgAdmins may not assign other members to be OrgAdmins.

Default Roles

As discussed above, access to every asset and resource in an organization requires a permission, but the ability to create and modify roles and permissions also requires a permission. Fundamentally, roles are dynamic and can be created as required, but to ensure smooth operation organizations contain four static roles.

  • Member
    • Every user who joins an organization is assigned Member by default. By default, Members are granted the rights to get and create assets, and evaluate evaluatable assets.
  • Administrator
    • The owner of the organization is granted Administrator. By default this role has every permission granted, but this is dynamic and subject to change. This should not be confused with OrgAdmin, which is a privilege.
  • Manager
    • Managers, in addition to the permissions granted to members, possess the ability to update and delete assets, and manage organization users, roles, and permissions.
  • Terminated.
    • This role has the highest priority among the other static roles, and denies every permission. The purpose of this role is to denote users who are no longer members of an organization without directly removing them, which could potentially malform organization managed tables and views.

Additional roles can be created by users with permission to manage roles.

Applications

As a multi-tenant system, a single WMServer instance can partition multiple applications at once. To ensure that two different applications can define resources and operations without any intersection, resources are defined in the context of an applicationID, which are unique. All static resources and operations are defined in the "WMServer" applicationID.

Static Resource/Operation Table and Default Permissions

Currently there are 16 resources and 110 operations among them. I chose not to build out this table for the time being due to that. If we need proper documentation on these later down the line I can come up with a shorter means of achieving that.

Resource Operation Description Member Default Manager Default
All assets Get false true

Defining Resources/Operations in WMServer

As seen in the above table, resources and operations are considerably expansive. In the current version of World Modeler™ alone there are over a hundred. To effectively manage each one, WMServer defines the interface IResource which has the virtual static method IResource.ResourceDefinition(). Resources and operations are defined on a class by class basis. For each class that implements IResource and makes use of the permission system, it must define the set of resource and operation names in IResource.ResourceDefinition() that it makes use of in its methods. In addition to that, resource definitions interface with the static roles mentioned above, setting defaults for each permission generated contained by those roles.

Classes that implement IResource can make use of the resources they define with the WMAccessManager class, which has the methods GetPermissionAsync and EnsurePermissionAsync to check if a user has permission, and throw a 403 if the user lacks permission, respectively.

During runtime, every IResource derived type in the application is queried, and the full set of resource definitions are compiled and cached for later use.

In order to add a new resource or change existing operations, it is as simple as implementing a new IResource or changing the resource definition of an existing IResource derived type.

Dynamic Database Seeding

To ensure World Modeler™ can function normally, all of the resources, operations, and permissions required by the IResourcess defined in the application need to be managed in the database dynamically, without SQL initializer or conversion scripts. This can be done with a flag set in appsettings.json, but has a few best practice restrictions.

  • If multiple WMServer instances access the same database, only one instance should ever have the flag set to prevent concurrency issues
  • Even if the resources, operations, and permissions are up to date, querying the database to ensure this is a heavy operation and adds a severe startup delay to the application. If everything is up to date, the flag should not be set.

The key in question is:

    ...
    "SeedDB": true,
    ...

If false, or if the line isn't present at all, the flag will default to not set.

⇦ Prev: 6. LLMs