add new `link` API to `api::PolicySet`

mwhicks1 commented 11 months ago

Describe the feature you'd like to request

The current PolicySet.link API requires the user to provide the template ID, linking environment values, and the ID of the newly linked policy.

To simplify the user experience, we should also provide a link API that doesn't require the user to construct the new policy's ID; instead the ID can be constructed as a function of the template ID and linked environment values, along with a user-provided prefix string. This new ID would be returned back from link.

Concretely, the ID would have the form:

prefix|templateID|bar-separated-linkvalues

Example:

templateID = reader
?principal = User::"Alice"
?resource = Photo::"vacation.jpg"
prefix = photo

yields linked policy ID

photo|reader|User::"Alice"|Photo::"vacation.jpg"

Example:

templateID = admin-owner
?principal = User::"Alice"
prefix = photo

yields linked policy ID

photo|admin-owner|User::"Alice"

One question is whether we can stipulate that the form of the ID is subject to change, i.e., users should not rely on its precise form. That way, if we discovered later that a different format was preferred, we could switch to that.

Describe alternatives you've considered

A reasonable alternative is to do nothing, leaving policy ID construction to the user.

There is a risk that this API will construct an ID that clashes with an existing static policy ID in the PolicySet (we can assure by construction it will not conflict with template-linked policies). As a result, the user will have to deal with the possibility of such an error, which could be awkward. For example, they might need to ensure that static policies never have a prefix that could overlap with the prefix used by template-linked policies. This may or may not be simpler than needing to handle all parts of ID construction.

Additional context

No response

Is this something that you'd be interested in working on?

[X] 👋 I may be able to implement this feature request
[ ] ⚠️ This feature might incur a breaking change

john-h-kastner-aws commented 10 months ago

Thinking about this, I also agree that leaving it as-is would be reasonable, but the API feels unwieldy at the moment.

If we do this, I think we should automatically handle template/policy id collision with the generated id, otherwise collision would still be possible during linking, and we wouldn't be much better than the current API.

Allowing the generated ids to change in the future is also a bit of a problem. Every user will depend on them to the extent that they expect their other ids don't conflict with generated ids.

mwhicks1 commented 10 months ago

I can agree with this statement:

we should automatically handle template/policy id collision with the generated id,

But not sure about this one:

Allowing the generated ids to change in the future is also a bit of a problem.

The second statement implies that the automatic handling of ID collision must also be spelled out. That seems onerous. Moreover:

Every user will depend on them to the extent that they expect their other ids don't conflict with generated ids.

If we use the prescribed form in the issue, then users can simply ensure that their static policy IDs never start with the given prefix of the auto-generated ID (leaving the rest of the generation process open to change). Isn't that enough?

cedar-policy / cedar