| Bug #62241 | Pluggable authentication documentation is not clear/useful | ||
|---|---|---|---|
| Submitted: | 23 Aug 2011 18:48 | Modified: | 1 Nov 2011 19:57 |
| Reporter: | Sveta Smirnova | Email Updates: | |
| Status: | Closed | Impact on me: | |
| Category: | MySQL Server: Documentation | Severity: | S3 (Non-critical) |
| Version: | 5.5.15 | OS: | Any |
| Assigned to: | Paul DuBois | CPU Architecture: | Any |
[23 Aug 2011 18:48]
Sveta Smirnova
[23 Aug 2011 18:50]
Paul DuBois
The guts of all this is probably better handled in the Internals manual.
[23 Aug 2011 19:22]
Sveta Smirnova
Paul, if you mean http://forge.mysql.com/wiki/MySQL_Internals it does not mention pluggable authentication at all.
[24 Aug 2011 14:43]
Paul DuBois
Okay, I'll begin by commenting on some of the remarks in the bug report, and we can go on from there. "it is hard for users to write authentication plugins using only documentation" We don't want it to be harder than necessary to write plugins, but we do expect that people writing code will look at existing code, not just documentation: "In MySQL source distributions, authentication plugin source is located in the plugin/auth directory and can be examined as a guide to writing other authentication plugins." "2. There is no reference for writing authentication plugins." I don't understand that because immediately after this comment the bug report gives the URL to the reference for writing authentication plugins. "does not have example on how to write proxy plugin" Okay, but ... there is no such thing as a "proxy plugin." The only thing a plugin does to enable proxy capability is return a different user name to the server, to indicate the proxied user. See: http://dev.mysql.com/doc/refman/5.5/en/writing-authentication-plugins.html#writing-authent... which says: auth_simple_server_main() is so basic that it does not use the authentication information structure except to set the member that indicates whether a password was received. For a description of this structure's members and how to use them, see the plugin_auth.h header file. For example, a plugin that supports proxy users must return to the server the name of the proxied user (the MySQL user whose privileges the client user should get). To do this, the plugin must set the info->authenticated_as member to the proxied user name. For information about proxying, see Section 5.5.7, “Proxy Users”. "3. Chapter "Proxy Users" at http://dev.mysql.com/doc/refman/5.5/en/proxy-users.html does not have usage examples." Yes, it does. I don't understand what you mean. Examples of what? "2. Add better examples and how-to's." The entire section is an example and how-to. I won't say it cannot be better, but this comment is so vague that it cannot be acted on. Please clarify. "3. Take examples from test named plugin_auth and put them there." The section does have examples from that plugin. Not sure what this is supposed to mean.
[24 Aug 2011 18:01]
Sveta Smirnova
Paul, > "it is hard for users to write authentication plugins using only documentation" > > We don't want it to be harder than necessary to write plugins, but we do expect that people writing code will look at existing code, not just documentation: ... It is hard to argue, lets continue with following > "2. There is no reference for writing authentication plugins." > > I don't understand that because immediately after this comment the bug report gives the URL to the reference for writing authentication plugins. I mean something like for what we have for UDF here: http://dev.mysql.com/doc/refman/5.5/en/adding-udf.html What is required, what is not. Something like "MySQL handles aggregate UDFs as follows: ", but for auth plugins. Link to header file is good, but would be better if manual contains a bit more details. > "does not have example on how to write proxy plugin" > > Okay, but ... there is no such thing as a "proxy plugin." The only thing a plugin does to enable proxy capability is return a different user name to the server, to indicate the proxied user. Correct. But this is what people really want from this feature and would be good to have small example of such a plugin here, not just few words. Feedback from an user who managed to write a plugin without help of blog posts at planet: "when I firstly saw GRANT PROXY statement I spent 1 hour trying to understand how it works until found I must change name in C code". So here is some linking between manual pages problem. > "3. Chapter "Proxy Users" at http://dev.mysql.com/doc/refman/5.5/en/proxy-users.html does not have usage examples." > > Yes, it does. I don't understand what you mean. Examples of what? Something more with expected output. So user can run example and get result described here. Something like deadlock example at http://dev.mysql.com/doc/refman/5.5/en/innodb-lock-modes.html > "2. Add better examples and how-to's." > > The entire section is an example and how-to. I won't say it cannot be better, but this comment is so vague that it cannot be acted on. Please clarify. I mean example should be such what user can use it to create its own from start to end. It is good for UDFs at http://dev.mysql.com/doc/refman/5.5/en/udf-compiling.html, although its example refers to sql/udf_example.c too, but it contains all building instructions and what is required and what is not.
[1 Nov 2011 19:57]
Paul DuBois
Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products. http://dev.mysql.com/doc/refman/5.5/en/writing-authentication-plugins.html#writing-authent...
