Access Control
The platform leverages a policy based access control system to authorize service and client operations. This system provides powerful and customizable access control rules for platform services and client applications.
How authorization works
Users of the platform are assigned a role. When the user requests an action of a service or client application, the authorization of the action is determined by evaluating the policies attached to the role assigned to the user. If evaluation of the policies results in an explicit DENY then the action is unauthorized. If any of the policies results in an explicit ALLOW, then the action is authorized.
For example, Alice is assigned the role Application User which has multiple policies attached to it. One of those policies allows the api:rooms:listRooms action. This means when an application using Alice’s credentials sends a request to list rooms, the request will be allowed to fetch a list of rooms.
In summary, authorization of an action is determined by evaluating policy statements against a requested action on a resource by a principal within an execution context.
Authorization = Principal + Action + Resource + Context
Policies
Policies are simply JSON documents with a list of statements explicitly allowing or explicitly denying actions of a platform service or client application. Policies are best organized by service and type of access, or by purpose. For example a policy can be made to allow read access to all spaces and another can be made to allow read & write access to all spaces.
Policy types
The platform allows for two types of types of polices.
Managed polices
Managed policies are created and maintained by the platform. They generally cover common use cases of the various platform services.
Custom policies
Custom policies are created and maintained by the organization. Custom policies are useful for organizations that have specific security requirements for data resources and client applications features
Policies are simply JSON documents with a list of statements explicitly allowing or explicitly denying actions of a platform service or client application. It can optionally specify conditions that must be met to evaluate.
Policy JSON
// Policy json
{
"statements": [
{
"effect": "allow | deny",
"actions": [ "service:operation" ],
"conditions": [
{
expression: ""
operator: ""
values: [""]
}
]
}
]
}
// Policy example
Roles
Roles are a mechanism for grouping policies for assignment to users, space members, and extensions .
Role types
The platform allows for two types of types of roles.
Managed roles
Managed roles are created and maintained by the platform. They generally cover common use cases for different types of users.
Custom roles
Custom roles are created and maintained by the organization. Custom roles are useful for organizations that have specific security requirements for access control.
Role assignment
Once the defined, policies can then be attached to to one or more roles. Roles are then assigned to one or more users, space members, or extensions. In addition, there are some additional role attributes to consider.
Role principals
Roles have one or more usages that determine which principals can be assigned the role. Principals are actors that can request actions of platform services or client applications.
Principals types
Team Users
Team users are users that manage the content, access, and settings of the platform. They generally have administrative, development, quality assurance, and billing roles.
Application Users & Guests
Application users are end-users that use client applications to access content. They generally are assigned application user roles.
Space members
When a user is granted access to a space, the relationship is called a space members. That relationship can optionally be assigned a role to allow or deny additional actions for either server or client access.
Extensions
Extensions users are for custom applications that run alongside users or independent of a user.
Role levels
Role levels are an optional attribute that allows for creating a “fence” around access control. This is useful when allowing non-administrative users to assign roles while preventing such users to elevate their own access. Valid role levels range from 0 to 9000 and lower values indicate lower access.
During role assignment operations, the lowest role level of the principal performing the action is used to determine if the requested roles are accessible to the principal. For the purpose of evaluation, roles assigned to the principal without a level set defaults to a level of 0, while roles requested for assignment without a level set defaults to a level of 9000.
UI Considerations
When a client applications exposes a role assignment interface, it’s possible to use a combination of role principals and role levels to filter the list of available roles for assignment based on the context.
Implicit role assignment and overrides
In some cases there implicit roles used for evaluating access.
Space owner
A space owner is implicitly assigned the Space Administrator managed role. It is possible to use a different implicit space owner role by changing the default in the management console’s Authentication & Authorization settings.
Guests
A guest users is implicitly assigned the Application User managed role. It is possible to use a different implicit guest user role by changing the default in the management console’s Authentication & Authorization settings.