From 33e8a493a4f8a9a341aa730efb477b1fe6c51ad0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Fri, 9 May 2014 17:57:20 +0200 Subject: [PATCH] Better documentation for authentication modes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - move most of that to the setup section - remove historical notes (like when it was introduced or originally called) - include example scripts in the docs as well Signed-off-by: Michal Čihař --- doc/config.rst | 24 +++++------------------- doc/setup.rst | 36 ++++++++++++++++++++++++++++++------ 2 files changed, 35 insertions(+), 25 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index 9c4773af8a..804d199342 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -345,26 +345,12 @@ Server connection settings * 'config' authentication (``$auth_type = 'config'``) is the plain old way: username and password are stored in :file:`config.inc.php`. - * 'cookie' authentication mode (``$auth_type = 'cookie'``) as - introduced in 2.2.3 allows you to log in as any valid MySQL user with - the help of cookies. Username and password are stored in cookies - during the session and password is deleted when it ends. This can also - allow you to log in in arbitrary server if :config:option:`$cfg['AllowArbitraryServer']` enabled. - * 'http' authentication (was - called 'advanced' in previous versions and can be written also as - 'http') (``$auth_type = 'http';'``) as introduced in 1.3.0 allows you to log in as any + * 'cookie' authentication mode (``$auth_type = 'cookie'``) allows you to + log in as any valid MySQL user with the help of cookies. + * 'http' authentication allows you to log in as any valid MySQL user via HTTP-Auth. - * 'signon' authentication mode (``$auth_type = 'signon'``) as - introduced in 2.10.0 allows you to log in from prepared PHP session - data or using supplied PHP script. This is useful for implementing - single signon from another application. Sample way how to seed session - is in signon example: :file:`examples/signon.php`. There is also - alternative example using OpenID - :file:`examples/openid.php` and example - for scripts based solution - :file:`examples/signon-script.php`. You need - to configure :config:option:`$cfg['Servers'][$i]['SignonSession']` or - :config:option:`$cfg['Servers'][$i]['SignonScript']` and - :config:option:`$cfg['Servers'][$i]['SignonURL']` to use this authentication - method. + * 'signon' authentication mode (``$auth_type = 'signon'``) allows you to + log in from prepared PHP session data or using supplied PHP script. .. seealso:: :ref:`authentication_modes` diff --git a/doc/setup.rst b/doc/setup.rst index 271c4d2630..7f99660537 100644 --- a/doc/setup.rst +++ b/doc/setup.rst @@ -360,10 +360,8 @@ HTTP authentication mode Cookie authentication mode -------------------------- -* You can use this method as a replacement for the :term:`HTTP` authentication - (for example, if you're running :term:`IIS`). -* Obviously, the user must enable cookies in the browser, but this is - now a requirement for all authentication modes. +* Username and password are stored in cookies during the session and password + is deleted when it ends. * With this mode, the user can truly log out of phpMyAdmin and log back in with the same username. * If you want to allow users to enter any hostname to connect (rather than only @@ -378,9 +376,35 @@ Signon authentication mode -------------------------- * This mode is a convenient way of using credentials from another - application to authenticate to phpMyAdmin. + application to authenticate to phpMyAdmin to implement signle signon + solution. * The other application has to store login information into session - data. + data (see :config:option:`$cfg['Servers'][$i]['SignonSession']`) or you + need to implement script to return the credentials (see + :config:option:`$cfg['Servers'][$i]['SignonScript']`). +* When no credentials are available, the user is being redirected to + :config:option:`$cfg['Servers'][$i]['SignonURL']`, where you should handle + the login process. + +The very basic example of saving credentials in a session is available as +:file:`examples/signon.php`: + +.. literalinclude:: ../examples/signon.php + :language: php + +Alternatively you can also use this way to integrate with OpenID as shown +in :file:`examples/openid.php`: + +.. literalinclude:: ../examples/openid.php + :language: php + +If you intend to pass the credentials using some other means than, you have to +implement wrapper in PHP to get that data and set it to +:config:option:`$cfg['Servers'][$i]['SignonScript']`. There is very minimal example +in :file:`examples/signon-script.php`: + +.. literalinclude:: ../examples/signon-script.php + :language: php .. seealso:: :config:option:`$cfg['Servers'][$i]['auth_type']`,