AuthTrans

AuthTrans stands for Authorization Translation. AuthTrans directives give the server instructions for checking authorization before allowing a client to access resources. AuthTrans directives work in conjunction with PathCheck directives. Generally, an AuthTrans function checks if the user name and password associated with the request are acceptable, but it does not allow or deny access to the request; that is left to a PathCheck function.

The server handles the authorization of client users in two steps:

• AuthTrans validates authorization information sent by the client in the Authorization header.

• PathCheck checks that the authorized user is allowed access to the requested resource.

  The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated, and to provide the flexibility to have resources that record authorization information, but do not require it.

  AuthTrans functions get the user name and password from the headers associated with the request. When a client initially makes a request, the user name and password are unknown so the AuthTrans functions and PathCheck functions work together to reject the request, since they can’t validate the user name and password. When the client receives the rejection, its usual response is to present a dialog box asking for the user name and password to enter the appropriate realm, and then the client submits the request again, this time including the user name and password in the headers.

  If there is more than one AuthTrans directive in obj.conf, each function is executed in order until one succeeds in authorizing the user.

  The following AuthTrans-class functions are described in detail in this section:

• basic-auth calls a custom function to verify user name and password. Optionally determines the user’s group.

• basic-ncsa verifies user name and password against an NCSA-style or system DBM database. Optionally determines the user’s group.

• get-sslid 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.

• match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Server based upon the results by setting values for specified variables.

• qos-handler handles the current quality of service statistics.

• set-variable enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.

basic-auth

Applicable in AuthTrans-class directives.

The basic-auth function calls a custom function to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.

This function is usually used in conjunction with the PathCheck-class function require-auth.

Parameters

The following table describes parameters for the basic-auth function.

Examples

In magnus.conf:

Init fn=load-modules shlib=/path/to/mycustomauth.so 
funcs=hardcoded_auth

In obj.conf:

AuthTrans fn=basic-auth auth-type=basic 
userfn=hardcoded_authPathCheck fn=require-auth 
auth-type=basic realm="Marketing Plans"

See Also

require-auth

basic-ncsa

Applicable in AuthTrans-class directives.

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 in conjunction with the PathCheck-class function require-auth.

Parameters

The following table describes parameters for the basic-ncsa function.

Examples

AuthTrans fn=basic-ncsa auth-type=basic 
dbm=/sun/server61/userdb/rs

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"
AuthTrans fn=basic-ncsa auth-type=basic 
userfile=/sun/server61/.htpasswd grpfile=/sun/server61/.grpfile

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"

See Also

require-auth

get-sslid

Applicable in AuthTrans-class directives.

This function is provided for backward compatibility only. The functionality of get-sslid has been incorporated into the standard processing of an SSL connection.

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.

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.

Parameters

The following table describes parameters for the get-sslid function.

match-browser

Applicable in all stage directives.

The match-browser SAF matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Server based upon the results by setting values for specified variables.

Syntax

stage fn="match-browser" browser="string" name="value" [name="value" ...]

Parameters

The following table describes parameter values for the match-browser function.

Example

The following AuthTrans directive instructs Sun Java System Web Server to do as follows when the browser's User-Agent header contains the string Broken or broken. The server will:

• Not send the SSL3 and TLS close_notify packet (see set-variable).

• Not honor requests for HTTP Keep-Alive (see set-variable

• Use the HTTP/1.0 protocol rather than HTTP/1.1 (see set-variable).

AuthTrans fn="match-browser"
                browser="*[Bb]roken*"
                ssl-unclean-shutdown="true"
                keep-alive="disabled"
                http-downgrade="1.0"

See Also

set-variable

qos-handler

Applicable in AuthTrans-class directives.

The qos-handler function examines the current quality of service statistics for the virtual server, virtual server class, and global server, logs the statistics, and enforces the QOS parameters by returning an error. This must be the first AuthTrans function configured in the default object in order to work properly.

The code for this SAF is one of the examples provided in the Sun Java System Web Server 6.1 NSAPI Programmer’s Guide.

For more information, see the Sun Java System Web Server 6.1 SP9 Performance Tuning, Sizing, and Scaling Guide.

Parameters

The following table describes parameters for the qos-handler function.

Example

AuthTrans fn=qos-handler

         

See Also

qos-error

set-variable

Applicable in all stage directives.

The set-variable function enables you to change server settings based upon conditional information in a request. It can also be used to manipulate variables in parameter blocks with the following commands:

• insert-pblock="name=value"

  Adds a new value to the specified pblock.

• set-pblock="name=value"

  Sets a new value in the specified pblock, replacing any existing value(s) with the same name.

• remove-pblock="name"

  Removes all values with the given name from the specified pblock.

For more information about parameter blocks, see the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide.

Syntax

stage fn="set-variable" [{insert|set|remove}-pblock="name=value" ...][name="value" ...]

Parameters

The following table describes parameter values for the set-variable function.

Variables

The following tables lists variables supported by the set-variable SAF.

Examples

• To deny HTTP keep-alive requests for a specific server class (while still honoring keep-alive requests for the other classes), add this AuthTrans directive to the obj.conf for the server class, and set the variable keep-alive to disabled:

  AuthTrans fn="set-variable" keep-alive="disabled"

  To cause that same server class to use HTTP/1.0 while the rest of the server classes use HTTP/1.1, the AuthTrans directive would be:

  AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="true"

• To insert an HTTP header into each response, add a NameTrans directive to obj.conf, using the insert-pblock command and specifying srvhdrs as your Session/Request parameter block.

  For example, to insert the HTTP header P3P, you would add the following line to each request:

  NameTrans fn="set-variable" insert-srvhdrs="P3P"

• To terminate processing a request based upon certain URIs, use a <Client> tag to specify the URIs and an AuthTrans directive that sets the variable abort to true when there is a match. Your <Client> tag would be comparable to the following:

  <Client uri="*(system32|root.exe)*">AuthTrans fn="set-variable" abort="true"</Client>

See Also

match-browser