Lack of documentation for role permutations and possibilities

New to keystone and started by creating a VM and running the guide here:

https://docs.openstack.org/devstack/latest/

Saw that keystone was operational and started using the openstack cli tool along with the V3 API page:

https://developer.openstack.org/api-ref/identity/v3/index.html

"Domains¶
A domain is a collection of users, groups, and projects. Each group and project is owned by exactly one domain.

Each domain defines a namespace where certain API-visible name attributes exist, which affects whether those names must be globally unique or unique within that domain. In the Identity API, the uniqueness of these attributes is as follows:

Domain name. Globally unique across all domains.
Role name. Unique within the owning domain.
User name. Unique within the owning domain.
Project name. Unique within the owning domain.
Group name. Unique within the owning domain."

It says Role name unique within a domain. Along with users, projects, and groups it makes sense that when a role is created using the --domain option that it exists within the domain, and can only interact with things from that domain as a full fledged rule. I created users specifying the domain option, and projects specifying the domain option, why not rules as well? When running the openstack cli tool and showing the output of role assignments, it would list the role when running:

openstack role assignment list --user newyorker --names

yet the role is absent when running:

openstack role assignment list --user newyorker --names --effective

I was using the 'effective' option to show which roles were actually in affect, as in, would allow a user to receive a domain or project scoped token. I didn't understand the difference between the two especially since the documentation around effective kept talking about groups and that did not match up with what I was experiencing since groups were not in use.

Through helpful chat mates, kmalloc and lbragstad, they explained what was happening along with the link to: https://specs.openstack.org/openstack/keystone-specs/specs/mitaka/domain-specific-roles.html

There are two different style guides going on between the specs subdomain and the developer subdomain. Not sure if that is intentional, but if I came across the spec in search results I would assume the spec may not be relevant or may be outdated. Nothing can beat the word current at the top of a web page with a change log history as the introduction.... Perhaps link the API call to the spec that created it? That way there is more reading material and less web searching, looking at people's out dated blogs, which I did manage to find that passage a couple of times.

A separate documentation note that caught me by surprise was the removal of LDAP write support. It's the second sentence is this paragraph:

https://docs.openstack.org/keystone/pike/admin/identity-integrate-with-ldap.html

To me integration means a symbiotic relationship, whereas LDAP is really being used as a RO data store.

The confusion compounds since LDAP write support did exist in a previous release and the O'Reilly book contains this line,

"These options also include whether Keystone is able write to LDAP or simply read the LDAP data."

There are not many resources available, especially with the advice of not trusting blogs, and books have this authoritative prestige about them, so surely the book must be right.... it is not.

After contemplating the matter, I understand enterprise organizations would want write access stripped out but there are plenty of new organizations that want to onboard enterprise level number of users immediately, through keystone, since it does all of this other stuff, and I'd rather let keystone manage it all anyway. Let me hook up the keystone_attribute_field to the LDAP_attribute_field, and wow this is neat!

O'Rielly book mentioned in previous comment:

Identity, Authentication, and Access Management in OpenStack
by Henry Nash; Brad Topol; Steve Martinelli
Published by O'Reilly Media, Inc., 2015

It would be great to have better explanations of the advanced role concepts as well as the policy.json file broken down with more examples.

Please feel free to use the information in the presentation that Henry and I did:

https://www.openstack.org/videos/austin-2016/advances-in-keystones-role-based-access-control

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

Reviewed: https://review.openstack.org/575911
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=d054c9a5ac3aeb9a076c1089a2b5645fca0f3d3b
Submitter: Zuul
Branch: master

commit d054c9a5ac3aeb9a076c1089a2b5645fca0f3d3b
Author: Kristi Nikolla <email address hidden>
Date: Sat Jun 16 09:52:23 2018 -0400

    Simple usage docs for implied roles

    Depends-On: I08f785dc9e840da2e16915683eecfe49189c44b3
    Change-Id: I47722a52f590eae1d1b5c6c5ac7f08b5508e9437
    Partial-Bug: #1775094