LookupSubjects API

[josephschorr]

The Lookup Watch API Proposal includes the addition of the "reachability" APIs, which allow a caller to query the data-driven shape of the permissions graph.

One of the APIs proposed is LookupSubjects which would act as a filtered, streaming form of ExpandPermission, but across an entire object type:

message LookupSubjectsRequest {
    Consistency consistency = 1;

    ObjectReference resource = 2;
    string optional_permission = 3;

    string optional_subject_type = 4;
    string optional_subject_relation = 5;
}

message LookupSubjectsResponse {
    Relationship found_relationship = 1;
    ZedToken found_at = 2;
}

All fields on the request besides consistency and resource would be optional, in which case all subjects (of all kinds) would be find for the specified resource.

Open Questions

1. Should the LookupSubjectsResponse contain the path of all relations/permissions that were traversed to reach a subject? This could be very useful in building permissions panels or auditing systems.
2. Should optional_subject_type (and relation) be repeated, to allow filtering to a set of allowed types, instead of a single type?
3. Should optional_permission be repeated, to allow filtering to a set of allowed permissions/relations?

[jonwhitty]

Should the LookupSubjectsResponse contain the path of all relations/permissions that were traversed to reach a subject? This could be very useful in building permissions panels or auditing systems.

I think the client should be able to selectively choose to return the path of all relations/permissions. I like the idea of using a FieldMask here to allow the client to specify to include it or not.

Should optional_subject_type (and relation) be repeated, to allow filtering to a set of allowed types, instead of a single type?

I think so, yeah. This just gives the client more flexibility to be selective about what they want to lookup. This could be really useful if the client only cares about certain subject types or relations. It also doesn't restrict the ability to lookup all, we'll just want to make sure we account for that case. To me it makes sense that if you omit this repeated field then that indicates you want to lookup all subjects for any subject type (and relation).

Should optional_permission be repeated, to allow filtering to a set of allowed permissions/relations?

Yes, I believe this would be a good feature. A lot of permission aware external indexes only need to know about 'view' permission. Common cases for this include Reporting or Search features of a platform. Allowing the client to selectively choose what permission/relations they want to lookup the subjects for would be very valuable for that use case. It also doesn't restrict the user from being more generic instead of more specific, so in that regard it's more flexible IMO. If they don't provide a list of optional permissions then we just lookup assuming all permissions.

[josephschorr]

Updated proposal:

message LookupSubjectsRequest {
    Consistency consistency = 1;

    ObjectReference resource = 2;

    repeated string optional_permissions = 3;
    repeated SubjectAndRelation optional_subjects = 4;
}

message SubjectAndRelation {
   string subject_type = 1;
   string optional_subject_relation = 2;
}

message PathEntry {
  ObjectReference expanded_object = 1;
  string expanded_relation = 2;
}

message LookupSubjectsResponse {
    Relationship relationship = 1;
    repeated PathEntry reachability_path_entries = 2;
    ZedToken found_at = 3;
}

[jonwhitty]

@josephschorr do we want the optional_permission and optional_subject to be plural?

message LookupSubjectsRequest {
    Consistency consistency = 1;

    ObjectReference resource = 2;

    repeated string optional_permissions = 3;
    repeated SubjectAndRelation optional_subjects = 4;
}

[josephschorr]

Yes, good point. Updated

[jakedt]

Plan after a recent discussion:

• LookupSubjects becomes the exact inverse of LookupResources in that it
  • Returns all of the subjects that match the subject type of the parent resource
  • Contains no context of how the subject was found
• implementation details:
  • Expand dispatch becomes a streaming API
  • Expand dispatch gets a subject filter for only returning relevant items
  • LookupSubjects uses recursive streaming expand dispatch internally to compute subject set

[gergof]

In our application we need to answer questions like "which users have access to the resource" to know which users should be notified if the resource changes. Currently I'm using the ExpandPermissionTree API and compute the unions/intersections/differences in the application to resolve this. I'm really looking forward to see LookupSubjects API implemented.

[josephschorr]

Done in https://github.com/authzed/spicedb/pull/770