Granting access to users
Access Records​
Authorization checks verify a user's permissions to a particular resource. A check always includes user, resource, and permission. So the creation and assignment of permissions must also include these three same properties. Access records are the place in Authress where these are specified and the user gets those permissions.
Access records combine permissions with resources to make statements, and access records statements are assigned to a user list or group. A user user_id might have star (*) access to all documents in an organization /organizations/org1/documents/✶. (For brevity, in the following cases /organizations/org1 is usually omitted.)
Roles​
Instead of directly assigning permissions, access records use roles. The only difference between roles and permissions is that roles are a list of permissions. They do not specify resources. Assigning a role for a resource to a user in an access record gives that user all the permissions in the role to the resources in the statement.
Users​
The list of all users will gain access via the roles to the resources in the access record statements. Subsets of users are supported via groups. To give different users different access, create separate access records, one for each list of valid statements.
Statements​
To prevent unnecessary proliferation of access records, records support multiple statements. Statements are independent and do not affect each other. The roles in a statement apply to the resources in the statement, but not to other statements. This makes it easy to assign different levels of permissions to different resources all for the same users in the same access record.
Cascading resources​
Access records resources always imply cascading permissions to sub-resources. When a permission documents:read is assigned to a user for resource /documents/✶, this implies they also have documents:read to /documents/A and /documents/B/sub-documents/C/metadata. This is important when modeling resource permissions. If cascading permissions should not apply in a circumstance, then take the action to split the model. For instance, if metadata access to sub-resources should not be cascaded from documents, then split /documents/✶/metadata to /metadata/✶ when assigning ✶nd checking permissions.
##✶# Fetching user resources
Due to the nature of cascading resources, it is easy to get all the sub-resources. GET /users/{userId}/resources?resourceUri=/documents/ will return all the resources that are sub-resources of documents.
When to create an access record​
Access records should be created or updated whenever there is a change to any user's permission in your system. For any action in your application, an authorization check is performed, and for every resource created, an access record should be generated. This way permissions always stay flexible. Authress is optimally designed to make this very effective and performant. In most cases, there is a direct association between creating a resource in your database and creating or updating an access record.
Creating new application resources​
See more in creating access records
When a new resource is generated in your application, only the service that owns the resource has access by default. To allow the user to access the resource they just created, create an access record. Most frequently a user might already have access to create a resource. For instance, if a user has a role which contains documents:✶ for resource /org/{orgId}/documents, then the user already has access to all documents scoped permissions for every document in the organization. Creating an additional record in this case may not be necessary. Records created through this process are considered resource based records. Each resource in your software would have a corresponding access record.
[Recommended] When creating resource based records, specify the Record ID of a new access record to match the resource being created, and specify the users/resources in this record as the permissions change. This is optional, however, by implementing this, we enable easy management and updates of the users and permissions in these records.
Editing an access record​
Most of the general cases of access record management happen through your application service calls via the Authress SDKs. However, the Authress UI offers a full feature set to create and manage user permissions as well.
User management of permissions​
See more more common authorization patterns in the Authress usage guides
There is a distinction in Authress between having a permission and the ability to Grant that permission to other users. In some cases, they are the same, in other cases, who has access to share a permission should be limited. By default roles have the Allow flag set. user with only Allow will pass authorization checks for the permission, but they will be denied if they try to create or update an access record. This is because Allow does not give them ability to change permissions.
Grant overcomes this challenge, by allowing users with a permission specified for Grant to grant other users a role with the Allow permission. Users with Grant can assign roles and update access records (They still must have access to the access record to change it). Likewise for Allow, a user with Grant cannot grant other users a role with the Grant permission. That is because:
GrantgrantsAllowGrantcannot grantGrant
To assign a role to a user that has either the Allow or Grant permission, the assigner must have Delegate. The Delegate permission allows users to assign all of Allow, Grant, and Delegate to other users via access records. If a user without this access tries to update an access record they will see this error:
In most cases your engineers and your Authress admin will need Delegate, your users may or may not. You can directly call Authress with a user's access token from either your UIs or your services. In these cases, the Authress API will validate permissions on access record changes. Alternatively, you can proxy the calls to Authress using your service. In those cases, if you use your service client access key, then the permissions of the client will be checked and not the user's. As Authress validates the caller's permissions. In the latter case, Allow, Grant, and Delegate will be validated on the service client's permissions not on the user's. To prevent unauthorized changes, the service must perform the validation since Authress won't know about the user. More about this topic can be reviewed in the common authorization patterns knowledge base article.
What are record admin?​
As with all resources, the permissions to change Authress related resources are scoped to Authress:RESOURCE. For access records, editing and assigning permissions is easier by assigning record admins. These admins are not given any permission in the record other than to change the record itself. A record admin must still have necessary Grant and Delegate permissions that in the record. A record admin may change a record, but in a way which would violate their own permissions. Users that have Grant and are not an admin of the record nor have explicit access to change access records, will not be able to change any permissions.
Handling record limits​
Access records are finite in size.
If you have a record that might have more than 100 users, groups, or 100 statements/resources, it will hit the access record capacity limit. Records that reach that limit will be restricted by the Authress API from further additions. When designing a system to use access records compare the cardinality of the size of the resource set with the allowed size of a access record. If the access record is larger by a magnitude, then there is safety in performing the action. If your resource set, user, or group list is unbounded, then unique generation of resource records is required.
Managing records are free with the usage of the API, so the only benefit to limiting resource records to a small set is for ease of manual management, and does not have a performance on Authress or your application. In most cases, using more access records is more performant than only using a few larger ones. (More information is available in the Billing, caching and rate limiting article).