ListUsers

[aaguiarz]

In the same way we provide a ListObjects endpoint that list all resources for a specific user & relation, We should provide a way to list which users have a specific relationship with a specific resource, for example:

const response = await fgaClient.listUsers({
object: "document:pricing",
relation: "reader",
type: "document"
});

// returns response.users : ["user:jon", "user:maria"]

There's a PR for the RFC here.

[aaguiarz]

@alee792, @mountainerd, @shivaKhat23, @xXAvoraXx

Do you have concrete use cases for when would you use this API?

[alee792]

1. ACL generation, as you've shown above. Although this can be done with an alternative authorization model, our current one is geared towards allowed object lists.
2. Garbage collecting. If I delete an organization, I'd like to look up its member relations and delete those as well. If there are workarounds, do let me know!

[mountainerd]

Absent of an SDK that can do some local evaluation of an auth model, I'd use a capability like that to pull authorized users into memory to evaluate on an API endpoint or as some middleware for local evaluation instead of calling out to the API for the evaluation.

[xXAvoraXx]

I haven't experienced a use case yet, but it looks like the opposite of listobjects.

[velmohan]

@aaguiarz I ended up implementing a similar endpoint for list-users as a solution to the problem I discussed here: https://github.com/orgs/openfga/discussions/196

Basically I have some data sources that do not provide change notifications. These data sources generally represent a fixed type of tuple where ObjectType, Relation and UserType as fixed. To be able to sync these data sources with OpenFGA tuples, I have built a list-users endpoint that will then be used to sync (i.e. delete, add) tuples. It would be great if this is supported in OpenFGA natively.

[kian99]

Stumbled across this thread from #33
In our use case, similar to what was discussed in openfga/openfga#406, I would be using list-users for output to a GUI to understand which users have access to an object. Granted I think for our use case, the UI might evolve in a way where we only return objects that have a direct relation to the resource (using the read method) and then allow users to click and drill down deeper, alleviating the need for list-users.

[seandlg]

We've previously implemented this by exploring the sub-graphs we receive from the expand API. However, since this felt too bleeding edge and results in many network requests, we've reverted to simply using read for the relations of interest (since read doesn't follow userset rewrite rules).

This works fine for now, in particular because we need the direct relation anyways.

Consider the following simplified model:

model
  schema 1.1
type user
       
type org
  relations
    define owner: [user]
    define member: [user] or owner
    define can_delete_org: owner
          
type project
  relations
    define parent: [org]
    define can_manage_project: member from parent

If we want to display all members with access to an organization, we could check for member using the expand API endpoint, or we could read for both owner and member relations. The latter is nicer, since we want to display the concrete role the user has in an organization. As stated in the comment above, as long as we are querying for direct relations, using read is fine.

[willvedd]

Good news all – we've experimentally released the ListUsers API with the v1.5.4-rc1 release candidate! This feature can be enabled by passing the --experimentals enable-list-users flag to the OpenFGA server. Please refer to the ListUsers API docs for more instructions on usage.

We hope you give it a go and provided feedback!

[avinashs433]

@willvedd can you confirm the environmental variable format to enable this through docker compose.

[willvedd]

can you confirm the environmental variable format to enable this through docker compose.

@avinashs433 under services.openfga.environment you'll want to add OPENFGA_EXPERIMENTALS=enable-list-users

[avinashs433]

Thanks. Is there a way to determine if the user is a direct assignee of a role or not ? In order for me to allow unassignment from the administrator role.

Example:
type group relations define administrator: [user] or superadmin from parent

[ian-activeloop]

@avinashs433 would this suffice for you? It's how we're currently pulling direct relations on specific objects to get users for permissions presentation to users:
fga tuple read --object group:group_id --relation admininistrator
That should completely ignore the or superadmin from parent aspect of the relation definition.

[xXAvoraXx]

Why I gave this error ?

this api reference has 2 elements in the array but when I use 2 elements I get the following error. https://openfga.dev/api/service#/Relationship%20Queries/ListUsers

  "user_filters": [
    {
      "type": "user"
    },
    {
      "type": "group",
      "relation": "member"
    }
  ],

{
    "code": "validation_error",
    "message": "invalid ListUsersRequest.UserFilters: value must contain exactly 1 item(s)"
}

[rhamzeh]

Hi @xXAvoraXx, while we designed the API to support an array for future iterations and improvements, currently it requires a single element in the user_filters, anything more or less will return an error