Skip to main content

Creating new records

When using access records there are some common patterns that might be frequently used. Below each of these is discussed.

Access record usage

Access records are the core of Authress and are usually categorized in three different usages:

1. A record represents the permissions that a user or a group has to a list of resources.

Common situations are the creation of a team or user group and the resources that group owns. When the number of resources is small or contains multiple wildcards (*) this pattern works well. Good examples of this is the Authress Admin or individual Engineering Team 01. These teams likely own * to all the resources in their domain, and nothing else. They might not even be granted access to the Authress portal.

2. A record represents everyone who can access a specific resource.

In cases where you are focusing on Resource-Based Access Control, the records most likely represent an actual resource in your software. For resource A, here are the list of users and groups that can access it. This frequently happens when we have resources like a file system, or document repository. When you want to make changes for the specific resource for a user, you can find the appropriate record and update the specific roles for that user.

3. A record represents an arbitrary product concept

Not everything in your application lends itself to a specific user/group or a specific resource. Perhaps there is a specific permissions situation where a group of resources and a group of users is heavily coupled together. In these cases, a record need not represent either a specific user or a specific group, but in stead can be used however it makes the most sense for your application. Common usages of this is when there are highly used resources and often shared with a high number of users. In these cases an access record might represent the intersection of a user AND a resource. To achieve these more complex situations, users, roles, and resources can allow be assigned at the statement level instead of at the top of an access record.

Specifying users at the statement level

The Record ID

When creating access records, keep in mind the use cases above. These use cases will help you define what the identifier of the access record should be. Access records are dynamically assigned record IDs, however, you can specify the record ID when creating the record.

When creating a record focused on a user or group, set the record ID to be of the form rec_user:${userId} or rec_group:${groupId}, and likewise when creating a record that represents a resource specifically, set the record ID to be rec_resource:${resourceId}. This is not a requirement and there are very few rules for what the resource record should be, but by doing this, when you want to change the permissions of a user, you can directly look up the user's record and patch it using rec_user:${userId}.

It's worth noting that access record IDs cannot be directly changed. A new record would need to be created with the identifier.

Record namespaces

Just like resources and permissions, records too can utilize the namespace: prefix to group access records together. For instance, the service called the document repository might want to scope the IDs of access records. So when creating a new access record for resources specific to the document repository service, these record IDs might take the form rec_document_repository:resource-${resourceId}. While the actual format is completely up to the implementation, the only important part of this example is the :. The rec_document_repository: prefix of the access record ID, enables you to give access to other entities in your platform. For instance, the team that owns the document repository service might need READ on Authress:AccessRecords/rec_document_repository:*. Allowing anyone from that team to see the relevant records in the Authress Management Portal.

Reminder: record admin

Just because a user has the UPDATE permission an Authress:AccessRecord/ does not mean they have permissions to make any changes they want. Being admin allows them to edit the record. But it does not give them the ability to grant themselves nor others permissions that they don't already have. When updating an access record a user must have both UPDATE (or be an explicit Admin of the record) AND have the GRANT or DELEGATE on the permissions they are giving others.

  • If they are giving out the ALLOW permission, then they must have GRANT or DELEGATE
  • And if they are giving out GRANT or DELEGATE, then they must have DELEGATE.