Proposal for policy store specification

[ossdhaval]

Rendered

[emina]

Note that policy evaluation is independent of schemas in Cedar. That is, you don't need any schema at all to evaluate policies. You only need schemas to validate or analyze policies---or, if you are (optionally) using schema-based entity parsing, to parse entities.

So, I think we need to rephrase the motivation here to clarify this: there are no required dependencies on schemas at authorization (run) time.

[nynymike]

Yes, we are doing "schema-based entity parsing" in the Cedarling based on the rules for a trusted issuer, as mentioned in the docs here.

[Swolebrain]

Aren't the action groups specified in the schema (if any exist) necessary for policy evaluation as well?

[cdisselkoen]

You can pass them in entities if you do not pass a schema. (And if you don't have action groups, I believe you don't need to pass them in either entities or schema)

[emina]

The alternative is to maintain status quo and not provide a policy store specification as part of Cedar.

[philhassey]

I'm in favor of not specifying something at this point. There's a lot of things like unique hash key and issuer_id that seem pretty bespoke to a specific implementation. I'm not sure I see the general utility of this?

[nynymike]

The important part of the spec is to provide a way to bind policies and schema. At Janssen Project, we need to bind these two things and version them as part of the cryptographic chain of custody. We also want to show Cedar PDP interoperability--i.e. a policy store that runs on the Cedarling can run on AVP.

The less important part of the RFC is to provide a way to map issuers and default_entities. AVP does have a way to trust issuers, and it would be nice to have alignment on how we specify this. It's not rocket science. We expected some pushback here (for example, using regular expressions to map string claims to multi-property cedar entities). Our hope was that making some fields "optional" might make them acceptable.

Regarding issuer_id, if you have n number of issuers, you need a key for each issuer? Just like we have a key for each policy, and each policy store. If a unique hash key is not a good way to do it, we're open to other suggestions. You really just need non-collision here, so we could be less proscriptive.

[patjakdev]

My feedback is that I don't really understand why the community needs an authoritative specification for the "policy store" concept. The specification you've created seems fine for your specific use case, but I don't really see a need for the Cedar team to dictate (and maintain into the future) such a specification.

Are you looking to interoperate with policy stores generated by third parties or something?

[Swolebrain]

There's one alternative I've outlined above. In general, alternatives are always applicable. For instance with the alternative I outlined, we make it more difficult to cryptographically sign the state of a particular policy store, but we can support more use cases. Another alternative is to specify the cedar schema in a way that's driven by the API spec. It can be versioned and signed in that way. We have a reference implementation for how an OpenAPI spec can be made to express a cedar schema here: https://github.com/cedar-policy/cedar-authorization

Regarding the mapping of issuers, I believe what Phil meant is that we have oidc hardcoded into this spec without a way to specify other types of identity sources, like SAML or any future ones.

[emina]

Thanks for the RFC! Sounds like an interesting proposal to me. I'd be curious to hear from others who are building their own Cedar policy stores, and if this proposal would fit their needs.

[RoyalCookie]

There are no apparent drawbacks to creating this specification.

Apps using Cedar can choose not to adopt this specification

I don't think this is really accurate, while it's true that applications can choose not to implement a Policy Store.
By creating an official RFC for the Policy Store concept effectively establishes a standard that applications would need to follow if they want to export or communicate Policy Stores to external applications or third-party tools in the Cedar ecosystem.
Which hugely expands Cedar's scope beyond policy language specifications into defining inter-application communication.

I think having such a specification could be very usefull if done correctly so early, but it's a huge scope increase that needs to be considered as a part of this RFC.

[RoyalCookie]

I think attempting to defined all these new concepts in the initial RFC might be a mistake, I'd expect some pushback to simply introducing the Policy Store concept to Cedar.

But I think every AVP/OIDC/OAuth specific attribute outlined in the RFC requires it's own discussion so it might be more productive to simplify the scope of this RFC.

Limit it specifically to introducing the Policy Store concept where only the core attributes are defined such as description, policy_content, creation_date?, but allows for additional user defined attributes perhaps?

[Swolebrain]

I completely agree we should leave out identity-related portions of the specification for the time being.

There's a tremendous amount of complexity in coming up with a general-enough abstraction to support a majority of oidc providers, due to the fact that they all deviate from the oidc spec in slightly different ways. For example:

• The concept of "groups" is modeled differently. Okta models it as a "Groups" claim that can only be present in identity tokens. Ping models it as a "groups" claim that is present in both identity and access tokens. Cognito models it as a "cognito:groups" claim that can be present in either token. Auth0 models something similar as a "permissions" claim.
• Different levels of support for JWE token encryption
• Different treatments for client_id claim. The one example I can remember is that Auth0 sometimes uses an azp claim (depending on which type of "auth0 application" the token comes from) instead of client_id to represent the client id.
• Can't find the details right now but if my memory doesn't fail me, there's also different formats for some standard claim values (where one idp will want a space-separated string another one might want a string array).

Beyond that, this proposal doesn't leave room to support other identity sources, like for example SAML, or any future specs that might come out (perhaps for MCP's or what not).

[identitymonk]

Especially on the trusted_issuer element. This part is not support by native Cedar SDK. And while it is supported by Amazon Verified Permissions, it is limited to one Trusted Issuer at the moment.

Therefore this, while being forward thinking, is an OP capability that can not be translated in other implementations.

[nynymike]

Regarding trusted_issuers... We are going to refactor this to minimize the suggested metadata... there is too much stuff in here that we don't need in the spec--that's true.

This RFC lists the trusted_issuers feature as a MAY not a MUST (i.e. optional). Don't need it... don't use it. For those PDPs that are already allowing the specification of trusted issuers, it's a nice feature--it can help enterprises bind the security model to the trust model. Sorry to get all philosophical, but at a high level... JWTs = Truth from outside your domain. "Garbage in garbage out" as they say. If you can't trust the data going into your policies, they are worthless. That's why there is so much value tying the policies with the issuers.

I completely agree we should leave out identity-related portions of the specification for the time being.

Identity tokens are just one kind of token, and we anticipated a range of issuers, issuing all kinds of tokens. For example, consider Google platform attestations, FIDO Alliance authenticator attestations, or verifiable credentials. This trusted_issuer section is a conduit for mapping these tokens to Cedar entities so we can make policies about them.

...doesn't leave room to support other identity sources, like for example SAML, or any future specs that might come out (perhaps for MCP's or what not).

Other token formats are possible too, like SAML, X.509, mobile driver license, W3C verifiable credentials carried in a JWT, or whatever. A given ecosystem federation can define schema for whatever tokens they need. OAuth and OpenID tokens have widespread adoption, so we thought it made sense to ship with "batteries included" for these very standard tokens. They also provide a good way to demonstrate the intended design and new token types.

And while it is supported by Amazon Verified Permissions, it is limited to one Trusted Issuer at the moment.

So if we could define the spec in a way that supports AVP's one Trusted Issuer, but open the possibility that we'll need to make policies about more then one issuer... that would be a win right?

Is it really so future looking to say that we may need to write policies about tokens from more then one issuer? I would say we're already seeing these requirements in the AI world.

[Swolebrain]

While I think the idea of standardizing on a policy store format is fantastic, and I thank you for your contribution, I have several objections to this format. I will try to organize them by theme below.

I will use the term builder to refer to people like us, who build applications using Cedar, and use the term end user to refer to the users using those applications.

1. Use case support

There are at least two major use cases that are left out, not possible to support by the format outlined in this proposal: multi-tenancy and dynamic policy stores (as well as use cases which have both attributes). This format is good for IaC-driven policy stores but it is not good for dynamic policy stores.

To summarize, I will use as an example a use case that requires both: dynamic policies and multi-tenancy. Let's say you're a builder working on ClickDown.com, an imaginary productivity app that allows you to manage tasks, create and share docs, manage content, and even live chat with coworkers. You're using Cedar to model the authz model of ClickDown. With Cedar, when building a multitenant app like ClickDown, the best practice is to have one policy store per tenant. This allows for permission isolation and avoids accidental collisions. Since your application is very successful and you market with the freemium model, your app has 80 million users. That makes this JSON file be somewhere north of 2.4 terabytes (assuming 30kb per policy store, which is actually low).

Additionally, each tenant of ClickDown has many end users. Admin end-users of the ClickDown app have the ability to create other users. Since you user Cedar, there's a lot of flexibility in what you can do in your "Create user" flow. You provide your tenant admins with a flow such that they can select all the actions and resources the new user is allowed to act on. One or more cedar policies are created in the backend. So when you create a new user ClickDown::User::"123123", there are associated policies like permit(principal == ClickDown::User::"123123", action...); generated specific to that user. Under this use case (which is common), each tenant will have policy stores that will grow arbitrarily. One tenant by itself might have 100,000 users in it, with 100,000 policies. It's impractical to version the whole policy store when one single policy was created or updated.

2. Format serialization

If a policy store descriptor format is to exist, one of its uses should be to serialize dynamic policy stores for the purposes of disaster recovery. Serializing a multi-gigabyte file in json is needlessly difficult. Since you can't load it all into memory (because you run oom) you need to write a streaming serializer. This needlessly increases the complexity of encoding this format.

It's much easier to compare the git HEAD to HEAD~1 and only deploy the files that were changed.

De-serializing the format to compare it to what's already deployed has similar streaming complications.

3. Support for templates

If a policy store descriptor format is to exist, it should support policy templates and template linked policies.

An alternative

I would recommend that instead of this, the policy store format should:

1. Encompass a single policy store
2. Store units in the most atomic manner possible, so they can be versioned independently and thus deployed independently.

One structure could be like so:

└── root/
    ├── policyStoremetadata.json                          # Export metadata (cedar version, name, description, etc)
    ├── schema.cedarchema                 # Schema definition for the policy store
    ├── static_policies/                       # Directory for standalone policies
    │   ├── policy_1.cedar                     # Individual Cedar policy files, filename should be policy id
    │   ├── policy_2.cedar
    │   └── policy_n.cedar
    ├── templates/                             # Directory for templates and their linked policies
    │   ├── template_1/                      # Folder should be template id
    │   │   ├── template.cedar         
    │   │   ├── link_1.json                    # Batch of template variable combinations representing template linked policies
    │   │   ├── link_2.json                    
    │   │   └── link_n.json
    │   ├── template_2/
    │   │   ├── template.cedar
    │   │   └── link_1.json
    │   └── template_n/
    │       └── template.cedar
    └── manifest.json   

Note there's a manifest.json file which can be used to list all the contents of a policy store. It would end up being something reminiscent of an info.plist file in an iOS app or a progressive web app's manifest.json file. I haven't thought through this in detail, but one pro of having a manifest is that it should be easier to do static analysis validation on the manifest. For example, if the manifest says that the policy store should perform validation at authorization time, then there must be a schema file present, it must be parseable, and all the policies named in the manifest must be validated against the schema.

Also note I've left out identity-related things from this, for reasons detailed below.

[identitymonk]

While I like the idea of including the policies templates also as part of the proposal, I need more details on the use case of the counter proposal to be able to support this idea more.

As is it seems the counter proposal defeats the initial purpose of the OP.

[Swolebrain]

The idea is that many customers have realized that you don't need token claims to model "Roles" any more and rather you can have policy templates as proxies for roles. Then when you want to assign a "role" to a particular user, you just instantiate the template (in AVP parlance, you create a "Template linked policy"). Therefore the existence of a template equates to the existence of a role

[nynymike]

I actually quite like this design... I even like the use of templates... for those who don't want it, don't use it. For publication of these policies, we could make a versioned zip file. Which may not work for a multi-tenant application, but it works great for a mobile app or browser app.

[Swolebrain]

Although I agree that versioning is strongly desired, using a single file makes these 3 bulletpoints difficult to support:

• For forensic analysis, under the context of multi-tenancy and dynamic policies, if tenant1 changes one policy, that creates a whole new version of the policyStores file. So tenant 700 sees a different policy store version in audit logs even though they've changed no policies
• If a policy store has a thousand policies and only one policy is changed, now my IAC deployer needs to download the whole policy store, diff it against the file, and change what's necessary to change. That, or put write pressure on the DB re-writing everything. Neither is preferrable over updating only what needs to be updated, which can be accomplished by versioning at a more granular level.
• See above, it's much easier to deploy changes and roll back if you know what specific things changed in each policy store.

[identitymonk]

Based on the OP proposal:

• on 1/:
  • the file for tenant1 will be different from the file from tenant700 from what I read in between the lines. @nynymike can you expand the example to a multi-tenant system example please?
• on 2/:
  • there is still an ability to track from OP proposed format what changed, which policy was updated and through the id of this policy, which object should be updated on the deployment.
  • from OP proposal, I read in between the lines that the policies should not be changed backend side. And if this is happening that should be detected as a Drift to be remediated.

[nynymike]

I don't actually agree that every policy change requires a new policy store version. If you have 700 policies, you edit 50 of them, and then submit a PR for approval, and once approved... it gets released as a new policy store version.

If your app has dynamic policies, then a policy store version won't make sense for you. I think the individual policy version is just as good as long as you have a way to create a chain of custody for the audit log.

We will try to flush out these examples in the revision...

[identitymonk]

While I like the idea of including the policies templates also as part of the proposal, I need more details on the use case of the counter proposal to be able to support this idea more.

As is it seems the counter proposal defeats the initial purpose of the OP.

[identitymonk]

That is good for at Admin time policy definitions but what about the at run time policy definitions? Where do you aim to stores those? in this file?

[identitymonk]

Based on the OP proposal:

• on 1/:
  • the file for tenant1 will be different from the file from tenant700 from what I read in between the lines. @nynymike can you expand the example to a multi-tenant system example please?
• on 2/:
  • there is still an ability to track from OP proposed format what changed, which policy was updated and through the id of this policy, which object should be updated on the deployment.
  • from OP proposal, I read in between the lines that the policies should not be changed backend side. And if this is happening that should be detected as a Drift to be remediated.

[identitymonk]

Should the cedar_version be moved inside each policy_store definition? change of cedar version can have a global impact on the policies declared. While most of the changes should be not breaking this cannot be guaranteed. Therefore different policy stores might have different cedar versions,

[nynymike]

I would personally see each tenant having a different policy store. You would never want one huge policy store with 700 tenants! We'll address these questions in the new draft.

[identitymonk]

In this case, is preferable to create a shared policy store or to create a reusable bundle of policies referenced into multiple dedicated policy stores?
I still find one application having to talk to multiple policy stores (the common / shared one and their own / specific one) complex as it requires:

• N (for N the number of authoritative policy stores) authorization requests
• a logic of fall back based on the N-1 authorization request result

[nynymike]

This text does not say that an application would have more than one policy store--this can never happen. It says an organization can have multiple policy stores. And there can be ways to re-use policies--which might re-appear in different policy stores.

[identitymonk]

CEDAR is Cedar. Cedar is not an acronym

[nynymike]

@identitymonk ... Regarding your below hesitation about the trusted issuer metadata... as you say, AVP does support specifying at least one IDP. That's not surprising--authentication standards make authz a lot more useful.

Leaving out the trusted issuer part would prevent interoperability with AVP, which is one of the main goals of this spec. As the Trusted Issuer metadata is a MAY not a MUST, it's ok if all vendors don't support all the features. This is the case with most standards.

But to the extent that we can get agreement on even a subset, that enables interoperability.

[identitymonk]

Especially on the trusted_issuer element. This part is not support by native Cedar SDK. And while it is supported by Amazon Verified Permissions, it is limited to one Trusted Issuer at the moment.

Therefore this, while being forward thinking, is an OP capability that can not be translated in other implementations.

[ossdhaval]

Thank you everyone for your time and input. We have revised the RFC to address the comments. Please follow the link in the PR description to read the updated version.

Major changes

• Moving from a single JSON file structure to a developer-friendly directory format. For suggesting this idea, @Swolebrain has been added as a contributor. :-)
• Each policy, template, and entity is stored as an individual, human-readable file. No base64-encoded strings. Greatly improving version control, IDE support, and collaborative workflows
• Design allows for multiple trusted issuers
• For deployment or distribution, the proposal introduces a standardized .cjar archive format that preserves the structured directory
• The RFC details file conventions, extensible metadata, and open questions while explicitly outlining drawbacks and alternatives

And more.

Looking forward to your inputs on the revised RFC.

[benkehoe]

I'm struggling with why this makes sense to include as part of Cedar proper.

policies are targeted to a specific schema

This might be addressable with a much more narrow proposal, like a well-known policy annotation for linking the policy to a schema version.

In the audit logs to create a cryptographic chain of custody, it's critical to know the exact version of the policies and the schema used at evaluation time. For example, when using schema-based entity parsing.

This is a very use case-specific assumption, that the policies as collected and schema are accessed via a consistent snapshot for authorization decisions, and that schema is used at authorization time. Cedar itself does not define either of these things.

The rest of the motivation deals with interoperability of authorization systems that are built using Cedar, as opposed to the interoperability of Cedar itself. It doesn't make sense to me, for example, that Cedar would define a format that includes trusted issuers, which are not represented anywhere within Cedar itself.

My take here is that a better path might be establishing a separate effort (within or alongside the Cedar project) to define (optional) standards for authorization systems built on top of Cedar. A policy store spec is one aspect. Another could be, for example, a standardized way to provide entities in a call to an AuthZEN-compliant authorization endpoint. Another would be the transmission of entity slices, which is explicitly left out of the proposal in RFC74.

[blubben]

This is roughly where I'm landing as well. I do think a standard directory structure could be useful, for instance, enabling more powerful and consistent IDE experiences (which know how to find the schema and policies.) But I worry the current proposal won't work at scale--when there are many policies and entities not necessarily collocated.

My take here is that a better path might be establishing a separate effort (within or alongside the Cedar project) to define (optional) standards for authorization systems built on top of Cedar.

I like this idea.

[nynymike]

Why does Java have "jar" files--that's also technically a deployment issue. Why does SAML define "metadata" -- also just a deployment issue? It was suggested to me to go this route because I'm not sure if another route exists.

[benkehoe]

This doesn't make sense to me. You need all the entities in order to fully know what authorization decisions would be made with a particular policy store snapshot. Knowing the "default" entities doesn't tell you anything, and could be misleading if those entities were modified after being loaded. This feels less like a definitive model for a policy store and more like capturing particular authorization systems' features.

If support for entities is desired, it should support large volumes of entities, potentially captured separately and referenced in some way here.

[nynymike]

Each entity would have it's own JSON file. I guess you could put a lot of entities here, but that wasn't the intention--a feature to define some basics about this policy store's ecosystem. The Cedarling converts tokens into entities, so it's implicit that there are add'l runtime entities.

The origin of this feature is that we've been working to upgrade the Gluu Flex AdminUI to use Cedar policies (it's a React Application with a Node API backend). Supporting default_entities was by far the easiest solution to model the role:capability mapping in our application, although there were some other awkward workarounds like sending this info in a JWT, but that reduced policy readability. You can also see the design document for the Cedarling in JanssenProject/jans#11870

[benkehoe]

My point is that this is presented as a cryptographically-verified snapshot of a policy store, but it explicitly does not include all entities, so it's not a true snapshot of entities, and the entities it does include can be mutated from the state given here, so it's not even a cryptographically-verified snapshot of those entities.

I would say default_entities should not be part of the Cedar definition of a policy store (if we have one, which as I say in my other comment I am skeptical we should), but that you probably need to support application-specific extensions as part of this spec.

[nynymike]

Ok, hence the default_ part of the claim :-)

[blubben]

I'd suggest making the schema a subdirectory of its own. It can be convenient to break a schema up by namespace (and sharing schema fragments across projects.)

[nynymike]

Personally, my inclincation was always to have multiple schema files. Frankly, it's one of the most frustrating things about Cedar. In the days of LDAP servers, we had a schema folder, and we would drop in all our default, enterprise, and third party schema. However, LDAP had a clear way to re-use schema--one objectclass could extend another objectclass. So there was a clear way to reference a schema without incorporating it into your own schema files. In Cedar, this is not possible.

I guess you could union all the schema files into one big schema. That would require some checking to prevent namespace collissions or duplication. Probably, it would be best to validate the schema before you make the policy store. And at that point, why do we need multiple files in the policy store itself? Also, when running validation tools, it's easier to have one schema for a set of policies.

So our net takeaway was that nothing stops you from having n number of schema files in your repo. But when you put them together and render your policy store--which is made for consumption by a PDP--you might as well just render one final schema file which proves that it all works together, and is less ambiguous about decisions regarding duplication or collissions.

[ossdhaval]

Hello everyone,

This RFC has been updated to address the feedback comments.

Highlight of the changes:

• Introduced the new manifest.json file that provides an inventory of all files in the policy store for validation and integrity checking
• Added samples to cover action groups
• Expanded details on Default entities
• Added JSON Schema for trusted issuers and entity files

Please share your views for the updated RFC.

[nynymike]

We made some changes to address the feedback, like simplifying the trusted_issuer metadata a little and adding another example to the default_entity section. I hope we can make progress on this RFC soon.

[nynymike]

https://aws.amazon.com/blogs/aws/amazon-bedrock-agentcore-adds-quality-evaluations-and-policy-controls-for-deploying-trusted-ai-agents/

Governance needs to be interoperable. While CNCF community contributors like Amazon are developing interesting services, their claims to audit and compliance teams are hard to accomplish without specific versioned policies. We need to know what version of policy is in the execution environment, and how it got there. And we need continuous evaluation according to an assessment procedure, without which, the policy is merely a recomendation. Lack of a versionable binary like this makes Cedar impossible to govern in an interoperable way.

[Swolebrain]

When I think of this format I naturally think of how our cdk/cloudformation support could be made to use it. In cdk/cfn, the way they solve the problem of id's is by virtue of having something that is basically like a "mirror id." In the world of cloudformation, the resource has an id, and cloudformation itself keeps track of how this id (on the cloudformation side) maps to the id on the "real" resource.

The current CDK constructs for verified permissions support either passing a custom cloudformation id, or using the file name as an id. I think this could be the same - the filename (without extension) can be used as the "mirror id" for systems that don't allow specifying an id. And if the system that is storing the policy stores does allow the ability to specify the id, then the filename can also be used as the id.

[Swolebrain]

I think this is not too complicated; it would be something like

{
  policy_template_id: string,
  slots: Record<SlotId, EntityUID>
}

Where EntityUID is {type: string, id: string} and SlotId is just any string. Right now we only support principal and resource slotIds but in the future we might support slots in the when clause.

[Swolebrain]

Optionally adding subdirectories with whatever convention the user wants to use could be a good idea too?

[Swolebrain]

One important unresolved question for me is, once we have this accepted, what do we do with it? Does the Cedar team need to provide APIs to instantiate an authorizer from policy store files? Or do we keep this just as guidance for teams who want to implement their own solutions? What functionality would be necessary or useful to have in a cedar-owned repo to support this policy store definition?

The answer to this question will also help steer my thinking regarding the default_entities. As of now my knee jerk reaction is aligned with some of the other commenters, where the default entities shouldn't be a part of the spec

[cdisselkoen]

Summarizing some discussion at the most recent Cedar maintainers meeting:

1. The maintainers would like to hear more from the RFC authors/sponsors about this RFC and why standardizing this format as part of Cedar itself is valuable. The maintainers see some use cases (e.g., policy store backup) but not a strong motivation for including a specification for this format as part of Cedar itself. This opinion is currently shared by maintainers from various institutions that were present.
2. One maintainer suggested that we should consider a much simpler version of this RFC, e.g., without the checksums (as checksums would be automatically provided by wire protocols, databases, or Git, if this format was transmitted or stored in those ways).
3. At the Cedar library level, policy stores can already be hydrated from files containing Cedar policy syntax or JSON syntax, and the latter also supports templates and template-linked policies (instances) in a single JSON file.

[nynymike]

Duly noted. I'm in the process of proposing a "GovOps" working group at OpenSSF, which could be a home for interoperability related standards.