Modeling Users, Permissions, and Roles

Using local roles, local users, and canonical permissions to describe access

Using local_users to describe local and federated identities and service accounts

Most applications will have some concept of a “local user” that can have varying permissions to data and metadata. Most modern cloud applications offer some form of single sign-on. In some cases, local user accounts correspond to an external federated identity, or even only exist ephemerally.

The Open Authorization API is able to represent local users, local groups, and external identities. An external identity could be an user connecting directly to a resource through Single Sign On, or an SSO group. A local user could be a just-in-time account created when an IdP user first connects.

You should represent system users using local_user objects, even for apps that are SSO-enabled. The local user object is able to contain useful attributes such as activity status and timestamps, enabling rich search on those entities. A local user can also reference a federated identity, creating graph relationships between IdP entities and local users and groups when the payload is parsed. Veza handles these cross service connections similarly to built-in integrations such as Snowflake.

• The OAA template supports direct permissions from IdP users to resources. However, including a local user entity in your OAA mapping strategy is still recommended when possible.
• Users can also be grouped and assigned permissions with local_groups.

Map provider permissions to Veza canonical permissions

Veza understands an identity's level access to a resource in terms of raw system permissions in the provider's terms (such as AWS IAM s3:DeleteBucket), and canonical permissions (such asDATA DELETE). This allows Veza to answer the questions: "Who has MERGE permission on production repositories?" and "who can read data from any resource flagged for PII compliance?".

OAA requires you to map each granular application permission (like "view ticket" or "close ticket") to its corresponding C/R/U/D permission. This enables search and audit of effective and configured access.

Raw ("System") Permission	Canonical Permission
Manage Access	Metadata Write
Merge	Data Write
Pull	Data Read

Modeling role-based access control

SaaS apps tend to be role-based, and organizations that follow security best practices will typically restrict the assignment of permissions directly to users. Following standard RBAC concepts, an OAA role represents a collection of permissions which can be scoped to individual resources or specific resource types.

If permissions granted by a role only apply to specific resource types or sub-resources, create the custom permissions individually and add them to the role in a list:

self.app.add_local_role("Write", ["Pull", "Fork", "Push", "Merge"])

Under the custom application OAA schema, users can have direct permissions and role-based permissions to resources. Modeling these role-based permission assignments will enable searches such as "show all users with the maintain role in GitHub."

Note that “roles” in some apps actually function more like groups (lists of users), in which case they should be modeled using local_groups.

For payloads where permissions apply for the entire application, you can create a single custom permission for a role, containing all the associated canonical permissions:

self.app.add_custom_permission("limited_user", permissions=[OAAPermission.DataRead, OAAPermission.MetadataRead])
self.app.add_local_role("Responder", unique_id="limited_user", permissions=["limited_user"])

As demonstrated in the OAA PagerDuty connector, this is a quick way to model authorization structures such as:

Custom Application Role	Custom App Permission	Canonical Permission
Account Owner	owner	Data Write, Data Read, Data Delete, Metadata Read, Metadata Write
Responder	limited_user	Data Read, Metadata Read
Observer	limited_user	Data Read, Metadata Read