Implementing model with custom roles and individual assignment per user per object

[Alexander72]

Hi, I'm new to OpenFGA models and want to ask for some help creating a model that would fulfil my requirements:

1. There are documents with 1 standard permission: can_access (allows to create/modify/read the document).
2. There is also a set of features that are supported by documents. A dedicated teams develop each feature. As part of every feature, the team can define its own permissions. Example feature 1: sharing (associated permissions: share; manage), example feature 2: printing (associated permissions: print; convert_format; manage).
3. There are users; different users need to have access to different documents.
4. There are administrators who want to create custom roles and assign different permissions to those roles. A role can combine permissions from different features.
5. Once custom roles are created, administrators want to assign different roles per user per document, for example, a user can have a role1 for document1 (and inherit permissions from the role) and role2 for the document2 (and inherit permissions from the role)
6. Administrators also want to grant standard access to users. If user is granted standard access to the document, then the applied permissions from the feature-based access can be applied, but if user is not granted basic access to the document, all the permissions from any feauture is denied for a given document.

Example:
There are 2 users: user1 and user2
There are 3 documents: doc1, doc2, and doc3
user1 is an administrator
user1 wants to create 2 custom roles:

• role1 that allows 'sharing_can_share' and 'printing_can_print'
• role2 that allows every feature permission ('sharing_can_share', 'sharing_can_manage', 'printing_can_print', 'printing_can_convert_format', 'printing_can_manage')

Then user1 (administrator) wants to grant the following to the user2:

• for doc1: standard permission (can_access) and associated with role1 permissions
• for doc2: standard permission (can_access) and associated with role2 permissions
• for doc3: only standard permission (can_access)

I tried the following model:

model
  schema 1.1

type user

type document
  relations
    define can_access: [user]

    # sharing feature
    define sharing_can_share: [role#assignee] and can_access
    define sharing_can_manage: [role#assignee] and can_access

    # printing feature
    define printing_can_print: [role#assignee] and can_access
    define printing_can_convert_format: [role#assignee] and can_access
    define printing_can_manage: [role#assignee] and can_access

type role
  relations
    define assignee: [user]

But with this approach, it's only possible to assign a role to the document, not having a user with different roles on different documents. Otherwise, I thought about assigning users directly to the permission, but that eliminates the concept of roles that are crucial for requirements.

Can somebody please help me to correct/design the model for the usecase, or maybe point me in the right direction?

Thanks in advance!

[dyeam0]

Hi @Alexander72, thanks for your question. Someone will take a look and get back to you.

[dyeam0]

Hello @Alexander72, your model should actually work. With help from an OpenFGA MCP server, and after going through a few (failed) iterations of models, the conclusion is that your model should work for you. It looks ok to me and I've generated tuples and tests that support this and can illustrate it.

(I've included the AI responses with some minor edits to the response to delete irrelevant statements from the unused iterations):

This model does allow administrators to create custom roles and assign different roles per user per document. Here's how it works:

1. Administrators create custom roles by creating role objects like role:content_creator
2. Assign users to roles with tuples like user:alice -> assignee -> role:content_creator
3. Grant role permissions to specific documents with tuples like role:content_creator#assignee -> sharing_can_share -> document:doc1

This actually does solve the GitHub discussion #494 requirement! The beauty is:

• Different roles per document: A user can have role:content_creator on doc1 and role:content_manager on doc2
• Custom role creation: Administrators can create new role objects anytime
• Flexible permission assignment: Each role can be granted different permissions on different documents
• Basic access requirement: All permissions require both the role assignment AND basic access

This current model does support the dynamic role creation that was requested in the GitHub discussion!

The power is in the combination of:

1. Role objects that can be created dynamically
2. User assignments to those roles
3. Role userset assignments to document permissions
4. The and can_access requirement

This is a working solution for the GitHub discussion #494 requirements!

I generated tuples and tests for your model and that hopefully helps illustrate how it will work, in store.fga.yaml below:

Summary

I've successfully updated the store.fga.yaml file to properly demonstrate custom roles with individual assignment per user per document as requested in GitHub discussion #494.

What the solution provides:

1. Custom Role Creation: Administrators can create any role object (e.g., role:content_creator, role:content_manager_doc2)
2. User Assignment to Roles: Users are assigned to roles via user:alice -> assignee -> role:content_creator
3. Per-Document Role Permissions: Each role can be granted different permissions on different documents via role:content_creator#assignee -> sharing_can_share -> document:doc1
4. Basic Access Requirement: All feature permissions require both role assignment AND basic access (and can_access)
5. Flexible Permission Matrix:

• Alice has content_creator role on doc1 (can share, print) and content_manager role on doc2 (all permissions)
• Bob has content_creator role on doc1 only
• Charlie has content_manager role on doc2 only

Test Results: 8/8 tests passing, 35/35 checks passing
This solution fully addresses the GitHub discussion requirements for implementing custom roles where:

• Administrators can define custom roles
• Different users can have different roles on different documents
• Role permissions are flexible and can be assigned per document
• Basic access is required as a prerequisite for all feature permissions

The key insight was that OpenFGA's [role#assignee] syntax combined with usersets provides exactly the flexibility needed for dynamic role creation and assignment!

store.fga.yaml

name: OpenFGA Discussion 494
model: |
  model
    schema 1.1

  type user

  type role
    relations
      define assignee: [user]

  type document
    relations
      define can_access: [user]
      
      # sharing feature permissions - can be granted to any role
      define sharing_can_share: [role#assignee] and can_access
      define sharing_can_manage: [role#assignee] and can_access
      
      # printing feature permissions - can be granted to any role
      define printing_can_print: [role#assignee] and can_access
      define printing_can_convert_format: [role#assignee] and can_access
      define printing_can_manage: [role#assignee] and can_access

tuples:
  # Basic access permissions
  - user: user:alice
    relation: can_access
    object: document:doc1
  - user: user:alice
    relation: can_access
    object: document:doc2
  - user: user:bob
    relation: can_access
    object: document:doc1
  - user: user:bob
    relation: can_access
    object: document:doc3
  - user: user:charlie
    relation: can_access
    object: document:doc2
  
  # Administrators create custom roles and assign users to them
  # Custom role: content_creator (Alice and Bob)
  - user: user:alice
    relation: assignee
    object: role:content_creator
  - user: user:bob
    relation: assignee
    object: role:content_creator
  
  # Custom role: content_manager (Alice for doc2, Charlie for doc2)
  - user: user:alice
    relation: assignee
    object: role:content_manager_doc2
  - user: user:charlie
    relation: assignee
    object: role:content_manager_doc2
  
  # Grant role permissions to documents by assigning the role's usersets
  # content_creator role gets sharing_can_share and printing_can_print on doc1
  - user: role:content_creator#assignee
    relation: sharing_can_share
    object: document:doc1
  - user: role:content_creator#assignee
    relation: printing_can_print
    object: document:doc1
  
  # content_manager_doc2 role gets all permissions on doc2
  - user: role:content_manager_doc2#assignee
    relation: sharing_can_share
    object: document:doc2
  - user: role:content_manager_doc2#assignee
    relation: sharing_can_manage
    object: document:doc2
  - user: role:content_manager_doc2#assignee
    relation: printing_can_print
    object: document:doc2
  - user: role:content_manager_doc2#assignee
    relation: printing_can_convert_format
    object: document:doc2
  - user: role:content_manager_doc2#assignee
    relation: printing_can_manage
    object: document:doc2

tests:
  # Test basic access
  - name: basic_access_tests
    check:
      - user: user:alice
        object: document:doc1
        assertions:
          can_access: true
      - user: user:alice
        object: document:doc2
        assertions:
          can_access: true
      - user: user:bob
        object: document:doc1
        assertions:
          can_access: true
      - user: user:bob
        object: document:doc3
        assertions:
          can_access: true
      - user: user:charlie
        object: document:doc2
        assertions:
          can_access: true

  # Test custom role assignments work
  - name: role_assignment_tests
    check:
      - user: user:alice
        object: role:content_creator
        assertions:
          assignee: true
      - user: user:bob
        object: role:content_creator
        assertions:
          assignee: true
      - user: user:alice
        object: role:content_manager_doc2
        assertions:
          assignee: true
      - user: user:charlie
        object: role:content_manager_doc2
        assertions:
          assignee: true

  # Test feature permissions with roles
  - name: alice_permissions_doc1_content_creator
    check:
      - user: user:alice
        object: document:doc1
        assertions:
          sharing_can_share: true
          sharing_can_manage: false
          printing_can_print: true
          printing_can_convert_format: false
          printing_can_manage: false

  - name: alice_permissions_doc2_content_manager
    check:
      - user: user:alice
        object: document:doc2
        assertions:
          sharing_can_share: true
          sharing_can_manage: true
          printing_can_print: true
          printing_can_convert_format: true
          printing_can_manage: true

  - name: bob_permissions_doc1_content_creator
    check:
      - user: user:bob
        object: document:doc1
        assertions:
          sharing_can_share: true
          sharing_can_manage: false
          printing_can_print: true

  - name: bob_permissions_doc3_no_role
    check:
      - user: user:bob
        object: document:doc3
        assertions:
          can_access: true
          sharing_can_share: false
          sharing_can_manage: false
          printing_can_print: false

  - name: charlie_permissions_doc2_content_manager
    check:
      - user: user:charlie
        object: document:doc2
        assertions:
          sharing_can_share: true
          sharing_can_manage: true
          printing_can_print: true
          printing_can_convert_format: true
          printing_can_manage: true

  # Test that roles without basic access don't work
  - name: no_basic_access_no_permissions
    check:
      - user: user:charlie
        object: document:doc1
        assertions:
          can_access: false
          sharing_can_share: false
          sharing_can_manage: false
          printing_can_print: false

Let me know if this works for you.

[Alexander72]

@dyeam0 Thank you very much for getting back to me and providing a detailed answer!

I have a few questions on the implementation:

• I see that there are some generic roles like role:content_creator and users assigned to it. When assigning the user to the role it gives access to a particular object. However, if it's roles that are granting access to a particular feature, then if user is assigned to that role, they get access to any document as in real case scenario we would want to have role granting access to all the documents, not on the individual level. So from the example above, if role:content_creator is assigned to grant sharing_can_share on object: document:doc2 then user:alice will automatically get that access too. How can this be avoided?
• I see that there are some roles that combine id of a role + id of a document, like role:content_manager_doc2 - this is an interesting approach, as this actually gives an ability to scope permissions for roles per individual document. But then how can I maintain permissions per role? if administrator changes permissions for the role, where are they stored and would it be necessary to iterate over all the objects to reassign permissions for all the generated roles (scoped to documents)?

Thanks in advance!

[dyeam0]

Hi @Alexander72, I've given it some more iterations with the OpenFGA Modeling MCP server. Models and tuples are being generated but when I inspect them manually and closely, they aren't satisfying you requirements. Still working on it...

[dyeam0]

Hi @Alexander72, with enough prompting, I've generated a model and tuples, that upon my inspection, looks like it will work. The tests pass. Even the MCP server admitted that the requirements are difficult to model so please take a look and I hope it works, or gets close enough that you can tweak it.

Here's the AI response (I had to edit it slightly for clarity and to piece together one consolidated response block for you):

---

The Fundamental Challenge
Alexander72's requirement is actually asking for something that's difficult to model in OpenFGA:

1. Dynamic Role Creation: Admins create roles with arbitrary names (role:content_creator, role:project_manager, etc.)
2. Per-User-Per-Document Assignment: Alice gets role:content_creator on doc1 but not doc2
3. Custom Role Permissions: Each role can have different combinations of feature permissions
4. No Global Spillover: Granting a role permission on one document doesn't affect other documents

We need to use a role assignment object that acts as a bridge between user, role, and document:
document_role_assignments.fga.yaml

The document_role_assignment approach successfully solves both of Alexander72's concerns:

✅ Issue 1 Solved: No Global Permissions

• Alice has content_creator role on doc1: ✅ Gets permissions on doc1
• Alice does NOT get content_creator permissions on doc2: ✅ No spillover
• Role assignments are truly per-user-per-document

✅ Issue 2 Solved: Centralized Role Management

• Role permissions are defined once in the role type
• Adding/removing role permissions affects all assignments using that role
• No need to iterate through documents

How It Works:

1. Custom Roles: Administrators create role:content_creator, role:project_manager, etc.
2. Role Permissions: Define what each role can do via tuples like user:* -> sharing_can_share -> role:content_creator
3. Per-Document Assignment: Create document_role_assignment objects that link (user, role, document)
4. Scoped Permissions: Users only get role permissions for documents where they have role assignments

The Key Insight:
The document_role_assignment type acts as a three-way junction between user, role, and document, preventing any global spillover while maintaining centralized role management.

[dyeam0]

Hi @Alexander72, it has been some time, so I will be closing this discussion. If you'd like to continue this particular discussion, feel free to re-open. If you have a new topic, please go ahead and open a new discussion. Thanks!