https://bugs.openldap.org/show_bug.cgi?id=9256
--- Comment #4 from Karl O. Pinc kop@karlpinc.com --- Hi Ondřej,
Thanks for looking over my suggestions.
"depending on the SASL mechanism in use." why not say something like "if authz-regexp remapping is in place".
I really like this idea. Please see the text of the new patch. (I was able to re-write the sentence and eliminate many words.)
Maybe keep the slapd.conf->cn=config changes to a separate commit.
It didn't seem worth having a separate commit which changes only a single word. (Or two words, as "directive" becomes "attribute".) My thought was that a baby-step forward was better than none. On your recommendation I've reverted to using the the slapd.conf terminology. After settling on on some final text with you, I can add a separate commit, if you would like, to move to the cn=config terminology.
In the paragraph "Some internal operations..." not sure such sweeping changes are really needed,
<snip>
I have a lot of thoughts on the specifics of the changes I propose, and would be happy to go through the details if you want to hear. A lot of the details depend on exactly what it is that you (openldap) want to say. I hope that if you want to say something different than what I think you want to say then that will become clear as we write back and forth and I can make changes.
Until then, I've 2 responses, to go with the 2 parts of your comment:
The paragraph is about access requirements for authentication and authorization. As such, it should start with a topic sentence that says so. That right there (seemingly) requires that the existing first and last sentences, 2 out of the 4 in the paragraph, be moved around and re-worded. With that I'm well on my way to making sweeping changes.
<snip>
maybe just saying the default filter equals to objectclass=* if not specified would simplify and clarify that part?
The purpose of the section is to document what privileges on what entries/attributes are required for which operations. To be comprehensive, and concise, attributes (and so forth) must be paired with specific privileges, in the context of an operation. If you don't specify every attribute needing privilege paired with that attribute's required privilege you are leaving things out.
Adding rational and context and background and other things to build a narrative can make the documentation easier to read. But it does not make sense to mention that objectClass is searched on and make the reader reason through on their own what sort of access permissions are needed under what conditions. Requiring the reader to reach their own conclusions, when the correct answer will be the same for every single reader, has little purpose and makes life hard for the reader. At least that's how I see it. SASL is complicated enough as it is.
One of my goals was to keep things brief. If you think it helps to add background about the existence of the default search filter I can do that. It might help if you suggested an edit to work from, if you want to go forward with this.
Another goal was to try to retain the narrative style and as much of the original text as possible. If your concern is that my rewrite adds additional verbiage and is longer than the original paragraph you might, instead, like the following more aggressive edit:
-------<snip>------- Authentication which uses authzID mapping (typically needed for SASL) and authorization using the proxyAuthz control require auth (=x) privileges on: all the attributes present in the search filter of the URI regexp maps (the right-hand side of the authz-regexp directive), or on the objectClass attribute when either direct DN mapping or when the URI contains no explicit search filter; on the entry pseudo-attribute of all the database entries searched; and on the authzTo attribute of the authorizing identity and/or on the authzFrom attribute of the authorized identity. -------<snip>-------
This is shorter than the original and, I believe, completely documents what attributes require what permissions under what conditions.
I kind of like the short version. But I also like the explanation in the original about how the idea is to relax, what would otherwise be more restrictive permissions, to "auth" when authenticating. That's the kind of thing that a narrative helps with. There's an "ah-ha" moment for the reader to give them a bit of satisfaction and an expectation that since they understand this point they will be able to understand the boring more complicated stuff that's coming later in the paragraph.
If you want the short version I'll have to upload another patch; I've left the long version in the patch I'm uploading with this message.
Thanks again.