From 7d02f7d410598c9a7a75be6c6a9aabaf125f1fab Mon Sep 17 00:00:00 2001 From: Nick Kew Date: Fri, 18 Nov 2005 00:43:41 +0000 Subject: [PATCH] Documentation for mod_authz_dbd git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@345391 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_authz_dbd.html.en | 244 +++++++++++++++++++++++++ docs/manual/mod/mod_authz_dbd.xml | 221 ++++++++++++++++++++++ docs/manual/mod/mod_authz_dbd.xml.meta | 11 ++ 3 files changed, 476 insertions(+) create mode 100644 docs/manual/mod/mod_authz_dbd.html.en create mode 100644 docs/manual/mod/mod_authz_dbd.xml create mode 100644 docs/manual/mod/mod_authz_dbd.xml.meta diff --git a/docs/manual/mod/mod_authz_dbd.html.en b/docs/manual/mod/mod_authz_dbd.html.en new file mode 100644 index 0000000000..47b1335e2f --- /dev/null +++ b/docs/manual/mod/mod_authz_dbd.html.en @@ -0,0 +1,244 @@ + + + +mod_authz_dbd - Apache HTTP Server + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.3

+
+
<-
+
+Apache > HTTP Server > Documentation > Version 2.3 > Modules
+
+

Apache Module mod_authz_dbd

+
+

Available Languages:  en 

+
+ + + + +
Description:Group Authorization and Login using SQL
Status:Extension
Module Identifier:authz_dbd_module
Source File:mod_authz_dbd.c
Compatibility:Available in Apache 2.2 and later
+

Summary

+ +

This module provides authorization capabilities so that + authenticated users can be allowed or denied access to portions + of the web site by group membership. It also provides + database/backend login/logout in conjunction with + mod_authn_dbd.

+
+ +
top
+
+

Database Login

+ +

In addition to the standard authz function of checking group +membership, this module provides database Login/Logout capability. +Specifically, we can maintain a logged in/logged out status in +the database, and control the status via designated URLs (subject +of course to users supplying the necessary credentials).

+

This works by defining two special +Require types: +Require dbd-login and Require dbd-logout. +For usage details, see the configuration example below.

+
top
+
+

Client Login

+ +

In conjunction with server login/logout, we may wish to implement +clientside login/out, for example by setting and unsetting a cookie +or other such token. Although this is not the business of an authz +module, client session management software should be able to tie its +operation in to database login/logout. To support this, +mod_authz_dbd exports an optional hook that will +be run whenever a user successfully logs into or out of the database. +Session management modules can use the hook to implement functions +to start and end a client session.

+
top
+
+

Configuration Example

+ +

+# DBD Configuration
+DBDriver oracle
+DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
+
+DBDMin  4
+DBDKeep 8
+DBDMax  20
+DBDExptime 300
+
+<Directory /usr/www/my.site/team-private/>
+   # authn with mod_authn_dbd
+   AuthType Basic
+   AuthName Team
+   AuthBasicProvider dbd
+   AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s AND login = true"
+
+   # Require dbd-group and authz_dbd implementation
+   Require dbd-group team
+   AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
+
+   # When a user fails to authn/authz, invite them to login
+   ErrorDocument 401 /team-private/login-form.html
+
+   <Files login.html>
+      # Don't require that we're already logged in!
+      AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s"
+
+      # dbd-login action executes a query to set our own state
+      Require dbd-login
+      AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"
+
+      # Return user to referring page (if any) on successful login
+      AuthzDBDLoginToReferer On
+   </Files>
+
+   <Files logout.html>
+      # dbd-logout action executes a query to set our own state
+      Require dbd-logout
+      AuthzDBDQuery "UPDATE authn SET login = false WHERE user = %s"
+   </Files>
+</Directory>
+
+
+
top
+

AuthzDBDAuthoritative Directive

+ + + + + + + +
Description:Sets whether authorization will be passed on to lower level +modules
Syntax:AuthzDBDAuthoritative On|Off
Default:AuthzDBDAuthoritative On
Context:directory
Status:Extension
Module:mod_authz_dbd
+

Setting the AuthzDBDAuthoritative + directive explicitly to Off allows group authorization + to be handled by another authz module if the userID is not + in any authorized dbd-group. If there are any groups + specified, the usual checks will be applied and a failure will + give an Authentication Required reply.

+ +

So if a userID appears in the database of more than one module; + or if a valid Require + directive applies to more than one module; then the first module + will verify the credentials; and no access is passed on; + regardless of the AuthAuthoritative setting.

+ +

A common use for this is in conjunction with one of the + auth providers; such or + mod_authn_file. Whereas this DBD module supplies + the bulk of the user credential checking; a few (administrator) related + accesses fall through to a lower level with a well protected + .htpasswd file.

+ +

By default, control is not passed on and an unknown group + will result in an Authentication Required reply. Not + setting it thus keeps the system secure and forces an NCSA + compliant behaviour.

+ +
+
top
+

AuthzDBDLoginToReferer Directive

+ + + + + + + +
Description:Determines whether to redirect the Client to the Referring +page on successful login or logout if a Referer request +header is present
Syntax:AuthzDBDLoginToReferer On|Off
Default:AuthzDBDLoginToReferer Off
Context:directory
Status:Extension
Module:mod_authz_dbd
+

In conjunction with Require dbd-login or + Require dbd-logout, this provides the option to + redirect the client back to the Referring page (the URL in + the Referer HTTP request header, if present. + When there is no Referer header, + AuthzDBDLoginToReferer On will be ignored.

+ +
+
top
+

AuthzDBDQuery Directive

+ + + + + + +
Description:Specify the SQL Query for the required operation
Syntax:AuthzDBDQuery SQL-Query
Context:directory
Status:Extension
Module:mod_authz_dbd
+

The AuthzDBDQuery specifies an SQL + query to run. The purpose of the query depends on the + Require directive in + effect.

+
    +
  • With Require dbd-group, it specifies a query + to look up groups for the current user. This is the standard + functionality of other authz modules such as + mod_authz_file and mod_authz_dbm. + In this case it will typically take the form
    + AuthzDBDQuery "SELECT group FROM groups WHERE user= %s" +
    • +
  • With Require dbd-login or Require dbd-logout, + it will never deny access, but will instead execute an SQL Query + designed to log the user (who must already be authenticated with + mod_authn_dbd) in or out. Such a query will + typically take the form
    + AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s" +
    • +
+ +
+
top
+

AuthzDBDRedirectQuery Directive

+ + + + + + +
Description:Specify a query to look up a login page for the user
Syntax:AuthzDBDRedirectQuery SQL-Query
Context:directory
Status:Extension
Module:mod_authz_dbd
+

Specifies an optional query to use after successful login + (or logout) to redirect the user to a page, which may be + specific to the user. Such a query will take the form
+ AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s" +

+

Note that AuthzDBDLoginToReferer takes + precedence if both are set.

+ +
+
+
+

Available Languages:  en 

+
+ diff --git a/docs/manual/mod/mod_authz_dbd.xml b/docs/manual/mod/mod_authz_dbd.xml new file mode 100644 index 0000000000..ce0b05fba3 --- /dev/null +++ b/docs/manual/mod/mod_authz_dbd.xml @@ -0,0 +1,221 @@ + + + + + + + + + +mod_authz_dbd +Group Authorization and Login using SQL +Extension +mod_authz_dbd.c +authz_dbd_module +Available in Apache 2.2 and later + + +

This module provides authorization capabilities so that + authenticated users can be allowed or denied access to portions + of the web site by group membership. It also provides + database/backend login/logout in conjunction with + mod_authn_dbd.

+ + +Require +Satisfy +DBDriver +DBDParams + +
+Database Login +

In addition to the standard authz function of checking group +membership, this module provides database Login/Logout capability. +Specifically, we can maintain a logged in/logged out status in +the database, and control the status via designated URLs (subject +of course to users supplying the necessary credentials).

+

This works by defining two special +Require types: +Require dbd-login and Require dbd-logout. +For usage details, see the configuration example below.

+
+ +
+Client Login +

In conjunction with server login/logout, we may wish to implement +clientside login/out, for example by setting and unsetting a cookie +or other such token. Although this is not the business of an authz +module, client session management software should be able to tie its +operation in to database login/logout. To support this, +mod_authz_dbd exports an optional hook that will +be run whenever a user successfully logs into or out of the database. +Session management modules can use the hook to implement functions +to start and end a client session.

+
+ +
+Configuration Example +

+# DBD Configuration
+DBDriver oracle
+DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
+
+DBDMin  4
+DBDKeep 8
+DBDMax  20
+DBDExptime 300
+
+<Directory /usr/www/my.site/team-private/>
+   # authn with mod_authn_dbd
+   AuthType Basic
+   AuthName Team
+   AuthBasicProvider dbd
+   AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s AND login = true"
+
+   # Require dbd-group and authz_dbd implementation
+   Require dbd-group team
+   AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
+
+   # When a user fails to authn/authz, invite them to login
+   ErrorDocument 401 /team-private/login-form.html
+
+   <Files login.html>
+      # Don't require that we're already logged in!
+      AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s"
+
+      # dbd-login action executes a query to set our own state
+      Require dbd-login
+      AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"
+
+      # Return user to referring page (if any) on successful login
+      AuthzDBDLoginToReferer On
+   </Files>
+
+   <Files logout.html>
+      # dbd-logout action executes a query to set our own state
+      Require dbd-logout
+      AuthzDBDQuery "UPDATE authn SET login = false WHERE user = %s"
+   </Files>
+</Directory>
+
+ +
+ + +AuthzDBDQuery +Specify the SQL Query for the required operation +AuthzDBDQuery SQL-Query +directory + + +

The AuthzDBDQuery specifies an SQL + query to run. The purpose of the query depends on the + Require directive in + effect.

+
    +
  • With Require dbd-group, it specifies a query + to look up groups for the current user. This is the standard + functionality of other authz modules such as + mod_authz_file and mod_authz_dbm. + In this case it will typically take the form
    + AuthzDBDQuery "SELECT group FROM groups WHERE user= %s" +
    • +
  • With Require dbd-login or Require dbd-logout, + it will never deny access, but will instead execute an SQL Query + designed to log the user (who must already be authenticated with + mod_authn_dbd) in or out. Such a query will + typically take the form
    + AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s" +
    • +
+ + + + +AuthzDBDRedirectQuery +Specify a query to look up a login page for the user +AuthzDBDRedirectQuery SQL-Query +directory + + +

Specifies an optional query to use after successful login + (or logout) to redirect the user to a page, which may be + specific to the user. Such a query will take the form
+ AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s" +

+

Note that AuthzDBDLoginToReferer takes + precedence if both are set.

+ + + + +AuthzDBDLoginToReferer +Determines whether to redirect the Client to the Referring +page on successful login or logout if a Referer request +header is present +AuthzDBDLoginToReferer On|Off +AuthzDBDLoginToReferer Off +directory + + +

In conjunction with Require dbd-login or + Require dbd-logout, this provides the option to + redirect the client back to the Referring page (the URL in + the Referer HTTP request header, if present. + When there is no Referer header, + AuthzDBDLoginToReferer On will be ignored.

+ + + + +AuthzDBDAuthoritative +Sets whether authorization will be passed on to lower level +modules +AuthzDBDAuthoritative On|Off +AuthzDBDAuthoritative On +directory + + +

Setting the AuthzDBDAuthoritative + directive explicitly to Off allows group authorization + to be handled by another authz module if the userID is not + in any authorized dbd-group. If there are any groups + specified, the usual checks will be applied and a failure will + give an Authentication Required reply.

+ +

So if a userID appears in the database of more than one module; + or if a valid Require + directive applies to more than one module; then the first module + will verify the credentials; and no access is passed on; + regardless of the AuthAuthoritative setting.

+ +

A common use for this is in conjunction with one of the + auth providers; such or + mod_authn_file. Whereas this DBD module supplies + the bulk of the user credential checking; a few (administrator) related + accesses fall through to a lower level with a well protected + .htpasswd file.

+ +

By default, control is not passed on and an unknown group + will result in an Authentication Required reply. Not + setting it thus keeps the system secure and forces an NCSA + compliant behaviour.

+ + + + diff --git a/docs/manual/mod/mod_authz_dbd.xml.meta b/docs/manual/mod/mod_authz_dbd.xml.meta new file mode 100644 index 0000000000..97769e16f9 --- /dev/null +++ b/docs/manual/mod/mod_authz_dbd.xml.meta @@ -0,0 +1,11 @@ + + + + mod_authz_dbd + /mod/ + .. + + + en + + -- 2.50.0