<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Authorization Quick Guide\chapter_auth_quick_guide)

<P> WASD offers a comprehensive and versatile authentication and authorization
environment.  A little too comprehensive, often leaving the new administrator
wondering where to begin.  The role of this chapter is to provide a starting
place, especially for sources of authentication, along with some basic
configurations. <REFERENCE>(chapter_authorization) contains a detailed
explanation of all aspects.  All examples here assume a standard installation 
and environment.

<P> Just to clarify. <EMPHASIS>(Authentication\BOLD) is the verification of a
user's identity, usually through username/password credentials.
<EMPHASIS>(Authorization\BOLD) is allowing a certain action to be applied to a
particular path based on that identity.

<HEAD1>(SYSUAF/Identifier Authentication\head_auth_quick_identifier)

<P> This setup allows any active account to authenticate using the local VMS
username and password.  By default not every account may authenticate this
way, only those holding specified VMS rights identifiers.  See
<REFERENCE>(head_auth_identifier).  The examples provided in this section
allows access to the WASD server administration menus, and so may be followed
specifically for that purpose, as well as serve as a general guide.

<LIST>(UNNUMBERED)

<LE> Define the following logical before calling the server startup
procedure.  To make such a definition permanent add it to the system or Web
environment startup procedures.  This logical contains a startup qualifier that
configures the server to allow authentication from the SYSUAF, using VMS rights
identifiers.  See <REFERENCE>(head_auth_policy).

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM HTTPD$STARTUP_SERVER "/SYSUAF=ID"
  $ @<EMPHASIS>(device):[HT_ROOT.LOCAL]STARTUP.COM
<ENDCODE_EXAMPLE>

<P><LE> Decide on an identifier name.  This can be an existing identifier, or
one created for the purpose.  For this example the identifier will be
<QUOTE>(WASD_WEBADMIN).  Any identifier can be created using actions similar to
the following example.

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> ADD /IDENTIFIER WASD_WEBADMIN
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> Modify the authorization configuration file, accessed by the server
using the system logical HTTPD$AUTH, to contain the following.  This allows
full access to the Administration Menu and [.LOCAL] directory (and no world
access).  Additional paths may be added as required, and of course multiple
identifiers may be created and used for multiple realms and paths.

<CODE_EXAMPLE>
  ["Web Admin"=WASD_WEBADMIN=id]
  /httpd/-/admin/* r+w
  /ht_root/local/* r+w
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The identifier must then be granted to those accounts allowed to
authenticate in this way.

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> GRANT /IDENTIFIER WASD_WEBADMIN SYSTEM
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> Using this approach useful discrimination may be exercised.  For
instance, one identifier for Web administrators, another (or others) for
different authentication requirements.

<CODE_EXAMPLE>
  ["Web Admin"=WASD_WEBADMIN=id]
  /ht_root/local/* r+w
  /httpd/-/admin/* r+w
  ["Area Access"=<EMPHASIS>(area-identifier-name)=id]
  /web/area/* r+w ; r
<ENDCODE_EXAMPLE>

<P> Of course the one account may hold multiple identifiers and so may have
access to various areas.

<CODE_EXAMPLE>
  UAF> GRANT /IDENTIFIER WASD_WEBADMIN SYSTEM
  UAF> GRANT /IDENTIFIER <EMPHASIS>(area-identifier-name) SYSTEM
<ENDCODE_EXAMPLE>

<P> Using VMS rights identifiers allows significant granularity in providing
access.

<ENDLIST>

<HEAD>(After Changes\head_auth_quick_after_changes)

<P> If the HTTPD$AUTH configuration file is changed, or rights identifiers are
granted or revoked from accounts, the server should be directed to reload the
file and purge any cached authorization information.

<CODE_EXAMPLE>
  $ HTTPD/DO=AUTH=LOAD
  $ HTTPD/DO=AUTH=PURGE
<ENDCODE_EXAMPLE>

<HEAD1>(SYSUAF Authentication\head_auth_quick_sysuaf)

<P> <EMPHASIS>(The use of rights identifiers (described above) is strongly
recommended.\BOLD)  However if this is impractical for some reason, an
alternative setup allows <UNDERLINE>(any active, non-privileged account) to
authenticate using the server system VMS username and password.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> Define the following logical before calling the server startup
procedure.  This logical configures the server to allow authentication from the
SYSUAF.  See <REFERENCE>(head_auth_policy).

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM HTTPD$STARTUP_SERVER "/SYSUAF"
  $ @<EMPHASIS>(device):[HT_ROOT.LOCAL]STARTUP.COM
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> Modify the authorization configuration file, accessed by the server
using the system logical HTTPD$AUTH, to contain the following.  This allows
full access to the Administration Menu and [.LOCAL] directory (and no world
access at all).  Additional paths may be configured as required.

<CODE_EXAMPLE>
  ["Whatever you want to call it!"=VMS]
  /web/area/* r+w
<ENDCODE_EXAMPLE>

<P> Update access (read+write) may be provided to the authorized and read-only
access to the world using syntax similar to the following example.  This
applies to all authentication sources.

<CODE_EXAMPLE>
  /web/area/* r+w ; r
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> With no discrimination on which accounts can and cannot authenticate
using this setup additional controls on what can be accessed must be supplied. 
This is done using either restriction lists (see
<REFERENCE>(head_auth_access_restrict))

<CODE_EXAMPLE>
  ["Realm Name"=VMS]
  /web/area1/* r+w,~username1,~username2
  /web/area2/* r+w,#host1,#host2,~username3
<ENDCODE_EXAMPLE>

<P> or using access groups (see <REFERENCE>(head_auth_quick_groups))

<CODE_EXAMPLE>
  ["Realm Name"=VMS;<EMPHASIS>(list_name1)=list]
  /web/area1/* r+w ; 
  ["Realm Name"=VMS;<EMPHASIS>(list_name2)=list]
  /web/area2/* r+w ; r
<ENDCODE_EXAMPLE>

<ENDLIST>

<NOTE>
To also allow privileged accounts to authenticate via the SYSUAF with this
configuration change the logical definition as follows.

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM HTTPD$STARTUP_SERVER "/SYSUAF=RELAXED"
<ENDCODE_EXAMPLE>

<P> <EMPHASIS>(This is not a recommended configuration\BOLD).
<LINE>
Using VMS identifiers is a far better solution.  See previous section.
<ENDNOTE>

<HEAD1>(Other Authentication\head_auth_quick_other)

<P> Other sources of authentication are available, either by themselves or used
in the same configuration file (different realms and paths) as those already
discussed.  See <REFERENCE>(head_auth_sources).  Non-SYSUAF sources do not
require any startup qualifier to be enabled.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Simple lists\BOLD) contain usernames and unencrypted
passwords.  These are plain-text files, created and modified using any desired
editor.

<CODE_EXAMPLE>
  ["Whatever you want to call it!"=<EMPHASIS>(list-name)=list]
  /web/area/* r+w ; r
<ENDCODE_EXAMPLE>

<P> This is a <UNDERLINE>(very) simple arrangement, with little inherent
security.  Lists are more useful when grouping names together for specifying
which group may do what to where.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTA databases\BOLD) are WASD-specific, binary repositories
of usernames, encrypted passwords, capabilities, user and other detail.

<CODE_EXAMPLE>
  ["Whatever you want to call it!"=<EMPHASIS>(HTA-database-name)=HTA]
  /web/area/* r+w ; r
<ENDCODE_EXAMPLE>

<P> These databases may be administered using the Administration Menu, are
quite secure and versatile.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(External agents\BOLD) are authentication and authorization
scripts executed on demand, under the control-of but external to the server. 
It is possible for a site to write it's own, custom authorization agent.

<CODE_EXAMPLE>
  ["Whatever you want to call it!"=<EMPHASIS>(agent-name)=agent]
  /web/area/* r+w ; r
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD1>(Read and Write Groupings\head_auth_quick_groups)

<P> WASD allows separate sources for groups of usernames to control read and
write access in a particular realm.  See <REFERENCE>(head_auth_using).  These
groups may be provided via simple lists, VMS identifiers, HTA databases and
authorization agents.  The following example shows an identifier authenticated
realm with full and read-only access controlled by two simple lists.  For the
first path the world has no access, for the second read-only access (with the
read-only grouping becoming basically redundant information).

<CODE_EXAMPLE>
  ["Realm Name"=<EMPHASIS>(identifier_name)=id;<EMPHASIS>(full_access_name)=list;<EMPHASIS>(read-only_name)=list]
  /web/area/* r+w ; 
  /web/another-area/* r+w ; r
<ENDCODE_EXAMPLE>

<HEAD1>(Considerations\head_auth_quick_considerations)

<P> Multiple authentication sources (realms) may be configured in the one
HTTPD$AUTH file.

<P> Multiple paths may be mapped against a single authentication source.

<P> Any path may be mapped only once (for any single virtual service).

<P> Paths may have additional access restrictions placed on them, including
client host name, username, etc. See <REFERENCE>(head_auth_access_restrict).

<P> The configuration file is loaded and stored by the server at startup.  If
changed it must be reloaded to take effect.  This can be done manually using

<CODE_EXAMPLE>
  $ HTTPD/DO=AUTH=LOAD
<ENDCODE_EXAMPLE>

<P> Authentication information is cached.  Access subsequently removed or
modified will not take effect until the entry expires, or is manually purged
using

<CODE_EXAMPLE>
  $ HTTPD/DO=AUTH=PURGE
<ENDCODE_EXAMPLE>

<P> Failed attempts to authenticate against a particular source are limited. 
When this is exceeded access is always denied.  If this has happened the cache
must be manually purged before a user can successfully authenticate

<CODE_EXAMPLE>
  $ HTTPD/DO=AUTH=PURGE
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Authentication and Authorization\chapter_authorization)

<P> <EMPHASIS>(Authentication\BOLD) is the verification of a user's identity,
usually through username/password credentials.
<EMPHASIS>(Authorization\BOLD) is allowing a certain action to be applied to a
particular path based on authentication of the originator.

<P> Generally, authorization is a two step process. First authentication,
using a username/password database. Second authorization, determining what
the username is allowed to do for this transaction.

<P> Authentication environments can get complex very quickly, don't forget to
<QUOTE>(keep it simple, stupid), see <REFERENCE>(head_auth_kiss).

<HEAD>(Overview\head_auth_overview)

<P> Server authorization is performed using a configuration file,
authentication source, and optional full-access and read-only authorization
grouping sources, and is based on per-path directives. There is no
user-configured authorization necessary, or possible! In the configuration file
paths are associated with the authentication and authorization environments,
and so become subject to the HTTPd authorization mechanism. Reiterating
<HELLIPSIS> WASD HTTPd authorization administration involves those two aspects,
setting authorization against paths and administering the authentication and
authorization sources.

<P> <EMPHASIS>(Authorization is applied to the request path (i.e. the path in
the URL used by the client).  Sometimes it is possible to access the same
resource using different paths.  Where this can occur care must be exercised to
authorize all possible paths.\BOLD)

<P> <EMPHASIS>(Where a request will result in script activation, authorization
is performed on both script and path components\BOLD). First script access is
checked for any authorization, then the path component is independently
authorized. Either may result in an authorization challenge/failure.  This
behaviour can be disabled using a path SETting rule, see
<REFERENCE>(head_set_rules).

<P> The <EMPHASIS>(authentication source\BOLD) name is refered to as the
<EMPHASIS>(realm), and refers to a collection of usernames and passwords.  It
can be the system's SYSUAF database.

<P> The <EMPHASIS>(authorization source\BOLD) is refered to as the
<EMPHASIS>(group), and refers to a collection of usernames and associated
<EMPHASIS>(permissions).

<HEAD1>(Authentication Policy\head_auth_policy)

<P> A <EMPHASIS>(policy) regarding when and how authorization can be used may be
established on a per-server basis. This can restrict authentication challenges
to 
<QUOTE>(https:) (SSL) requests (see <REFERENCE>(chapter_ssl)), thereby ensuring
that the authorization environment is not compromised by use in non-encrypted
transactions. Two HTTPd qualifiers provide this.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(/AUTHORIZE=\BOLD)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ALL \BOLD) restricts <EMPHASIS>(all\BOLD) requests to authorized
paths.  If a path does not have authorization configured  against it it is
automatically denied access.  This is an effective method of preventing
inadvertant access to areas in a site.  See <REFERENCE>(head_auth_all_requests).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SSL \BOLD) restricts <EMPHASIS>(all\BOLD)
authentication/authorization transactions to the SSL environment.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>((SSL,ALL) \BOLD) combines the above two.

<ENDLIST>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/SYSUAF=\BOLD)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> Used without any keywords, this qualifier allows all current (non-expired,
non-disusered, etc.), non-privileged accounts to be used for authentication
purposes. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ID \BOLD) restricts SYSUAF authenticated
account to those possessing a specific VMS resource identifier (see
<REFERENCE>(head_auth_identifier)).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(RELAXED \BOLD) allows <EMPHASIS>(any\BOLD) current account to
be authorized via the SYSUAF.  <EMPHASIS>(This is not recommended,\BOLD) use
rights identifiers to allow some discrimination to be exercised.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SSL \BOLD) restricts only SYSUAF authenticated
transactions to the SSL environment.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD \BOLD) enables the deprecated, "hard-wired" WASD
identifier environment available to this server. See
<REFERENCE>(head_auth_wasd_identifier).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>((ID,SSL) \BOLD) would allow two keywords to be applied, etc.

<ENDLIST>

<ENDLIST>

<P> Note also that individual paths may be restricted to SSL requests using
either the mapping conditional rule configuration or the authorization
configuration files. See <REFERENCE>(head_conditionals) and
<REFERENCE>(head_auth_access_restrict).

<P> In addition, the following configuration parameters have a direct role in
an established authorization policy.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>([AuthFailureLimit] \BOLD) sets the maximum unsuccessful attempts
allowed before a username is then always refused authentication.  After this
limit is reached the cache must be purged to re-allow the user access, see
<REFERENCE>(head_server_authentication).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthRevalidateLoginCookie] \BOLD) When user revalidation is in
effect (see immediately below), after having  previously closed the browser
initial authentication of a resource is immediately followed by another if a
cached entry on the server indicated revalidation was required.  This prevents
this second request.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>([AuthRevalidateUserMinutes] \BOLD) sets the number of minutes
between successive authentication attempts before the user is forced to reenter
the authentication data (via a browser dialog).  Zero disables this function.

<ENDLIST>

<HEAD>(Authentication Failures\head_auth_failures)

<P> Details of authentication failures are logged to the HTTPd process log. 

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(%HTTPD-W-AUTHFAIL \BOLD) indicates a failure to authenticate
(incorrect username/password).  The number of failures, the realm name, the
user name and the originating host are provided. Isolated instances of this are
only of moderate interest.  Consecutive instances may indicate a user thrashing
about for the correct password, but they usually give up before a dozen
attempts.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(%HTTPD-I-AUTHFAILOK \BOLD) advises that a previous failure to
authenticate has now successfully done so.  This is essentially informational.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(%HTTPD-W-AUTHFAILIM \BOLD) indicates the number of failures
have exceeded the [AuthFailureLimit], after which automatic refusal begins. 
This message should be of concern and the circumstances investigated,
especially if the number of attempts becomes excessive.

<ENDLIST>

<HEAD1>(Permissions, Path and User\head_auth_perm_path_and_user)

<P> <EMPHASIS>(Both paths and usernames have permissions associated with
them.\BOLD) A path may be specified as read-only, read and write, write-only
(yes, I'm sure someone will want this!), or none (permission to do nothing). A
username may be specified as read capable, read and write capable, or only
write capable.  For each transaction these two are combined to determine the
maximum level of access allowed. The allowed action is the logical AND of the
path and username permissions.

<P> The permissions may be described using the HTTP method names, or using the
more concise abbreviations R, W, and R+W.

<COMMENT>(HTML=<P>)

<TABLE>
<TABLE_SETUP>(6\10\5\5\5\5)
<TABLE_HEADS>(Path/User\DELETE\GET\HEAD\POST\PUT)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(READ or R\no\yes\yes\no\no)
<TABLE_ROW>(WRITE or W\yes\no\no\yes\yes)
<TABLE_ROW>(R+W\yes\yes\yes\yes\yes)
<TABLE_ROW>(NONE\no\no\no\no\no)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(DELETE\yes\yes\no\no\no)
<TABLE_ROW>(GET\no\yes\no\no\no)
<TABLE_ROW>(HEAD\no\no\yes\no\no)
<TABLE_ROW>(POST\no\no\no\yes\no)
<TABLE_ROW>(PUT\no\yes\no\no\yes)
<ENDTABLE>

<HEAD1>(Authorization Configuration File\head_auth_file)

<P> Requiring a particular path to be authorized in the HTTP transaction is
accomplished by applying authorization requirements against that path in a
configuration file.  This is an activity distinct from setting up and
maintaining any authentication/authorization databases required for the
environment.

<P> By default, the system-table logical name HTTPD$AUTH locates a common
authorization configuration file, unless an individual rule file is specified
using a job-table logical name. Simple editing of the file changes the
configuration. Comment lines may be included by prefixing them with the hash
<QUOTE>(#) character, and lines continued by placing the backslash character
<QUOTE>(<BACKSLASH>) as the last character on a line.

<P> Configuration directives begin either with a <QUOTE>([realm]),
<QUOTE>([realm;group]) or <QUOTE>([realm;group-r+w;group-r]) specification, or
with the forward-slash of a path specification.  Following the path
specification are HTTP method keywords controlling group and world permissions
to the path, and any <EMPHASIS>(access-restricting\BOLD) request scheme
(<QUOTE>(https:)) and/or host address(es) and/or username(s).

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(REALM\BOLD)

<P> Square brackets are used to enclose a [realm;group;group] specification,
introducing a new authentication grouping.  Within  these brackets is specified
the realm name (authentication source), and then optional group (authorization
source) names separated by semi-colons. All path specifications following this
are authenticated against the specified realm database, and permissions
obtained from the group <QUOTE>([realm;group]) database (or authentication
database if group not specified), until the next [realm;group;group]
specification.

<P> The following shows the format of an authentication source (realm) only
directive.

<CODE_EXAMPLE>
  [authentication-source]
<ENDCODE_EXAMPLE>

<P> This one, the format of a directive using both authentication and
authorization sources (both realm and group).

<CODE_EXAMPLE>
  [authentication-source ; authorization-source]
<ENDCODE_EXAMPLE>

<P> The third variation, using an authentication, full-access (read and write)
and read-only authorization sources (realm and two grouping).

<CODE_EXAMPLE>
  [authentication-source ; full-access-source ; read-only-source]
<ENDCODE_EXAMPLE>

<P> The authentication source may also be given a description.  This is the
text the browser dialog presents during password prompting.  See 
<REFERENCE>(head_auth_realm_description) in
<REFERENCE>(head_auth_sources).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(PATH\BOLD)

<P> Paths are usually specified terminated with an asterisk wildcard. This
implies that any directory tree below this is included  in the access control.
Wildcards may be used to match any portion of the specified path, or not at
all. Following the path specification are control keywords representing the
HTTP methods or permissions that can be applied against the path, and optional
access-restricting list of host address(es) and/or username(s), separated using
commas. Access control is against either or both the group and the world. The
group access is specified first followed by a semi-colon separated world
specification. The following show the format of the path directive, see the
examples below to further clarify the format.

<CODE_EXAMPLE>
  /root/path/  group-access-list,group-permissions ; \
               world-access-list,world-permissions
<ENDCODE_EXAMPLE>

<ENDLIST>

<P> <EMPHASIS>(The same path cannot be specified against two different
realms.\BOLD) The reason lies in the HTTP authentication schema, which allows
for only one realm in an authentication dialog. How would the server decide
which realm to use in the authentication challenge? Of course, different parts
of a given tree may have different authorizations, however any tree ending in
an asterisk results in the entire sub-tree being controlled by the specified
authorization environment, unless a separate specification exists for some
inferior portion of the tree.

<P> There is a thirty-one character limit on authentication source names, and a
fifteen character limit on usernames and passwords.  All source and user names
are case-insensitive.  <EMPHASIS>(BASIC) authentication scheme passwords are
case insensitive, however <EMPHASIS>(DIGEST) authentication scheme passwords
should all be either upper or lower case, mixed case will not work.

<HEAD>(Reserved Names\head_auth_reserved_realms)

<P> The following names are reserved and have special functionality.

<LIST>(NUMBERED)

<LE> <EMPHASIS>(EXTERNAL - \BOLD) Any authentication and authorization will be
done in some way by an external CGI script.  None is attempted by the server.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(NONE - \BOLD) This refers to any request, is not authenticated
in a any way, and just marks the path as having been authorized for access.
See <REFERENCE>(head_auth_all_requests).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(PROMISCUOUS - \BOLD) This realm is only available while the
/PROMISCUOUS qualifier is in use.  See <REFERENCE>(chapter_server_admin).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WORLD - \BOLD) This refers to any request and is not
authenticated in any way, only the permissions associated with the path are
applied to the request.  The reserved username <QUOTE>(WORLD) becomes the 
authenticated username.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VMS - \BOLD) Use the server system's SYSUAF database to
authenticate the username. For <QUOTE>(http:) requests the username/password
pairs are transmitted encoded but not encrypted,

<COMMENT>(HTML=<FONT COLOR="#ff0000">so this is not recommended</B></FONT>.)

<COMMENT>(HTML/OFF)
<EMPHASIS>(this is not recommended\BOLD).
<COMMENT>(HTML/ON) 

For <QUOTE>(https:) requests, using the implicit security offered by SSL (see
<REFERENCE>(chapter_ssl)) the use of SYSUAF authentication is considered
viable.

<P> By default accounts with SYSPRV authorized are always rejected to
discourage the use of potentially significant usernames (e.g. SYSTEM). Accounts
that are disusered, have passwords that have expired, or that are captive or
restricted are also automatically rejected.

<P> The authentication source may be disguised by giving it a specific
description.  This will the text the browser dialog presents during password
prompting.  See 
<REFERENCE>(head_auth_realm_description) in
<REFERENCE>(head_auth_sources).

<P> See <REFERENCE>(head_auth_sysuaf) for further information on these topics.

<ENDLIST>

<HEAD>(Reserved Username\head_auth_reserved_username)

<P> The following username is reserved.

<LIST>(NUMBERED)

<LE> <EMPHASIS>(WORLD - \BOLD) If a path is authorized using the WORLD realm
the pseudo-authenticated username becomes <QUOTE>(WORLD).  Any log will reflect
this  username and scripts will access a WWW_REMOTE_USER containing this value. 
Although not forbidden, it is not recommended this string be used as a username
in other realms.

<ENDLIST>

<HEAD>(Access Restriction List\head_auth_access_restrict)

<P> If a host name, protocol identifier or username is included in the path
configuration directive it acts to <EMPHASIS>(further\BOLD) limit access to
matching clients (path and username permissions still apply). If more than one
are included a request must match each. If multiple host names and/or
usernames are included the client must match at least one of each. Host and
username strings may contains the asterisk wildcard, matching one or more
consecutive characters. This is most useful when restricting access to all
hosts within a given domain, etc.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Host Names - \BOLD) may be specified as either alphabetic (if
DNS name resolution is enabled, see [DNSlookup] configuration directive) or
numeric addresses. When a host restriction occurs there is never an attempt to
authenticate any associated username. Hence applying host restrictions very
effectively prevents an attack from outside the allowed addresses. The
reserved word <EMPHASIS>(#localhost) refers to the host name the server is
executing on.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Network Mask - \BOLD) The mask is a dotted-decimal network
address, a slash, then a  dotted-decimal mask.  A network mask operates by
bitwise-ANDing the client host address with the mask, bitwise-ANDing the
network address supplied with the mask, then comparing the two results for
equality.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Request Scheme - \BOLD) (protocol) either <QUOTE>(http:) or
secured via <QUOTE>(https:) (SSL)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(User Names - \BOLD) are indicated by a leading tilde,
the <QUOTE>(~) character (similar or username URL syntax).

<ENDLIST>

<CP> For example

<CODE_EXAMPLE>
  /web/secret/* *.three.stooges,~Moe,~Larry,~Curly,read
<ENDCODE_EXAMPLE>

<CP> restricts read access to Curly, Larry and Moe accessing from within the
three.stooges network, while

<CODE_EXAMPLE>
  /web/secret/* https:,*.three.stooges,~Moe,~Larry,~Curly,read
<ENDCODE_EXAMPLE>

<CP> applies the further restriction of access via <QUOTE>(https:) (SSL) only.

<P> This example show the use of a network mask to restrict based on the source
network of the client.

<CODE_EXAMPLE>
  /web/secret/* https:,#131.185.250.128/255.255.255.192,~Moe,~Larry,~Curly,read
<ENDCODE_EXAMPLE>

<P> This example uses a 6 bit subnet.  Using the above example the host
131.185.250.250 would be accepted, but 131.185.250.50 would be rejected.

<P> Note that it more efficient to place <EMPHASIS>(protocol) and
<EMPHASIS>(host) restrictions at the front of a list.

<COMMENT>(....................................................................)

<HEAD1>(Authorization Sources\head_auth_sources)

<P> Username authorization information may be derived from several sources,
each with different characteristics.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VMS Rights Identifier\BOLD)

<P> An identifier is indicated by appending a <QUOTE>(=ID) to the name of the
realm or group.  Also refer to <REFERENCE>(head_auth_identifier).


<P> Whether or not any particular username is allowed to authenticate via the
SYSUAF may be controlled by that account holding or not holding a particular
rights identifier. Placing <QUOTE>(=ID) against realm name implies the username
must exist in the SYSUAF and hold the specified identifier name.

<CODE_EXAMPLE>
  [PROJECT_A=id]
<ENDCODE_EXAMPLE>

<P> When (and only when) a username has been authenticated via the SYSUAF,
rights identifiers associated with that account may be used to control the
level-of-access within that realm.  This is in addition to any identifier
controlling authentication itself.

<CODE_EXAMPLE>
  [PROJECT_A=id;PROJECT_A_LIBRARIAN=id;PROJECT_A_USER=id]
<ENDCODE_EXAMPLE>

<P> In this example a username would need to hold the PROJECT_A identifier to
be able to authenticate, PROJECT_A_LIBRARIAN to write the path(s) (via POST,
PUT) and PROJECT_A_USER to be able to read the path(s).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VMS Authentication\BOLD)

<P> The server system SYSUAF may be used to authenticate usernames using the
VMS account name and password.  The realm being VMS may be indicated by using
the name <QUOTE>(VMS), by appending <QUOTE>(=VMS) to another name making it
a <EMPHASIS>(VMS synonym), or by giving it a specific description (see
<REFERENCE>(head_auth_realm_description) in <REFERENCE>(head_auth_sources)).
Further information on SYSUAF authentication may be found in
<REFERENCE>(head_auth_sysuaf). These examples illustrate the general idea. 

<CODE_EXAMPLE>
  [VMS]
  [LOCAL=vms]
  [ANY_NAME_AT_ALL=vms]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Simple List\BOLD)

<P> A plain-text list may be used to provide usernames for group membership. 
The format is one username per line, at the start of the line, with optional,
white-space delimited text continuing along the line (which could be used as
documentation).  Blank lines and comment lines are ignored.  A line may be
continued by ending it with a <QUOTE>(<BACKSLASH>) character.  These files
may, of course, be created and maintained using any plain text editor.  They
must exist in the HT_AUTH: directory, have an extension of <QUOTE>(.$HTL), and
do not need to be world accessable.

<CODE_EXAMPLE>
  # the stooges
  curley     Jerome Horwitz
  larry      Louis Feinberg
  moe        Moses Horwitz
  shemp      Samuel Horwitz
  JoeBesser
  JoeDeRita
<ENDCODE_EXAMPLE>

<P> Simple lists are indicated in the configuration by appending a
<QUOTE>(=LIST) to the name.

<CODE_EXAMPLE>
  [VMS;STOOGES=list]
<ENDCODE_EXAMPLE>

<P> It also possible to use a simple list for authentication purposes.  The
plain-text password is appended to the username with a trailing equate symbol.
Although in general this is not recommended as everything is stored as
plain-text it may be suitable as an ad hoc solution in some circumstances. The
following example shows the format.

<CODE_EXAMPLE>
  # silly example
  fred=dancesalittle  Guess who?
  ginger=rogers       No second prizes!
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTA Database\BOLD)

<P> These are binary, fixed 512 byte record files, containing authentication
and authorization information.  HTA databases may be used for authentication
and group membership purposes.  The content is much the same, the role differs
according to the location in the realm directive.  The contents these files
must be accessed and modified via the server administration menu.  See
<REFERENCE>(head_server_revise). They are located in the HT_AUTH: directory and
have an extension of <QUOTE>(.$HTA).

<P> (Essentially for historical reasons) HTA databases are the default sources
for authorization information.  Therefore, using just a name, with no trailing
<QUOTE>(=<EMPHASIS>(something)), will configure an HTA source.  Also, and
recommended for clearly showing the intention, appending the <QUOTE>(=HTA)
qualifier specifies an HTA database.  The following example show some of the
variations.

<CODE_EXAMPLE>
  [VMS;PROJECT_A=hta]
  [DEVELOPERS=hta;PROJECT_A=hta]
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Authorization Agent\BOLD)

<P> An authorization agent is a CGI-compliant script that is specially
activated during the authorization processing.  Using CGI environment variables
it gets details of the request, makes an assessment based on it's own internal
authentication/authorization processing, and using the script
<EMPHASIS>(callout) mechanism returns it's results to the server, which then
acting on these, allows or denies access.

<P> Such agents allow a site to develop local authentication/authorization
mechnisms relatively easily, based on CGI principles.  A discussion of such a
development is not within the scope of this section, see the

<COMMENT>(HTML=
<A HREF="/ht_root/doc/scripting/">WASD Scripting Environment</A>
)

<COMMENT>(HTML/OFF)
<QUOTE>(WASD Scripting Environment)
<COMMENT>(HTML/ON) 

document for information on the use of callouts, and the example and working
authorization agents provided in the

<COMMENT>(HTML=
<A HREF="/ht_root/src/agent/">HT_ROOT:[SRC.AGENT]</A> directory.
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.AGENT] directory.
<COMMENT>(HTML/ON) 

The description at the beginning of these programs covers these topics in some
detail.

<P> An authorization agent would be configured using something like the
following, where the <QUOTE>(AUTHAGENT) is the actual script name doing the
authorization.  This has the the path <QUOTE>(/cgiauth-bin/) prepended to it.

<CODE_EXAMPLE>
  ["Example Agent"=AUTHAGENT_EXAMPLE=agent]
  /some/path/or/other/* r+w
<ENDCODE_EXAMPLE>

<P> It is possible to supply additional, per-path information to an agent. 
This can be any free-form text (up to a maximum length of 63 characters).  This
might be a configuration file location, as used in the example CEL
authenticator.  For example,

<CODE_EXAMPLE>
  ["CEL Authenticator"=AUTHAGENT_CEL=agent]
  /some/path/or/other/* r+w,param=HT_ROOT:[LOCAL]CEL1.LIS
  /a/nother/path/* r+w,param=HT_ROOT:[LOCAL]CEL2.LIS
<ENDCODE_EXAMPLE>

<P> It is necessary to have the following entry in the HTTPD$MAP configuration
file:

<CODE_EXAMPLE>
  exec+ /cgiauth-bin/* /cgi-bin/*
<ENDCODE_EXAMPLE>

<P> This implies that authentication agents are always CGIplus scripts
(technically it's possble for vanilla CGI script to be agents, but for
efficiency reasons this is discouraged).  It also allows authentication scripts
to be located outside of the general server tree if desired.

<ENDLIST>

<HEAD>(Multiple Source Types\head_auth_sources_multiple)

<P> A realm directive may contain one or more different types of authorization
information source, with the following restrictions.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> Rights identifiers may only be used with SYSUAF authenticated requests. 
The following combinations would therefore not be allowed.

<CODE_EXAMPLE>
  [DEVELOPERS;PROJECT_A=id]
  [DEVELOPERS=hta;LIBRARIAN=id;PROJECT_A=list]
  [STOOGES=list;MOE_HOWARD=id]
<ENDCODE_EXAMPLE>

<LE> WASD rights identifiers (deprecated) may only be used for group membership
when the /AUTHORIZE=WASD server qualifier has been specified at startup, and
the username has been authenticated using a WASD identifier.  See
<REFERENCE>(head_auth_wasd_identifier).

<ENDLIST>

<HEAD>(Realm Description\head_auth_realm_description)

<P> It is possible to supply text describing the authentication realm to the
browser user that differs from the actual source name.  This may be used to
disguise the  actual source or to provide a more informative description than
the source name conveys.

<P> Prefixing the actual realm source name with a double-quote
delimited string (of up to 31 characters) and an equate symbol will result in
the string being sent to a browser as the realm description during an
authentication challenge.  Here are some examples.

<CODE_EXAMPLE>
  [<QUOTE>(the local host)=VMS]
  [<QUOTE>(Social Club)=SOCIAL_CLUB_RW=id]
  [<QUOTE>(Finance Staff)=FINANCE=list]
  [<QUOTE>(Just Another Database)=DBACCESS=hta]
<ENDCODE_EXAMPLE>

<NOTE>
The <EMPHASIS>(Digest) authentication scheme uses the realm description at both
server and browser in the encrypted password challenge and response.  When
passwords are stored in an HTA file this realm synonym cannot be changed
without causing these passwords to be rendered invalid.
<ENDNOTE>

<COMMENT>(....................................................................)

<HEAD1>(Realm, Full-Access, Read-Only\head_auth_using)

<P> WASD authorization offers a number of combinations of access control.  This
is a summary.  Please note that when refering to the
<EMPHASIS>(level-of-access) a particular username may be allowed (read-only or
full, read-write  access), that it is always moderated by the level-of-access
provided with a path configured within that realm.
See <REFERENCE>(head_auth_perm_path_and_user).

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Authentication Only\BOLD)

<P> When a path is controlled by a realm that comprises an authentication
source only, as in this example

<CODE_EXAMPLE>
  [authentication-source]
<ENDCODE_EXAMPLE>

<CP> usernames authenticated using that are granted full (read and write)
access.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Authentication and Group\BOLD)

<P> Where a group membership source is provided following the authentication
source, as illustrated in this example

<CODE_EXAMPLE>
  [authentication-source;group-source]
<ENDCODE_EXAMPLE>

<CP> the level-of-access depends on the source of the group membership.  If
from a <EMPHASIS>(simple-list) of usernames or via a <EMPHASIS>(VMS rights
identifier) the username receives full (read and write) access.  If from an HTA
database the access is dependent on what is set against that user in the
database.  It can be either full or read-only.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Authentication and Two Groups\BOLD)

<P> When a second group is specified, as in

<CODE_EXAMPLE>
  [authentication-source;group-source;group-source]
<ENDCODE_EXAMPLE>

<CP> the authentication is interpreted in a
fixed fashion.  The first group specified contains usernames to be granted full
(read and write) access.  The second group read-only access.  Should a username
occur in both groups full access takes precedence.

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD1>(Virtual Servers\head_auth_virtual)

<P> As described in <REFERENCE>(head_virtual_services), virtual service syntax
may be used with authorization mapping to selectively apply rules to one
specific service.  This example provides the essentials of using this syntax. 
Note that service-specific and service-common rules may be mixed in any order
allowing common authorization environments to be shared.

<CODE_EXAMPLE>
  # authorization rules example for virtual servers
  [[alpha.wasd.dsto.defence.gov.au:443]]
  # ALPHA SSL is the only service permitting VMS (SYSUAF) authentication
  [LOCAL=vms]
  /web/* https:,r+w ; r
  /httpd/-/admin/* ~daniel,https:,r+w
  [[beta.wasd.dsto.defence.gov.au:80]]
  # BETA has it's own HTA database
  [BETA_USER=hta]
  /web/* r+w ; r
  [[gamma.wasd.dsto.defence.gov.au:80]]
  # GAMMA likewise
  [GAMMA_DEVELOPER=id;PROJECT-A=list]
  /web/project/a/* r+w ; r
  [GAMMA_DEVELOPER=id;PROJECT-B=list]
  /web/project/b/* r+w ; r
  [[*]]
  # allow anyone from the local subnet to upload to here
  [WORLD]
  /web/unload/* 131.185.200.*,r+w

<ENDCODE_EXAMPLE>

<P> The server administration menu path authorization report (see
<REFERENCE>(head_server_reports)) provides a selector allowing the viewing and
checking of rules showing all services or only one particular virtual server,
making it simpler to see exactly what any particular service is authorizing
against.

<COMMENT>(..................................................................)

<HEAD1>(Authorization Configuration Examples\head_auth_examples)

<P> Mixed case is used in the configuration examples (and should be in
configuration files) to assist in readability.  Rule interpretation however is
completely case-insensitive.

<LIST>(NUMBERED)

<LE> In the following example the authentication realm is <QUOTE>(WASD), a
synonym for SYSUAF authentication, and the permissions group
<QUOTE>(SOCIALCLUB), a simple list of usernames.  The directive allows those
authenticated from the WASD realm and in the SOCIALCLUB group full access (read
and write), and the world read-only.

<CODE_EXAMPLE>
  [WASD=vms;SOCIALCLUB=list]
  /web/socialclub/* r+w ; read
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> This example illustrates restricting access according internet address.
Both the group and world restriction is identical, but the group address is
being specified numerically, while the world access is being specified
alphabetically (just for the purposes of illustration). This access check is
done doing simple wildcard comparison, and makes numerical specifications
potentially more efficient because they are usually shorter. The second line
restricts that path's write access even further, to one username,
<QUOTE>(BLOGGS).

<CODE_EXAMPLE>
  [WASD=vms;SOCIALCLUB=list]
  /web/socialclub/* 131.185.45.*,get,post; *.dsto.defence.gov.au,get
  /web/socialclub/accounts/* 131.185.45.*,~BLOGGS,get,post; *.dsto.defence.gov.au,get
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> Three sources for authorization are specified in the following example. 
As the authentication source is VMS (by rights identifier), the full-access
group and read-only group can also be determined by possessing the specified
identifiers.  The first path can only be written to by those holding the
full-access identifier (librarian), the second path can only be read by both. 
The world has no access to these paths.

<CODE_EXAMPLE>
  [DEVELOPER=id;PROJECT_A_LIBRARIAN=id;PROJECT_A_USER=id]
  /web/projects/a/*  r+w
  /web/projects/*    r
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> In the following example the authentication realm and group are a single
HTA database, <QUOTE>(ADMIN). The first directive allows those in the ADMIN
group to read and write, and the world to read (<QUOTE>(get,post;get)). The
second line restricts write and even read access to ADMIN group, no world
access at all (<QUOTE>(get,post)).

<CODE_EXAMPLE>
  [ADMIN=hta]
  /web/everyone/* get,post;get
  /web/select/few/* get,post
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> With this example usernames are used to control access to the specified
paths. These usernames are authenticated from the COMPANY database.  The world
has read access in both cases.  Note the realm description, <QUOTE>(The
Company).
<CODE_EXAMPLE>
  [<QUOTE>(The Company)=COMPANY=hta]
  /web/docs/* ~Howard,~George,~Fred,r+w ; r
  /web/accounts/* ~George,r+w ; r
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The following example shows a path specifying the local system's SYSUAF
being used to authenticate any usernames. Whenever using SYSUAF authentication
it is <EMPHASIS>(strongly recommended to limit the potential hosts\BOLD) that
can authenticate in this way by always using a host-limiting access
restriction list. The world gets read access.

<CODE_EXAMPLE>
  [VMS]
  /web/local/area/* 131.185.250.*,r+w ; r
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> To restrict server administration to browsers executing on the server
system itself and the SYSUAF-authenticated username DANIEL use a restriction
list similar to the following.  It also shows the use of SYSUAF-authentication
being hidden by using a realm description.

<CODE_EXAMPLE>
  [<QUOTE>(not the VMS SYSUAF)=VMS]
  /httpd/-/admin/*  #localhost,~daniel,r+w
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The following example illustrates providing a read and writable area (GET,
POST and PUTable) to hosts in the local network <EMPHASIS>(without username
authentication\BOLD) (careful!).

<CODE_EXAMPLE>
  [WORLD]
  /web/scratch/*  *.local.hosts.only,r+w
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(..................................................................)

<HEAD2>(KISS\head_auth_kiss)

<P> WASD authorization allows for very simple authorization environments and
provides the scope for quite complex ones.  The path authentication scheme
allows for multiple, individually-maintained authentication and authorization
databases that can then be administered by autonomous managers, applying to
widely diverse paths, all under the ultimate control of the overall Web
administrator.

<P> <EMPHASIS>(Fortunately great complexity is not generally necessary.\BOLD)

<P> Most sites would be expected to require only an elementary setup allowing a
few selected Web information managers the ability to write to selected paths. 
This can best be provided with the one authentication database containing read
and write permissions against each user, with and access-restriction list
against individual paths.

<P> For example.  Consider a site with three departments, each of
which wishes to have three representatives capable of administering the
departmental Web information.  Authentication is via the SYSUAF.  Web
administrators hold an approriate VMS rights identifier, <QUOTE>(WEBADMIN). 
Department groupings are provided by three simple lists of names, including the
Web administrators (whose rights identifier would not be applied if access
control is via a simple list), a fourth lists those with read-only access into
the Finance area.  The four grouping files would look like:

<CODE_EXAMPLE>
  # Department 1            # Department 2
  WEB1                      WEB1
  WEB2                      WEB2
  JOHN                      RINGO
  PAUL                      CURLY
  GEORGE                    LARRY

  # Department 3            # Finance (read access)
  WEB1                      PAUL
  WEB2                      GEORGE
  MOE                       JOHN
  SHEMP                     RINGO
  MAC
<ENDCODE_EXAMPLE>

<CP> The authorization configuration file then contains:

<CODE_EXAMPLE>
  #######################################################################

  # allow web masters (!) to use the administration menu
  #                       to revise web configuration files
  # world has no access (read or write)
  # access is only allowed from a browser in the same subnet as the HTTPd
  ["Hypo Thetical Corp."=HYPOTHETICAL=vms;WEBADMIN=id]
  /httpd/-/admin/*  #150.15.30.*,r+w
  /ht_root/local/*  #150.15.30.*,r+w

  # allows Department 1 representatives to maintain their web
  # this may only be done from within the company subnet
  # world has read access
  ["Hypo Thetical Corp."=HYPOTHETICAL=vms;DEPARTMENT1=list]
  /web/dept/general/*   150.15.30.*,r+w ; r

  # and so on for the rest of the departments

  ["Hypo Thetical Corp."=HYPOTHETICAL=vms;DEPARTMENT2=list;FINANCE=list]
  # no world read access into finance, only those in the FINANCE list
  /web/dept/finance/*    150.15.30.*,r+w 

  ["Hypo Thetical Corp."=HYPOTHETICAL=vms;DEPARTMENT3=list]
  /web/dept/inventory/*       150.15.30.*,r+w ; r
  /web/dept/production/*      150.15.30.*,r+w ; r
  # (the next uses line continuation just for illustration)
  /web/dept/marketing/*       150.15.30.*,\
                              r+w ;\
                              read

  # we need an area for general POSTing (just for illustration :^)
  [WORLD]
  /web/world/*  r+w 

  #######################################################################
<ENDCODE_EXAMPLE>

<COMMENT>(..................................................................)

<HEAD1>(Authorization Cache\head_auth_cache)

<P> Access to authentication sources, SYSUAF, simple lists and HTA databases,
are relatively expensive operations.  To reduce the impact of this activity on
request latency and general server performance, authentication and
realm-associated permissions for each authenticated username are stored in a
cache.  This means that only the initial request needs to be checked from
appropriate databases, subsequent ones are resolved more quickly and
efficiently from cache.

<P> Such cached entries have a finite lifetime associated with them.  This
ensures that authorization information associated with that user is regularly
refreshed.  This period, in minutes, is set using the [AuthCacheMinutes]
configuration parameter.  Zero disables caching with a consequent impact on
performance.

<HEAD>(Implication\head_auth_cache_implication)

<P> Where-ever a cache is employed there arises the problem of keeping the
contents current.  The simple lifetime on entries in the authentication cache
means they will only be checked for currency whenever it expires.  Changes may
have occured to the databases in the meantime.

<P> Generally there is are other considerations when adding user access. 
Previously the user attempt failed (and was evaluated each time), now the user
is allowed access and the result is cached.

<P> When removing or modifying access for a user the cached contents must be
taken into account.  The user will continue to experience the previous level of
access until the cache lifetime expires on the entry.  When making such changes
it is recommended to explicitly purge the authentication cache either from the
command line using /DO=AUTH=PURGE (see <REFERENCE>(head_httpd_control)) or via
the server administration menu (see <REFERENCE>(chapter_server_admin)).  Of
course the other solution is just to disable caching, which is a less than
optimal solution.

<COMMENT>(..................................................................)

<HEAD1>(SYSUAF-Authenticated Users\head_auth_sysuaf)

<P> The ability to authenticate using the system's SYSUAF is controlled by the
server /SYSUAF[=keyword] qualifier. By default it is disabled.

<NOTE>(WARNING!)
<EMPHASIS>(SYSUAF authentication is not recommended except in the most secure
of LAN environments or when SSL is employed.\BOLD)
<ENDNOTE>

<P> HTTP (<QUOTE>(http:)) authentication is transmitted encoded but not
encrypted, making it vulnerable to evesdropping.

<P> By default accounts with SYSPRV authorized are always rejected to
discourage the use of potentially significant usernames (e.g. SYSTEM). This
behaviour can be changed through the use of specific identifiers, see
<REFERENCE>(head_auth_identifier) immediately below. Accounts that are
disusered, have passwords that have expired or that are captive or restricted
are always rejected.  Accounts that have access time restricting REMOTE or
NETWORK access will have those restrictions honoured (see
<REFERENCE>(head_auth_identifier) for a workaround for this.)

<P> Also see <REFERENCE>(head_auth_web_only).

<HEAD2>(Rights Identifiers\head_auth_identifier)

<P> Whether or not any particular username is allowed to authenticate via the
SYSUAF may be controlled by that account holding or not holding a particular
VMS rights identifier. When a username has been authenticated via the SYSUAF,
rights identifiers associated with that account may be used to control the
level-of-access within that realm.

<P> Use of identifiers for these purposes are enabled using the /SYSUAF=ID
server startup qualifier.

<P> Three reserved identifier names are optional.  A warning will be reported
during startup if these are not found.

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD_HTTPS_ONLY - \BOLD) restricts accounts holding it to
authenticating using SSL (https:).  Authentication via a standard
<QUOTE>(http:) will always be denied.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD_NIL_ACCESS - \BOLD) allows accounts with access time
restrictions to authenticate via the SYSUAF.  This is particularly intended to
support the use of nil-access accounts, see <REFERENCE>(head_auth_web_only).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD_PASSWORD_CHANGE - \BOLD) allows an account to modify it's
SYSUAF password, if this is configured for the server, see
<REFERENCE>(head_auth_user_password_change).

<ENDLIST>

<P> Identifiers may be managed using the following commands.  If unsure of the
security implications of this action consult the relevant VMS system management
security documentation.

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> ADD /IDENTIFIER WASD_HTTPS_ONLY
  UAF> ADD /IDENTIFIER PROJECT_USER
  UAF> ADD /IDENTIFIER PROJECT_DEVELOPER
  UAF> ADD /IDENTIFIER PROJECT_LIBRARIAN
<ENDCODE_EXAMPLE>

<P> They can then be provided to desired accounts using commands similar to the
following:

<CODE_EXAMPLE>
  UAF> GRANT /IDENTIFIER PROJECT_USER <LITERAL>(<account>)
<ENDCODE_EXAMPLE>

<P> and removed using:

<CODE_EXAMPLE>
  UAF> REVOKE /IDENTIFIER PROJECT_USER <LITERAL>(<account>)
<ENDCODE_EXAMPLE>

<P> Be aware that, as with all successful authentications, and due to the
WASD internal authentication cache, changing database contents does not
immediately affect access.  Any change in the RIGHTSLIST won't be reflected
until the cache entry expires or it is explicitly flushed (see
<REFERENCE>(head_auth_cache)).

<HEAD2>(WASD <QUOTE>(Hard-Wired) Identifiers\head_auth_wasd_identifier)

<P>
<NOTE>(Deprecated and Discouraged)
There are now <QUOTE>(better) approaches to achieving the same functionality
as described in this section.  This documentation is retained only for
reference by older site configurations.
<ENDNOTE>

<P>
<EMPHASIS>(This description is included for reasons of backward compatibility. 
As of version 6.0 the WASD identifiers must be enabled using the /SYSUAF=WASD
qualifier.\BOLD)

<P> When SYSUAF authentication is enabled, by default all non-privileged,
active accounts are capable of authentication.  Restriction of this to those
actually requiring such a capability is provided using VMS rights identifiers. 
When the /SYSUAF=WASD qualifier is employed a VMS account must possess one of two
specific identifiers before it is allowed to be used for server authentication. 
Note that this mechanism can also allow privileged accounts to be so used
<HELLIPSIS> deploy with discretion! Note also that the use of access
identifiers with this facility allows a much finer control of which accounts
may be used for authentication and so is also the prefered mechanism for
deploying SYSUAF authentication.

<LIST>(NUMBERED)

<LE> <EMPHASIS>(WASD_VMS_R\BOLD)

<P> This identifier provides at most read access.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD_VMS_RW\BOLD)

<P> This identifier provides read and write access (path protections still
apply of course).

<ENDLIST>

<P> Other identifiers provide further control for the way in which the
authenticated account may be used.

<LIST>(NUMBERED)

<LE> <EMPHASIS>(WASD_VMS_HTTPS\BOLD)

<P> Use of the authenticated account is restricted to <QUOTE>(https:) (SSL)
requests.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD_VMS_PWD\BOLD)

<P> The account is allowed to change it's SYSUAF password (!!).  It is
recommended this facility only be employed with SSL in place. 

<P> Password modification is enabled by including a mapping rule to the
internal change script.

<CODE_EXAMPLE>
  pass /httpd/-/change/* /httpd/-/change/*
<ENDCODE_EXAMPLE>

<P> The authorization configuration file must provide authenticated access.

<CODE_EXAMPLE>
  [VMS;VMS]
  /httpd/-/change/vms/* https:,r+w
<ENDCODE_EXAMPLE>

<P> Also see <REFERENCE>(head_auth_user_password_change).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(WASD_VMS__<LITERAL>(<group-name>)\BOLD)

<P> This form allows a suitably named identifier to be created for
use in providing group-membership via the SYSUAF.  Note the double-underscore
separating the fixed from the locally specified portion.  Using these
identifiers it is possible to limit paths to SYSUAF-authenticated accounts
possessing the requisite identifier in manner similar to
non-SYSUAF-authentication groups.  An account possessing the WASD_VMS__TESTING
identifier is allowed write access to the path in the following example:

<CODE_EXAMPLE>
  [VMS;TESTING]
  /web/project/testing/* r+w ; r
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(HTML=
<PRE>

</PRE>)

<P> All four rights identifiers must exist for the /SYSUAF=ID facility to be
used (even though none may be granted to any account).  The identifiers may be
created using the AUTHORIZE utility with following commands:

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> ADD /IDENTIFIER WASD_VMS_R
  UAF> ADD /IDENTIFIER WASD_VMS_RW
  UAF> ADD /IDENTIFIER WASD_VMS_HTTPS
  UAF> ADD /IDENTIFIER WASD_VMS_PWD
<ENDCODE_EXAMPLE>

<P> They can then be provided to desired accounts using commands similar to the
following:

<CODE_EXAMPLE>
  UAF> GRANT /IDENTIFIER WASD_VMS_RW <LITERAL>(<account>)
<ENDCODE_EXAMPLE>

<P> and removed using:

<CODE_EXAMPLE>
  UAF> REVOKE /IDENTIFIER WASD_VMS_RW <LITERAL>(<account>)
<ENDCODE_EXAMPLE>

<HEAD2>(Nil-Access VMS Accounts\head_auth_web_only)

<P> It is possible, and may be quite effective for some environments, to have a
SYSUAF account or accounts strictly for HTTP authorization, with no actual
interactive or other access allowed to the VMS system itself.  This would relax
the caution on the use of SYSUAF authentication outside of SSL transactions. An
obvious use would be for the HTTP server administrator.  Additional accounts
could be provided for other authorization requirements, all without
compromising the system's security.

<P> In setting up such an environment it is vital to ensure the HTTPd
server is started using the /SYSUAF=ID qualifier (see
<REFERENCE>(head_auth_policy)).  This will require all
SYSUAF-authenticated accounts to possess a specific VMS resource identifier,
accounts that do not possess the identifier cannot be used for HTTP
authentication.  In addition the identifier WASD_NIL_ACCESS will need to be
held (see <REFERENCE>(head_auth_identifier)), allowing the account to
authenticate despite being restricted by REMOTE and NETWORK time restrictions.

<P> To provide such an account select a group number that is currently unused
for any other purpose.  Create the desired account using whatever local
utility is used then activate VMS AUTHORIZE and effectively disable access to
that account from all sources and grant the appropriate access identifier (see
<REFERENCE>(head_auth_identifier) above).

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> MODIFY <LITERAL>(<account>) /NOINTERACTIVE /NONETWORK /NOBATCH /FLAG=DISMAIL
  UAF> GRANT /IDENTIFIER WASD_VMS_RW <LITERAL>(<account>)
<ENDCODE_EXAMPLE>

<HEAD2>(SYSUAF and SSL\head_auth_sysuaf_ssl)

<P> When SSL is in use (see <REFERENCE>(chapter_ssl)) the username/password
authentication information is inherently secured via the encrypted
communications of SSL. To enforce access to be via SSL add the following to the
HTTPD$MAP configuration file:

<CODE_EXAMPLE>
  /whatever/path/you/like/*  "403 Access denied."  ![sc:https]
<ENDCODE_EXAMPLE>

<CP> or alternatively the following to the HTTPD$AUTH configuration file:

<CODE_EXAMPLE>
  [REALM]
  /whatever/path/you/like/*  https:
<ENDCODE_EXAMPLE>

<P> Note that this mechanism is applied <EMPHASIS>(after\BOLD) any path and
method assessment made by the server's authentication schema.

<P> The qualifier /SYSUAF=SSL provides a powerful mechanism for protecting
SYSUAF authentication, restricting SYSUAF authenticated transactions to the SSL
environment.  The combination /SYSUAF=(SSL,ID) is particularly effective.

<P> Also see <REFERENCE>(head_auth_policy).

<HEAD2>(Security Profile\head_auth_security_profile)

<P> It is possible to control access to files and directories based on the VMS
security profile of a SYSUAF-authenticated remote user. This functionality is
implemented using VMS security system services involving SYSUAF and RIGHTSLIST
information. The feature must be explicitly allowed using the server /PROFILE
qualifier. By default it is disabled.

<NOTE>
Use caution when deploying the /PROFILE qualifier.  It was really designed with 
a very specific environment in mind, that of an Intranet where the sole purpose
was to provide VMS users access to their normal VMS resources via a Web
interface.
<ENDNOTE>

<P> When a SYSUAF-authenticated user (i.e. the VMS realm) is first
authenticated a VMS security-profile is created and stored in the
authentication cache (see <REFERENCE>(head_auth_cache)). A cached profile is an
efficient method of implementing this as it obviously removes the need of
creating a user profile each time a resource is assessed. If this profile
exists in the cache it is attached to each request authenticated for that user.
As it is cached for a period, any change to a user's security profile in the
SYSUAF or RIGHTSLIST won't be reflected in the cached profile until the cache
entry expires or it is explicitly flushed (see
<REFERENCE>(head_server_action)).

<P> When a request has this security profile all accesses to files and
directories are assessed against it. When a file or directory access is
requested the security-profile is employed by a VMS security system service to
assess the access. If allowed, it is provided via the SYSTEM file protection
field. Hence it is possible to be eligible for access via the OWNER field but
not actually be able to access it because of SYSTEM field protections! If not
allowed, a <QUOTE>(no privilege) error is generated.

<P> Of course, this functionality only provides access for the server, IT DOES
NOT PROPAGATE TO ANY SCRIPT ACCESS. If scripts must have a similar ability
they should implement their own scheme (which is not too difficult,

<COMMENT>(HTML=
see <A HREF="/ht_root/src/misc/chkacc.c">HT_ROOT:[SRC.MISC]CHKACC.C</A>)
)

<COMMENT>(HTML/OFF)
see HT_ROOT:[SRC.MISC]CHKACC.C
<COMMENT>(HTML/ON)

based on the CGI variable WWW_AUTH_REALM which would be <QUOTE>(VMS) indicating
SYSUAF-authentication, and the authenticated name in WWW_REMOTE_USER.

<HEAD>(Performance Impact\head_auth_sysuaf_perf)

<P> If the /PROFILE qualifier has enabled SYSUAF-authenticated security
profiles,  whenever a file or directory is assessed for access an explicit VMS
security system service call is made.  This call builds a security profile of
the object being assessed, compares the cached user security profile and
returns an indication whether access is permitted or forbidden.  This is
addition to any such assessments made by the file system as it is accessed.

<P> This extra security assessment is not done for non-SYSUAF-authenticated
accesses within the same server.

<P> For file access this extra overhead is negligible but becomes more
significant with directory listings (<QUOTE>(Index of)) where each file in the
directory is independently assessed for access.

<COMMENT>(..................................................................)

<HEAD1>(Controlling Server Write Access\head_auth_control_acls)

<P> The server account should have no direct write access to into any
directory structure. Files in these areas should be owned by SYSTEM ([1,4]).
Write access for the server into VMS directories (using the POST or PUT HTTP
methods) should be controlled using VMS ACLs. <EMPHASIS>(This is in addition
to the path authorization of the server itself of course!\BOLD) The
recommendation to have no ownership of files and provide an ACE on required
directories prevents inadvertant mapping/authorization of a path resulting in
the ability to write somewhere not intended.

<P> Two different ACEs implement two grades of access.

<LIST>(NUMBERED)

<LE> If the ACE grants <EMPHASIS>(CONTROL\BOLD) access to the server account
then only VMS-authenticated usernames with security profiles can potentially
write to the directory. Only potentially, because a further check is made to
assess whether that VMS account in particular has write access.

<P> This example shows a suitable ACE that applies only to the original
directory:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL)
<ENDCODE_EXAMPLE>

<CP> This example shows setting an ACE that will propagate to created files
and importantly, subdirectories:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL), -
          (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL))
<ENDCODE_EXAMPLE>

<LE> If the ACE grants <EMPHASIS>(WRITE\BOLD) access then the directory can be
written into by any authenticated username for the authorized path.

<P> This example shows a suitable ACE that applies only to the original
directory:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE)
<ENDCODE_EXAMPLE>

<CP> This example shows setting an ACE that will propagate to created files
and importantly, subdirectories:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+EXECUTE+DELETE), -
          (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE))
<ENDCODE_EXAMPLE>

<ENDLIST>

<P> To assist with the setting of the required ACEs an example,
general-purpose DCL procedure is provided,

<COMMENT>(HTML=
<A HREF="/ht_root/example/authace.com">HT_ROOT:[EXAMPLE]AUTHACE.COM</A>.
)

<COMMENT>(HTML/OFF)
HT_ROOT:[EXAMPLE]AUTHACE.COM.
<COMMENT>(HTML/ON)

<COMMENT>(..................................................................)

<HEAD1>(Securing All Requests\head_auth_all_requests)

<P> Some sites may be sensitive enough about Web resources that the
possibility of providing inadvertant access to some area or another is of major
concern.  WASD provides a facility that will automatically deny access to any
path that does not appear in the authorization configuration file.  This does
mean that all paths requiring access must have authorization rules associated
with them, but if something is missed some resource does not unexpectedly
become visible.

<P> At server startup the /AUTHORIZE=ALL qualifier enables this facility.

<P> For paths that require authentication and authorization the standard realms
and rules apply.  To indicate that a particular path should be allowed access,
but that no authorization applies the <QUOTE>(NONE) realm may be used.  The
following example provides some indication of how it should be used.

<CODE_EXAMPLE>
  # allow the librarian to update this area, world to read it
  [VMS;LIBRARIAN=id]
  /web/library/* r+w ; read
  # indicate there is no authorization to be applied
  [NONE]
  # allow access to general web areas
  /web/*
  # allow access to the HT_ROOT tree
  /ht_root/*
<ENDCODE_EXAMPLE>

<COMMENT>(..................................................................)

<HEAD1>(User Password Modification\head_auth_user_password_change)

<P> The server provides for users to be able to change their own HTA passwords
(and SYSUAF if required). This functionality, though desirable from the
administrator's viewpoint, is not  mandatory if the administrator is content to
field any password changes, forgotten passwords, etc.  Keep in mind that
passwords, though not visible during entry, are passed to the server using
clear-text form fields.

<P> Password modification is enabled by including a mapping rule to the
internal change script.  For example:

<CODE_EXAMPLE>
  pass /httpd/-/change/* /httpd/-/change/*
<ENDCODE_EXAMPLE>

<P> Any database to be enabled for password modification must have a writable
authorization path associated with it.  Note that what looks like redundancy in
specifying an identical realm and group authorization is what allows multiple,
independant identifiers to be individually controlled for password change (i.e.
one group of identifier holders allowed to change the password, another not). 
For example:

<CODE_EXAMPLE>
  [GROUP=id;GROUP=id]
  /httpd/-/change/group/* r+w

  [ANOTHER_GROUP=id;ANOTHER_GROUP=id]
  /httpd/-/change/another_group/* r+w
<ENDCODE_EXAMPLE>

<P> Use some form of cautionary wrapper if providing this functionality:

<CODE_EXAMPLE><LITERAL>
  <H2>Change Your Authentication</H2>

  <BLOCKQUOTE><I>
  Change the password used to identify yourself to the REALM Web environment for
  some actions.  Note that this <U>not</U> an operating system password, nor has
  it anything to do with it.  Due to the inherent weaknesses of using
  non-encrypted password transmissions on networks <FONT COLOR="#ff0000"><U>DO
  NOT</U> use a password you have in use anywhere else, especially an operating
  system password!</FONT> You need your current password to make the change.  If
  you have forgotten what it is contact <A HREF="/web/webadmin.html">WebAdmin</A>,
  preferably via e-mail, for the change to be made on your behalf.
  </I></BLOCKQUOTE>

  <UL>
  <LI><A HREF="/httpd/-/change/REALM/">REALM</A> realm.
  </UL>
<ENDLITERAL><ENDCODE_EXAMPLE>

<COMMENT>(..................................................................)

<HEAD1>(Cancelling Authorization\head_auth_logout)

<P> The reason authorization information is not required to be reentered on
subsequent accesses to controlled paths is cached information the browser
maintains.  It is sometimes desirable to be able to access the same path using
different authentication credentials, and correspondingly it would be useful if
a browser had a <EMPHASIS>(purge authorization cache) button, but this is
commonly not the case.  To provide this functionality the server must be used
to <QUOTE>(trick) the browser into cancelling its authorization information for
a particular path.

<P> This is achieved by adding a specific query string to the path requiring
cancellation.  The server detects this and returns an authorization failure
status (401) regardless of the contents of request <QUOTE>(Authorization:)
field.  This results in the browser flushing that path from it's authorization
cache, effectively requiring new authorization information the next time that
path is accessed.

<P> The basic procedure is as follows.

<LIST>(NUMBERED)

<COMMENT>(HTML=<P>)

<LE> Add the query string <QUOTE>(?httpd=cancel) to the path in question (if
there is an existing query then replace it), as in the following example.

<CODE_EXAMPLE>
  /the/current/path?httpd=cancel
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> The browser will respond with an authorization failure, and prompting to
retry or reenter the username and password.

<COMMENT>(HTML=<P>)

<LE> It is necessary to clear at least the password (i.e. remove any password
from the appropriate field) and reenter.

<COMMENT>(HTML=<P>)

<LE> The browser again responds with an authorization failure.

<COMMENT>(HTML=<P>)

<LE> At this stage the authorization dialog can be cancelled, resulting in a
server authorization failure message.

<COMMENT>(HTML=<P>)

<LE> The original path can now be returned to and reaccessed.  The browser
should again prompt for authorization information at which point different
credentials may be supplied.

<ENDLIST>

<COMMENT>(..................................................................)
