... *Back to [[Book|Administrator's Configuration File Reference#cfr]] [[Topic|Administrator's Configuration File Reference#chap7]]*
h2. {{AuthTrans}}
The {{Authtrans}} directive instructs the server to check for authorization before allowing a client to access resources. For more information, see [{{AuthTrans}}|Flow of Control in obj.conf#auth].
The following {{AuthTrans}}-class functions are described in detail in this section:
* [#{{basic-auth}}]
* [#{{basic-ncsa}}]
* [#{{get-sslid}}]
* [#{{qos-handler}}]
In addition, the following common SAFs are valid for the {{AuthTrans}} directive:
* [{{match-browser}}|Common SAFs across Multiple Directives#saf2]
* [{{set-variable}}|Common SAFs across Multiple Directives#saf8]
h3. {{basic-auth}} {anchor:auth1}
The {{basic-auth}} function verifies the authorization information sent by the client. The {{Authorization}} header is sent as part of the basic server authorization scheme. This function is usually used with the {{PathCheck}}-class function {{require-auth}}.
h4. Parameters
The following table describes parameters for the {{basic-auth}} function.
Table 7-1 {{basic-auth}} Parameters
||Parameter ||Description || |
|{{auth-type}} |Specifies the type of authorization to be used. The values can be {{basic}}, {{digest}}, or {{ssl}}. The default value is {{basic}}. |
|{{userdb}} |(Optional) Specifies the full path and file name of the database to be used for user verification. This parameter will be passed to the user function. | |
| |{{userfn}} |Name of the user custom function to verify authorization. This function must have been previously loaded with {{load-modules}}. It has the same interface as all of the SAFs, but it is called with the user name ({{user}}), password ({{pw}}), user database ({{userdb}}), and group database ({{groupdb}}), if supplied, in the {{pb}} parameter.This function checks the name and password using the database and returns {{REQ_NOACTION}} if they are not valid. It returns {{REQ_PROCEED}} if the name and password are valid. The {{basic-auth}} function will then add {{auth-type}}, {{auth-user}} ({{user}}), {{auth-db}} ({{userdb}}), and {{auth-password}} ({{pw}}, Windows only) to the {{rq->vars pblock}}. For more information on custom functions, Creating Custom Server Application Functions in [Sun Java System Web Server NSAPI Developer's
Guide|http://docs.sun.com/doc/820-6606/abvcu?a=view].
Guide|NSAPI Developer's Guide#Creating Custom Server Application Functions].
| |
|{{groupdb}} |(Optional) Specifies the full path and file name of the user database. This parameter will be passed to the group function. |
|{{groupfn}} |(Optional) Name of the group custom function that must have been previously loaded with {{load-modules}}. It has the same interface as all of the SAFs, but it is called with the user name ({{user}}), password ({{pw}}), user database ({{userdb}}), and group database ({{groupdb}}) in the {{pb}} parameter. This parameter also has access to the {{auth-type}}, {{auth-user}} ({{user}}), {{auth-db}} ({{userdb}}), and {{auth-password}} ({{pw}}, Windows only) parameters in the {{rq->vars pblock.}} The group function determines the group to which the user belongs using the group database, add it to {{rq->vars}} as {{auth-group}}, and return {{REQ_PROCEED}} if found. It returns {{REQ_NOACTION}} if the user’s group is not found. | |
... |{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |
h4. Example
In {{magnus.conf}}:
{code}
Init fn="load-modules" shlib="/path/to/mycustomauth.so" funcs="hardcoded_auth"
{code}
In {{obj.conf}}:
{code}
AuthTrans fn="basic-auth" auth-type="basic" userfn="hardcoded_auth"
PathCheck fn="require-auth" auth-type="basic" realm="Marketing Plans"{code}
h4. See Also
[{{require-auth}}|PathCheck#path13]
h3. {{basic-ncsa}} {anchor:auth2}
The {{basic-ncsa}} function verifies authorization information sent by the client against a database. The {{Authorization}} header is sent as part of the basic server authorization scheme. This function is usually used with the {{PathCheck}}-class function {{require-auth}}.
h4. Parameters
The following table describes parameters for the {{basic-ncsa}} function.
Table 7-2 {{basic-ncsa}} Parameters
||Parameter ||Description ||
|{{auth-type}} |Specifies the type of authorization to be used. The values can be {{basic}}, {{digest}}, or {{ssl}}. The default value is {{basic}}. |
|{{dbm}} |(Optional) Specifies the full path and base file name of the user database in the native format of the server. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to billions of users. If you use this parameter, do not use the {{userfile}} parameter. |
|{{userfile}} |(Optional) Specifies the full path name of the user database in the NCSA-style HTTPD user file format. This format consists of lines using the format _name:password_, where _password_ is encrypted. If you use this parameter, do not use {{dbm}}. |
|{{grpfile}} |(Optional) Specifies the NCSA-style HTTPD group file to be used. Each line of a group file consists of _group_{{:}}_user1 user2 ... userN_ where each user name is separated by spaces. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |
h4. Example
{code}
AuthTrans fn="basic-ncsa" auth-type="basic" dbm="/sun/server7/userdb/rs"
PathCheck fn="require-auth" auth-type="basic" realm="Marketing Plans"
AuthTrans fn="basic-ncsa" auth-type="basic" userfile="/sun/server7/.htpasswd"
grpfile="/sun/server7/.grpfile"
PathCheck fn="require-auth" auth-type="basic" realm="Marketing Plans"
{code}
h4. See Also
[{{require-auth}}|PathCheck#path13]
h3. {{get-sslid}} {anchor:auth3}
The {{get-sslid}} function retrieves a string that is unique to the current SSL session and stores it as the {{ssl-id}} variable in the {{Session->client}} parameter block.
{info:title=Note - }This function is provided for backward compatibility. The functionality of {{get-sslid}} has been incorporated into the standard processing of an SSL connection.
{info}
If the variable {{ssl-id}} is present when a CGI is invoked, it is passed to the CGI as the {{HTTPS_SESSIONID}} environment variable. The {{get-sslid}} function has no parameters and always returns {{REQ_NOACTION}}. It has no effect if SSL is not enabled.
h4. Parameters
The following table describes parameter for the {{get-sslid}} function.
Table 7-3 {{get-sslid}} Parameter
||Parameter ||Description ||
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |
h3. {{qos-handler}} {anchor:auth4}
The {{qos-handler}} function examines the current quality of service (QOS) statistics for a virtual server, logs the statistics, and enforces the QOS parameters by returning an error. This function must be the first {{AuthTrans}} function configured in the {{default}} object.
h4. Parameters
The following table describes parameter for the {{qos-handler}} function.
Table 7-4 {{qos-handler}} Parameter
||Parameter ||Description ||
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |
h4. Example
{code}
AuthTrans fn="qos-handler"
{code}
h4. See Also
[{{qos-error}}|Error#err2] |