Common guide for policy.json file

[Rushi Agrawal]

Not sure if it is a (wishlist) bug or a feature, but I think it makes sense to provide a common guide for policy.json file. When one googles for it, they just get policy.json file from manuals from different OpenStack projects:

See http://docs.openstack.org/trunk/config-reference/content/section_keystone-policy.json.html
and http://docs.openstack.org/trunk/config-reference/content/section_glance-policy.json.html
and http://docs.openstack.org/trunk/config-reference/content/section_cinder-policy.json.html

These manuals just list out a snip of policy.json file. I think we should provide a short introduction to what the rules and syntax in this file means (optionally also providing simple examples of how to add/change information)

[Rushi Agrawal (rushiagr)]

The only information I can find is only available for grizzly. But that too is incomplete, and requires other modifications too.

[Rushi Agrawal (rushiagr)]

Link for above comment ^ http://docs.openstack.org/grizzly/openstack-compute/admin/content/keystone-concepts.html

[Andreas Jaeger (jaegerandi)]

This is the link you're looking for:

http://docs.openstack.org/admin-guide-cloud/content/keystone-user-management.html

Does this resolve the bug?

[Rushi Agrawal (rushiagr)]

I don't think so, Andreas. The link is still not a full explanation of what is meant by 'project_id:blah', and 'rule:blah'.

[Rushi Agrawal (rushiagr)]

I hope I am supposed to change the status back to 'confirmed'. If I'm wrong and this needs to be done by Andreas, sorry...

[Tom Fifield (fifieldt)]

Marking as "High" - came up as a major issue in ops meetup.

[Tom Fifield (fifieldt)]

some text at http://openstack-in-production.blogspot.com/2015/02/delegation-of-roles.html that was deemed good

[Sean M. Collins (scollins)]

This was recently discussed at the OpenStack Operator's summit

https://etherpad.openstack.org/p/PHL-ops-security

[Bryan D. Payne (bdpayne)]

Adding tag for sec-guide. While we may want to doc this in other areas too, I'd like to track this for the security guide.

[Bernd Bausch (berndbausch)]

I am going to try my luck at a draft.
One aspect for which I have found practically no documentation is the mapping of policy checks to APIs, for example a rule like

    "volume:create": ""

refers to creating a volume, but not all APIs are that obvious. Is there information on this outside of the python code?

[Tom Fifield (fifieldt)]

so far very little I'm afraid Bernd - which is why solving this bug is so needed

[Bernd Bausch (berndbausch)]

I have started writing but need to clarify a number of questions. (Un)fortunately I have a sudden peak in (paying) work, which must have priority right now. There will be more time mid-April.

I will upload what I have in the next 1-2 days and document the questions I have. At that point, I can either leave things as they are or unassign myself (while I prefer to keep this assignment, I don't want to block progress). Is that an acceptable plan?

[Bernd Bausch (berndbausch)]

Open questions:
The only documentation about policy.json I could find is in the python source, in particular example keystone/openstack/common/policy.py (may be in a different location depending on the OpenStack release). A few questions remain though:

1- the structure of a policy check in policy.json is::
      <action> : <condition>
   where <action> is an API or an alias for the right hand condition.
   Q: Are other actions conceivable?

2- some actions look like a hierarchy, e.g.::
      compute_extension:v3:os-access-ips:discoverable
   I don't think I understand that fully.
   What does this mean?

3- while it is fairly obvious which API an action
   corresponds to, it's not always so. Is there
   documentation about this?

4- keystone/openstack/common/policy.py says that
  API attributes can be expressed in this way: *user.id*. I don't see
  this in any of the policy files; are there examples for this?
  What are examples for API attributes?

[Bernd Bausch (berndbausch)]

The Glance developer doc has a nice page on creating policies and on the Glance APIs that can be used in a policy.json file. See http://docs.openstack.org/developer/glance/policies.html. It would be great if similar docs existed for the other parts of OpenStack (granted the Glance API is the smallest and therefore easiest to write about).

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/166853

[Bernd Bausch (berndbausch)]

To be read: http://adam.younglogic.com/2013/11/policy-enforcement-openstack/

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/166853
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=0da1171a82ba952e90205a3a8cee15904f54f2fe
Submitter: Jenkins
Branch: master

commit 0da1171a82ba952e90205a3a8cee15904f54f2fe
Author: Bernd Bausch <email address hidden>
Date: Mon Mar 23 23:17:09 2015 +0900

    A short introduction to the policy.json file

    None of the manuals contains a satisfactory overview of the
    syntax and semantics of policy.json. This description attempts
    to close the gap; it should eventually go to the configuration
    guide.

    The main source is ...keystone/openstack/common/policy.py.

    Change-Id: I87ae3c1be0d602aa05f26c01624f1f7cb9d576e2
    Partial-Bug: #1311067

[Anne Gentle (annegentle)]

Setting to Confirmed since Bryan indicated they want to also incorporate into the Security Guide.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/178957

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/178957
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=683999e929528e94dbd3e6561df88f9736db7e32
Submitter: Jenkins
Branch: master

commit 683999e929528e94dbd3e6561df88f9736db7e32
Author: Bernd Bausch <email address hidden>
Date: Thu Apr 30 03:09:34 2015 +0900

    Amendments to the introduction of policy.json

    This is an amendment of https://review.openstack.org/#/c/166853/,
    after additional information became available.
    Specifically, information about the is_admin flag and a note on
    tweaking policy.json are added, and some points reworded for
    clarity.

    While there is still room for improvement, the bug, previously
    declared as partially fixed, can be closed now.

    Change-Id: Ifd01bc4e367f65d6ce45c54a005bafb660535260
    Closes-Bug: #1311067

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/openstack-manuals 15.0.0 release.