WASD VMS Web Services - Features and Facilities

3 - Authentication and Authorization

3.1 - Rule Interpretation 3.2 - Authentication Policy 3.3 - Permissions, Path and User 3.4 - Authorization Configuration File 3.5 - Authentication Sources 3.6 - Realm, Full-Access, Read-Only 3.7 - Virtual Servers 3.8 - Authorization Configuration Examples 3.8.1 - KISS 3.9 - Authorization Cache 3.10 - SYSUAF-Authenticated Users 3.10.1 - ACME 3.10.2 - Logon Type 3.10.3 - Rights Identifiers 3.10.4 - WASD "Hard-Wired" Identifiers 3.10.5 - VMS Account Proxying 3.10.6 - Nil-Access VMS Accounts 3.10.7 - SYSUAF and SSL 3.10.8 - SYSUAF Security Profile 3.10.9 - SYSUAF Profile For Full Site Access 3.11 - Token Authentication 3.12 - Skeleton-Key Authentication 3.13 - Controlling Server Write Access 3.14 - Securing All Requests 3.15 - User Password Modification 3.16 - Cancelling Authorization
next previous contents full-page

Authentication is the verification of a user's identity, usually through username/password credentials. Authorization is allowing a certain action to be applied to a particular path based on authentication of the originator.

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.

Basic authorization was discussed in "WASD VMS Web Services - Install and Config"; 13 - Authorization Configuration (Basics) WASD Web Services - Install and Config ). This section discusses all the aspects of WASD authentication and authorization.

Overview

By default, the logical name WASD_CONFIG_AUTH locates a common authorization rule file. Simple editing of the file and reloading into the running server changes the processing rules.

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 ... WASD HTTPd authorization administration involves those two aspects, setting authorization against paths and administering the authentication and authorization sources.

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.

Where a request will result in script activation, authorization is performed on both script and path components. 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 "WASD VMS Web Services - Install and Config"; 12.5.5 - SET Rule WASD Web Services - Install and Config ).

The authentication source name is refered to as the realm, and refers to a collection of usernames and passwords. It can be the system's SYSUAF database.

The authorization source is refered to as the group, and commonly refers to a collection of usernames and associated permissions.

3.1 - Rule Interpretation

The configuration file rules are scanned from first towards last, until a matching rule is encountered (or end-of-file). Generally a rule has a trailing wildcard to indicate that all sub-paths are subject to the same authorization requirements.

String Matching

Rule matching is string pattern matching, comparing the request specified path, and optionally other components of the request when using configuration conditionals (see "WASD VMS Web Services - Install and Config"; 7 - Conditional Configuration WASD Web Services - Install and Config ), to a series of patterns, until one of the patterns matches, at which stage the authorization characteristics are applied to the request and authentication processing is undertaken. If a matching pattern (rule) is not found the path is considered not to be subject to authorization. Both wildcard and regular expression based pattern matching is available (see "WASD VMS Web Services - Install and Config"; 6 - String Matching WASD Web Services - Install and Config ).

3.2 - Authentication Policy

A policy regarding when and how authorization can be used may be established on a per-server basis. This can restrict authentication challenges to "https:" (SSL) requests (4 - Transport Layer Security), thereby ensuring that the authorization environment is not compromised by use in non-encrypted transactions. Two server qualifiers provide this.

Note also that individual paths may be restricted to SSL requests using either the mapping conditional rule configuration or the authorization configuration files. See "WASD VMS Web Services - Install and Config"; 12.9 - Conditional Mapping WASD Web Services - Install and Config and Access Restriction Keywords.

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

Authentication Failures

Details of authentication failures are logged to the server process log.

Failures may also be directed to the OPCOM facility (see "WASD VMS Web Services - Install and Config"; 4.11 - OPCOM Logging WASD Web Services - Install and Config ).

3.3 - Permissions, Path and User

Both paths and usernames have permissions associated with them. 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.

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

HTTP Methods
Path/UserDELETEGETHEADPOSTPROPFINDPUTOther WebDAV
READ or Rnoyesyesnoyesnono
WRITE or Wyesnonoyesnoyesyes
R+Wyesyesyesyesyesyesyes
NONEnonononononono
DELETEyesyesnonononono
GETnoyesnonononono
HEADnonoyesnononono
POSTnononoyesnonono
PROPFINDnonononoyesnono
PUTnoyesnononoyesno
Other WebDAVnonononononoyes

3.4 - Authorization Configuration File

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.

By default, the system-table logical name WASD_CONFIG_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 "#" character, and lines continued by placing the backslash character "\" as the last character on a line.

The [IncludeFile] is a directive common to all WASD configuration, allowing a separate file to be included as a part of the current configuration. See (see "WASD VMS Web Services - Install and Config"; 4.1 - Include File Directive WASD Web Services - Install and Config ).

Configuration directives begin either with a "[realm]", "[realm;group]" or "[realm;group-r+w;group-r]" specification, with the forward-slash of a path specification, or with a "[AuthProxy]" or "[AuthProxyFile]" introducing a proxy mapping. Following the path specification are HTTP method keywords controlling group and world permissions to the path, and any access-restricting request scheme ("https:") and/or host address(es) and/or username(s).

The same path cannot be specified against two different realms for the same virtual service. 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.

There is a thirty-one character limit on authentication source names.

Reserved Names

The following realm names are reserved and have special functionality.

Reserved Username

The following username is reserved.

Access Restriction Keywords

If a host name, protocol identifier or username is included in the path configuration directive it acts to further 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. In addition a VMS security profile may be associated with the request.

For example
/web/secret/* *.three.stooges,~Moe,~Larry,~Curly,read
restricts read access to Curly, Larry and Moe accessing from within the three.stooges network, while
/web/secret/* https:,*.three.stooges,~Moe,~Larry,~Curly,read
applies the further restriction of access via "https:" (SSL) only.

These examples show the use of a network mask to restrict based on the source network of the client. The first, four octets supplied as a mask. The second a VLSM used to specify the length of the network component of the address.

/web/secret/* https:,#131.185.250.128/255.255.255.192,~Moe,~Larry,~Curly,read

/web/secret/* https:,#131.185.250.128/26,~Moe,~Larry,~Curly,read

These examples both specify a 6 bit subnet. With the above examples the host 131.185.250.250 would be accepted, but 131.185.250.50 would be rejected.

Note that it more efficient to place protocol and host restrictions at the front of a list.

3.5 - Authentication Sources

Authentication credentials may be validated against one of several sources, each with different characteristics.

Multiple Source Types

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

Realm Description

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.

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.

["the local host"=VMS]
["Social Club"=SOCIAL_CLUB_RW=id]
["Finance Staff"=FINANCE=list]
["Just Another Database"=DBACCESS=hta]
NOTE

The 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.

3.6 - Realm, Full-Access, Read-Only

WASD authorization offers a number of combinations of access control. This is a summary. Please note that when refering to the 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 3.3 - Permissions, Path and User.

3.7 - Virtual Servers

As described in "WASD VMS Web Services - Install and Config"; 4.3 - Virtual Services WASD Web Services - Install and Config ), 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.

# authorization rules example for virtual servers
[[alpha.example.com: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.example.com:80]]
# BETA has its own HTA database
[BETA_USER=hta]
/web/* r+w ; r
[[gamma.example.com: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

The online Server Administration facility path authorization report (9.4 - HTTPd 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.

3.8 - Authorization Configuration Examples

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.

  1. In the following example the authentication realm is "WASD", a synonym for SYSUAF authentication, and the permissions group "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.
    [WASD=vms;SOCIALCLUB=list]
    /web/socialclub/* r+w ; read
    
  2. 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, "BLOGGS".
    [WASD=vms;SOCIALCLUB=list]
    /web/socialclub/* 131.185.45.*,get,post; *.example.com,get
    /web/socialclub/accounts/* 131.185.45.*,~BLOGGS,get,post; *.example.com,get
    
  3. 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.
    [DEVELOPER=id;PROJECT_A_LIBRARIAN=id;PROJECT_A_USER=id]
    /web/projects/a/*  r+w
    /web/projects/*    r
    
  4. This example is the same as the one above, except in this case everyone else (that can authenticate against the resource) gets read-only access to the projects.
    [DEVELOPER=id;PROJECT_A_LIBRARIAN=id;*]
    /web/projects/a/*  r+w
    /web/projects/*    r
    
  5. In the following example the authentication realm and group are a single HTA database, "ADMIN". The first directive allows those in the ADMIN group to read and write, and the world to read ("get,post;get"). The second line restricts write and even read access to ADMIN group, no world access at all ("get,post").
    [ADMIN=hta]
    /web/everyone/* get,post;get
    /web/select/few/* get,post
    
  6. 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, "The Company".
    ["The Company"=COMPANY=hta]
    /web/docs/* ~Howard,~George,~Fred,r+w ; r
    /web/accounts/* ~George,r+w ; r
    
  7. The following example shows a path specifying the local system's SYSUAF being used to authenticate any usernames. Whenever using SYSUAF authentication it is strongly recommended to limit the potential hosts that can authenticate in this way by always using a host-limiting access restriction list. The world gets read access.
    [VMS]
    /web/local/area/* 131.185.250.*,r+w ; r
    
  8. 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.
    ["not the VMS SYSUAF"=VMS]
    /httpd/-/admin/*  #localhost,~daniel,r+w
    
  9. This example uses the RFC1413 identification protocol as the authentication source and a host group to control full access to paths in the realm.
    ["Ident Protocol"=RFC1413;131.185.250.0/24]
    /web/local/* r+w
    
  10. The following example illustrates providing a read and writable area (GET, POST and PUTable) to hosts in the local network without username authentication (careful!).
    [WORLD]
    /web/scratch/*  *.local.hosts.only,r+w
    

3.8.1 - KISS

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.

Fortunately great complexity is not generally necessary.

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.

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, "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:

# 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
The authorization configuration file then contains:
#######################################################################

# allow web masters (!) to use the server administration facility
#                       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
/wasd_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 

#######################################################################

3.9 - Authorization Cache

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.

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.

Implication

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.

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.

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 (9.7 - HTTPd Command Line) or via the Server Administration facility (9 - Server Administration). Of course the other solution is just to disable caching, which is a less than optimal solution.

3.10 - SYSUAF-Authenticated Users

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

WARNING!

SYSUAF authentication is not recommended except in the most secure of LAN environments or when SSL is employed.

HTTP credentials (username and password) are transmitted as encoded plain-text making them vulnerable to evesdropping.


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 3.10.3 - Rights Identifiers immediately below. Accounts that are disusered, have passwords that have expired or that are captive or restricted are always rejected. Accounts that have access day/time restricting access will have those restrictions honoured (see 3.10.3 - Rights Identifiers for a workaround for this).

Also see 3.10.6 - Nil-Access VMS Accounts.

3.10.1 - ACME

By default the Authentication and Credential Management Extension (ACME) is used to authenticate SYSUAF requests on Alpha and Itanium running VMS V7.3 or later (3.5 - Authentication Sources). VAX and earlier versions of VMS use WASD's own SYSUAF authentication routines. The advantage of ACME is with the processing of the (rather complex) authentication requirements by a vendor-supplied implementation. It also allows SYSUAF password change to be made subject to the full site policy (password history, dictionary checking, etc.) which WASD does not implement.

3.10.2 - Logon Type

By default SYSUAF authentication uses the NETWORK access restriction from the account SYSUAF record. Alternatives LOCAL, DIALUP and REMOTE may be specified using global configuration directive

# WASD_CONFIG_GLOBAL
[AuthSYSUAFlogonType]  REMOTE
and/or authorization rule parameter 'param="logon=REMOTE"'
["VMS Credentials"=WASD_VMS_RW=ID]
/secured/* r+w,https,param="logon=REMOTE"
(which takes precedence).

3.10.3 - Rights Identifiers

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.

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

The first three reserved identifier names are optional. A warning will be reported during startup if these are not found. The fourth must exist if SYSUAF proxy mappings are used in a /SYSUAF=ID environment.

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.

$ 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

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

UAF> GRANT /IDENTIFIER PROJECT_USER <account>

and removed using:

UAF> REVOKE /IDENTIFIER PROJECT_USER <account>

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 (3.9 - Authorization Cache).

3.10.4 - WASD "Hard-Wired" Identifiers

Deprecated and Discouraged

As this has been deprecated for some years now the documentation for this functionality has been removed.

For backward-reference see the "WASD Hypertext Services - Technical Overview" document for release v9.3 or earlier.


3.10.5 - VMS Account Proxying

Any authentication realm can have its usernames mapped into VMS usernames and the VMS username used as if it had been authenticated from the SYSUAF. This is a form of proxy access.

CAUTION

This is an extremely powerful mechanism and as a consequence requires enabling on the command-line at server startup using the /SYSUAF=PROXY qualifier and keyword. If identifiers are used to control SYSUAF authentication (i.e. /SYSUAF=ID) then any account mapped by proxy access must hold the WASD_PROXY_ACCESS identifier described in 3.10.3 - Rights Identifiers (and server startup would be something like "/SYSUAF=(ID,PROXY)").


When a proxy mapping occurs request user authorization detail reflects the SYSUAF username characteristics, not the actual original authentication source. This includes username, user details (i.e. becomes that derived from the owner field in the SYSUAF), constraints on the username access (e.g. SSL only), and user capabilities including any profile if enabled. Authorization source detail remains unchanged, reflecting the realm, realm description and group of the original source. For CGI scripting an additional variable, WWW_AUTH_REMOTE_USER, provides the original remote username.

For each realm, and even for each path, a different collection of mappings can be applied. Proxy entries are strings containing no white space. There are three basic variations, each with an optional host or network mask component.

  1. remote[@host|@network/mask]=SYSUAF
  2. *[@host|@network/mask]=SYSUAF
  3. *[@host|@network/mask]=*

The SYSUAF is the VMS username being mapped to. The remote is the remote username (CGI variable WWW_REMOTE_USER). The first variation maps a matching remote username (and optional host/network) onto the specific SYSUAF username. The second maps all remote usernames (and optional host/network) to the one SYSUAF username (useful as a final mapping). The third maps all remote usernames (optionally on the remote host/network) into the same SYSUAF username (again useful as a final mapping if there is a one-to-one equivalence between the systems).

Proxy mappings are processed sequentially from first to last until a matching rule is encountered. If none is found authorization is denied. Match-all and default mappings can be specified.

[RFC1413]
[AuthProxy] bloggs@131.185.250.1=fred
[AuthProxy] doe@131.185.250.*=john system=- *@131.185.252.0/24=*
[AuthProxy] *=GUEST

In this example the username bloggs on system 131.185.250.1 can access as if the request had been authenticated via the SYSUAF using the username and password of FRED, although of course no SYSUAF username or password needs to be supplied. The same applies to the second mapping, doe on the remote system to JOHN on the VMS system. The third mapping disallows a system account ever being mapped to the VMS equivalent. The fourth, wildcard mapping, maps all accounts on all systems in 131.185.250.0 8 bit subnet to the same VMS username on the server system. The fifth mapping provides a default username for all other remote usernames (and used like this would terminate further mapping).

Note that multiple, space-separated proxy entries may be placed on a single line. In this case they are processed from left to right and first to last.

["Just an Example"=EXAMPLE=list]
[AuthProxy] bloggs@131.185.250.1=fred doe@131.185.250.1=doe system=- \
*@131.185.252.0/24=* *=GUEST

Proxy mapping rules should be placed after a realm specification and before any authorization path rules in that realm. In this way the mappings will apply to all rules in that realm. It is possible to change the mappings between rules. Just insert the new mappings before the (first) rule they apply to. This cancels any previous mappings and starts a new set. This is an example.

["A Bunch of Users"=USERS=hta]
[AuthProxy] bloggs@131.185.250.1=fred doe@131.185.250.1=john
/fred/and/johns/path/* r+w
[AuthProxy] *=GUEST
/other/path/* read

An alternative to in-line proxy mapping is to provide the mappings in one or more independent files. In-line and in-file mappings may be combined.

["Another Bunch of Users"=MORE_USERS=hta]
[AuthProxy] SYSTEM=-
[AuthProxyFile]  WASD_ROOT:[LOCAL]PROXY.CONF
/path/for/proxy* r+w

To cancel all mappings for following rules use an [AuthProxy] (with no following mapping detail). Previous mappings are always cancelled with the start of a new realm specification. Where proxy mapping is not enabled at the command line or a proxy file cannot be loaded at startup a proxy entry is inserted preventing all access to the path.

REMEMBER - proxy processing can be observed using the WATCH facility.

3.10.6 - Nil-Access VMS Accounts

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.

In setting up such an environment it is vital to ensure the HTTPd server is started using the /SYSUAF=ID qualifier (3.2 - Authentication 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 (3.10.3 - Rights Identifiers), allowing the account to authenticate despite being restricted by REMOTE and NETWORK time restrictions.

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 3.10.3 - Rights Identifiers above).

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

3.10.7 - SYSUAF and SSL

When SSL is in use (4 - Transport Layer Security) 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 WASD_CONFIG_MAP configuration file:

/whatever/path/you/like/*  "403 Access denied."  ![sc:https]
or alternatively the following to the WASD_CONFIG_AUTH configuration file:
[REALM]
/whatever/path/you/like/*  https:

Note that this mechanism is applied after any path and method assessment made by the server's authentication schema.

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.

Also see 3.2 - Authentication Policy.

3.10.8 - SYSUAF Security Profile

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.

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 (3.9 - Authorization 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 (9.6 - HTTPd Server Action).

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 "no privilege" error is generated.

Once enabled using /PROFILE it can be applied to all SYSUAF authenticated paths, but must be enabled on a per-path basis, using the WASD_CONFIG_AUTH profile keyword (Access Restriction Keywords)

# WASD_CONFIG_AUTH
[VMS;VMS]
/wasd_root/local/* profile,https:,r+w
or the WASD_CONFIG_MAP SET profile and noprofile mapping rules (see "WASD VMS Web Services - Install and Config"; 12.5.5 - SET Rule WASD Web Services - Install and Config ).
# WASD_CONFIG_MAP
set /wasd_root/local/* profile
set * noprofile

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, see WASD_ROOT:[SRC.MISC]CHKACC.C ) based on the CGI variable WWW_AUTH_REALM which would be "VMS" indicating SYSUAF-authentication, and the authenticated name in WWW_REMOTE_USER.

Performance Impact

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.

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

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

3.10.9 - SYSUAF Profile For Full Site Access

Much of a site's package directory tree is inaccessible to the server account. One use of the SYSUAF profile functionality is to allow authenticated accesss to all files in that tree. This can accomplished by creating a specific mapping for this purpose, subjecting that to SYSUAF authentication with /PROFILE behaviour enabled (3.10.8 - SYSUAF Security Profile), and limiting the access to a SYSTEM group account. As all files in the WASD package are owned by SYSTEM the security profile used allows access to all files.

The following example shows a path with a leading dollar (to differentiate it from general access) being mapped into the package tree. The "set * noprofile" limits the application of this to the /$WASD_ROOT/ path (with the inline "profile").

# WASD_CONFIG_MAP
set * noprofile
  .
  .
  .
pass /wasd_root/* /wasd_root/*
pass /$WASD_ROOT/* /wasd_root/* profile

This path is then subjected to SYSUAF authentication with access limited to an SSL request from a specific IP address (the site administrator's) and the SYSTEM account.

# WASD_CONFIG_AUTH
[["/$WASD_ROOT/ Access"=WASD_TREE_ACCESS=id]]
/$WASD_ROOT/* https,10.1.1.2,~system,read

3.11 - Token Authentication

This is a niche authorisation environment for addressing niche requirements.

A token is an HTTP cookie delivered representation of authentication established in another context. Originally devised to allow controlled access to very large datasets without the overhead of SSL in the transmission but with access credentials supplied in the privacy of an SSL connection.

A common scenario is where the client starts off attempting to access a resource in non-SSL space which is controlled by token authentication. In the first instance the authenticator detects there is no access token present and redirects the client (browser) to the SSL equivalent of that space, where credentials can be supplied encrypted. In this example scenario the SSL area is controlled by WASD SYSUAF authentication (can be SSL client certificate, etc.) and the username/password is prompted for. When correctly entered this generates a token. The token is stored (with corresponding detail) as a record in a server-internal database and then returned to the browser as a set-cookie value.

With the token data stored the browser is transparently redirected back to the non-SSL space where the actual access is to be undertaken, this time the browser presenting the cookie containing the token. The authenticator examines the token, looking it up in the database. If found, has originated from the same IP address, represents the same authentication realm, and has not expired, it then allows the non-SSL space access to proceed, and in this example scenario the dataset transfer is initiated (in unencrypted clear-text). If the token is not found in the database or has expired, then the process is repeated with a redirect back into SSL space. If the realms differ a 403 forbidden response is issued (see configuration below).

The token itself is a significant sequence of pseudo-random characters, is short-lived (configurable as anything from a few seconds to a few tens of seconds, or more), and as a consequence is frequently regenerated. The token is just that, containing no actual credential data at all. It might be possible to snoop but as it contains nothing of value in itself, expires relatively quickly, and has an originating IP address check, the fairly remote risk of playback is just that.

The authenticator does all the work, implicitly redirecting the user from non-SSL space to SSL space for the original authentication, and then back again with the token used for access in the non-SSL space. With the expiry of a token it undertakes that cycle again, redirecting back to the SSL-space where the browser-cached credentials will be supplied automatically allowing the fresh token to be issued, and then redirected back into non-SSL space for access. To emphasise - all this is transparent to the user.

As a consequence of this model the resource being controlled can ONLY be accessed from non-SSL space using the controlled path. To access the same resource from SSL space a distinct path to the resource must be provided.

Configuration

As token authorisation relies on the client agent having HTTP cookies enabled (globally or specifically for the site) it is useful to have this tested for and/or advised about, on some related but other area of the site. There are simple techniques using JavaScript for detecting the availability of cookie processing. Search the Web for a suitable solution.

The automatic authorisation and redirection occurs using a combination of two distinguishable authorisation rules, one for supplying the credentials, the other for using the token for authorisation. In this example (and commonly) the resources are at "/location/" and the configuration accepts user-supplied credentials in SSL space and uses the token in non-SSL space. The asterisk just indicates that in the absence of any other parameter this authorisation rule has a complementary token rule where access will actually occur.

# WASD_CONFIG_AUTH
if (ssl:) 
   ["VMS credentials"=WASD_VMS_RW=id+"TOKEN=*"]
   /location/* r+w
else
   [WASD_VMS_RW=TOKEN]
   /location/* r+w
endif

And in this example, the same arrangement but with non-standard ports (specified using an integer with a leading colon).

# WASD_CONFIG_AUTH
if (ssl:) 
   ["VMS credentials"=WASD_VMS_RW=id+"TOKEN=:7080"]
   /location/* r+w
else
   [WASD_VMS_RW=TOKEN+"TOKEN=:7443"]
   /location/* r+w
endif

To prevent potential thrashing, where multiple, distinct realms within a single request are authorised using tokens, corresponding multiple token (cookie) names must be used. It is expected that this would be an uncommon but not impossible scenario. The "thrashing" would be a result of authorisation associated with a single, particular token name. Where a realm differs from a previous token generated another is required. The token authorisation scheme forces the use of distinct token names by 403-forbidding change of realm using the one token. Use explicitly specified, independent token (cookie) names, or an integer preceded by an ampersand (which appends the integer to the base token name), ensuring the complementary rules are using the same name/integer.

# WASD_CONFIG_AUTH
if (ssl:) 
   ["VMS credentials"=WASD_VMS_RW=id+"TOKEN=&42"]
   /location/* r+w
else
   [WASD_VMS_RW=TOKEN+"TOKEN=&42"]
   /location/* r+w
endif

For the final example, the token is contained in the non-default cookie named "WaSd_example" and the authentication performed using an X509 client certificate (which can only be supplied via SSL).

# WASD_CONFIG_AUTH
if (ssl:) 
   [X509+"TOKEN=WaSd_example"]
   /location/* r+w
else
   [X509=TOKEN+"TOKEN=WaSd_example"]
   /location/* r+w
endif

Some additional detail is available from the AUTHTOKEN.C code module.

3.12 - Skeleton-Key Authentication

Provides a username and password that is authenticated from data placed into the global common (i.e. in memory) by the site administrator. The username and password expire (become non-effective) after a period, one hour by default or an interval specified when the username and password are registered.

It is a method for allowing ad hoc authenticated access to the server, primarily intended for non-configured access to the online Server Administration facilities (9.1 - Access Before Configuration) but is available for other purposes where a permanent username and password in an authentication database is not necessary. A skeleton-key authenticated request is subject to all other authorization processing (i.e. access restrictions, etc.), and can be controlled using the likes of '~_*', etc.

The site administrator uses the command line directive

$ HTTPD /DO=AUTH=SKELKEY=_username:password[:period]
to set the username/password, and optionally the period in minutes. This authentication credential can be cancelled at any time using
$ HTTPD /DO=AUTH=SKELKEY=0

The username must begin with an underscore (to reduce the chances of clashing with a legitimate username) and have a minimum of 6 other characters. The password is delimited by a colon and must be at least 8 characters. The optional period in minutes can be from 1 to 10080 (one week). If not supplied it defaults to 60 (one hour). After the period expires the skeleton key is no longer accepted until reset.

NOTE

Choose username and password strings that are less-than-obvious and a period that's sufficient to the task! After all, it's your site that you might compromise!

The authentication process (with skeleton-key) is performed using these basic steps.

  1. Is a skeleton-key set? If not continue on with the normal authentication process.
  2. If set then check the request username leading character for an underscore. If not then continue on with normal authentication.
  3. If it begins with an underscore then match the request and skeleton-key usernames. If they do not match then continue with normal authentication.
  4. If the usernames match then compare the request and skeleton-key passwords. If matched then it's authenticated. If not it becomes an authentication failure.

Note that the authenticator resumes looking for a username from a configured authentication source unless the request and skeleton-key usernames match. After that the passwords either match allowing access or do not match resulting in an authentication failure.

Examples

$ HTTPD /DO=AUTH=SKELKEY=_FRED2ACC:USE82PA55

$ HTTPD /DO=AUTH=SKELKEY=_ANDY2WERP:EGGO4TEE:10

3.13 - Controlling Server Write Access

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. This is in addition to the path authorization of the server itself of course! 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.

Two different ACEs implement two grades of access.

  1. If the ACE grants CONTROL 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.

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

    $ SET SECURITY directory.DIR -
      /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL)
    
    This example shows setting an ACE that will propagate to created files and importantly, subdirectories:
    $ 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))
    

  2. If the ACE grants WRITE access then the directory can be written into by any authenticated username for the authorized path.

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

    $ SET SECURITY directory.DIR -
      /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE)
    
    This example shows setting an ACE that will propagate to created files and importantly, subdirectories:
    $ SET SECURITY directory.DIR -
      /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+EXECUTE+DELETE), -
            (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE))
    

To assist with the setting of the required ACEs an example, general-purpose DCL procedure is provided, WASD_ROOT:[EXAMPLE]AUTHACE.COM.

3.14 - Securing All Requests

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.

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

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 "NONE" realm may be used. The following example provides some indication of how it should be used.

# 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 WASD_ROOT tree
/wasd_root/*

There is also a per-path equivalent of the /AUTHORIZE=ALL functionality, described in "WASD VMS Web Services - Install and Config"; 12.5.5 - SET Rule WASD Web Services - Install and Config . This allows a path tree to be require authorization be enabled against it.

# avoid an absence of authorization allowing unintentional access
set /web/sensitive/* auth=all

3.15 - User Password Modification

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 (which is why SSL is recommended).

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

pass /httpd/-/change/* /httpd/-/change/*

Any database to be enabled for password modification must have a writable authorization path associated with it. For example:

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

[ANOTHER_GROUP=id;ANOTHER_GROUP=id]
/httpd/-/change/another_group/* r+w
NOTE

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).

Use some form of cautionary wrapper if providing this functionality over something other than an Intranet or SSL connection:

<H2>Change Your Authentication</H2>

<blockquote>
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.
</blockquote>

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

Password Expiry

When using SYSUAF authentication it is possible for a password to pre-expired, or when a password lifetime is set for a password to expire and require respecification. By default an expired password cannot be used for access. This may be overridden using the following global configuration directive.

[AuthSYSUAFacceptExpPwd]  enabled

Expired passwords may be specially processed by specifying a URL with WASD_CONFIG_GLOBAL [AuthSysUafPwdExpURL] configuration directive (see "WASD VMS Web Services - Install and Config"; 8.2 - Alphabetic Listing WASD Web Services - Install and Config ).

The WASD_CONFIG_MAP set auth=sysuaf=pwdexpurl=<string> rule allows the same URL to be specified on a per-path basis. When this is set a request requiring SYSUAF authentication that specifies a username with an expired password is redirected to the specified URL. This should directly or via an explanatory (wrapper) page redirect to the password change path described above. The password change dialog will have a small note indicating the password has expired and allows it to be changed.

The following WASD_CONFIG_GLOBAL directive

# WASD_CONFIG_GLOBAL
[AuthSysUafPwdExpURL]  https:///httpd/-/change/

# WASD_CONFIG_AUTH
[WASD_VMS_ID=id;WASD_VMS_RW=id]
/httpd/-/change/* r+w
would allow expired passwords to be changed.

It is also possible to redirect an expired password to a site-specific page for input and change. This allows some customization of the language and content of the expired password change dialog. An example document is provided at WASD_ROOT:[EXAMPLE]EXPIRED.SHTML (what it looks like) ready for relocation and customisation. Due to the complexities of passing realm information and then submitting that information to the server-internal change facility some dynamic processing is required via an SSI document.

This example assumes the site-specific document has been located at WEB:[000000]EXPIRED.SHTML and is accessed using SSL.

# WASD_CONFIG_GLOBAL
[AuthSysUafPwdExpURL]  https:///web/expired.shtml?httpd=ignore&realm=vms

# WASD_CONFIG_AUTH
[WASD_VMS_ID=id;WASD_VMS_RW=id]
/httpd/-/change/vms/* r+w
/web/expired.shtml r+w

3.16 - Cancelling Authorization

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 purge authorization cache button, but this is commonly not the case. To provide this functionality the server must be used to "trick" the browser into cancelling the authorization information for a particular path.

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 "Authorization:" field. This results in the browser flushing that path from the authorization cache, effectively requiring new authorization information the next time that path is accessed.

There are two variations on this mechanism.

  1. The basic procedure is as follows:
  2. A little more functional, if using a revalidation period via [AuthRevalidateUserMinutes] or 'SET auth=revalidate=' (perhaps set to something like 23:59:00, or one day), when the logout query string is supplied the server resets the entry forcing any future access to require revalidation. A successful logout message is then generated, circumventing the need for the username/password dialog described above.

    Also when using logout with a revalidation period a redirection URL may be appended to the logout query string. It then redirects to the supplied URL. It is important that the redirection is returned to the browser and not handled internally by WASD. Normal WASD redirection functionality applies.

    ?httpd=logout&goto=///
    ?httpd=logout&goto=///help/logout.html
    ?httpd=logout&goto=http://the.host.name/
    

    These examples redirect to

    the local home page
    a specific local page
    a specific remote server

    respectively.

    Authentication Cache

    User revalidation relies on an entry being maintained in the authentication cache. Each time the entry is flushed, for whatever reason (cache congestion, command-line purge, server restart, etc.), the user will be prompted for credentials. It may be necessary to increase the size of the cache by adjusting [AuthCacheEntriesMax].



next previous contents full-page