Changing and updating user access permissions

This article discusses how to manage ownership of already existing resources in your platform. It continues from the creating resources guide. Once a resource is created an a user has access that access will change over time.

We might have created access via one of the two preferred strategies:

1. User focused - An access record was created called User:user_001, this record contains all the user's permissions
2. Resource focused - Or an access record was created called Document:doc_001, meaning that this document represents all the permissions for it.

Authress supports a multiple other alternative access record strategies such as [User-Resource] naming the access record User:user_001:Document:doc_001 or permission could have been granted to a group or a generic set of users for a concrete concept.

Remember, an access record is how we grant a user the permission to perform an action on a resource. For the document repository, that might be documents:write on doc_001 for user_001. Here we'll assume we are using a Resource focused access record pattern, as users may have access to many resources, but resources won't have that many users involved.

info

This example uses the Document Repository product as a basis for explaining the technical concepts. Please review the setup before continuing.

Scenario

In our Document Repository, documents have owners. While that seems true on the surface, more appropriate would be to say that:

Every document has at least one user which has ✶ permissions to this specific document.

For this example document doc:001 is currently owned by user_001. At some point user_001 might decide to leave the company or transfer ownership to user_002. To do that in Authress, update the access record Document:doc_001 and replace user user_001 with user_002. Authress will then propagate this access record change and make the necessary permissions updates.

Code example

After checking if the user has access to create the document, we can go and update it, and then return the handle of the document to the user.

Move ownership from user_001 to user_002

import { AuthressClient } from '@authress/sdk';

// Your service client secret can be obtained by navigating to https://authress.io/app/#/settings?focus=clients
// * Edit the Service Client, scroll to Manage secret access keys, and click `Add key`
const serviceClientSecretAccessKey = 'sc_aaa.acc_001.secret';
const authressClient = new AuthressClient({ authressApiUrl: 'https://auth.yourdomain.com' }, serviceClientSecretAccessKey);

const documentId = 'doc_001';
await authressClient.accessRecords.updateRecord(`Document:${documentId}`, {
  name: `Access to document ${documentId}`,
  users: [{ userId: 'user_002' }],
  statements: [{
    roles: ['Admin'],
    resources: [{ resourceUri: `documents/${documentId}` }]
  }]
});

Notice how we are using the Service Client here instead of the user's access token, this is actually not required. We could have used the user's JWT as well since they have might be the admin of the current record.

Alternatively, we could make a change to the record to signify that both user_001 and user_002 should have full access:

Add user_002 as admin of document

await authressClient.accessRecords.updateRecord(`Document:${documentId}`, {
  name: `Access to document ${documentId}`,
  users: [{ userId: 'user_001' }, { userId: 'user_002' }],
  statements: [{
    roles: ['Admin'],
    resources: [{ resourceUri: `documents/${documentId}` }]
  }]
});

Or we assign partial access to user_002:

Add user_002 as Editor of document

await authressClient.accessRecords.updateRecord(`Document:${documentId}`, {
  name: `Access to document ${documentId}`,
  statements: [{
    // Keep user_001's permissions alone
    users: [{ userId: 'user_001' }],
    roles: ['Admin'],
    resources: [{ resourceUri: `documents/${documentId}` }]
  },
  {
    // Add user_002 as an Editor
    users: [{ userId: 'user_002' }],
    roles: ['Editor'],
    resources: [{ resourceUri: `documents/${documentId}` }]
  }]
});

User resource coupling

In this example we were able to easily change the access from one user to another one by updating the relevant access record. This is because Documents in our Document Repository are designed optimally to allow for this. We know that is a user story, so we use Authress to optimize access management changes.

Storing ownership of a record, the users, the creator, and additional information that is related to permissions and access management in Authress makes this easy to manage. For metadata and data changes, these make sense to store in your audit trail. For a list of all changes to any access record, and the history of changes, Authress provides the the event audit stream.

However, in some cases, resources are always directly coupled to one user and never changes. Examples of this could be a artist of a work of art, the owner of a driver's license, membership, or airline tickets. These things the original user will never change, no one can change the artist on the work of art (unless it was misattributed, and in that case, we are changing more than access permissions.) This means that the user should be stored with the record.

If the user attached to a record or resource assignment could ever change, for any resource, ever, then storing this in a durable, configurable, and malleable access record, creates the best long term strategy when using Authress.