|1Authorization Configuration (Basics)|

|^ 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.
|link%|../features/##Authentication and Authorization| of
|link%|../features/##|WASD Features and Facilities||
contains a detailed explanation of all
aspects.  All examples here assume a standard installation and environment.

|^ Just to clarify. |*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 that identity.

|^ Changes to the authorization configuration file can be validated at the
command-line before reload or restart.  This detects and reports any
syntactical and configuration errors but of course cannot check the
|/intent| of the rules.

|code|
$ HTTPD /DO=AUTH=CHECK
|!code|

|^ If additional server startup qualifiers are required to enable specific
authorization features then these must also be provided when checking.  For
example:

|code|
$ HTTPD /DO=AUTH=CHECK /SYSUAF /PROFILE
|!code|

|^ A server's currently loaded authorization rules may also be interrogated
from the Server Administration menu (see
|link%|../features/##Server Administration| of
|link%|../features/##|WASD Features and Facilities||).

|2SYSUAF/Identifier Authentication|

|^ 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.  The examples provided in
this section allows access to the WASD online Server Administration facility,
and so may be followed specifically for that purpose, as well as serve as a
general guide.

|bullet|

|item| 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
(|link%|../features/##Authentication Policy| of
|link%|../features/##|WASD Features and Facilities||).

|code|
$ DEFINE /SYSTEM WASD_STARTUP_SERVER "/SYSUAF=ID"
$ @|/device||:[WASD_ROOT.LOCAL]STARTUP.COM
|!code|

After a change to a command-line qualifier of the server such as the above
it needs to be restarted using the following directive.

|code|
$ HTTPD/DO=RESTART
|!code|

|item| Decide on an identifier name.  This can be an existing identifier, or
one created for the purpose.  For this example the identifier will be
"WASD_WEBADMIN".  Any identifier can be created using actions similar to the
following example.

|code|
$ SET DEFAULT SYS$SYSTEM
$ MCR AUTHORIZE
UAF> ADD /IDENTIFIER WASD_WEBADMIN
|!code|

|item| Modify the authorization configuration file, accessed by the server
using the system logical WASD_CONFIG_AUTH, to contain the following.  This
allows full access to the online Server Administration facility 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|
["Web Admin"=WASD_WEBADMIN=id]
/httpd/-/admin/* r+w
/wasd_root/local/* r+w
|!code|

|item| The identifier must then be granted to those accounts allowed to
authenticate in this way.

|code|
$ SET DEFAULT SYS$SYSTEM
$ MCR AUTHORIZE
UAF> GRANT /IDENTIFIER WASD_WEBADMIN SYSTEM
|!code|

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

|code|
["Web Admin"=WASD_WEBADMIN=id]
/wasd_root/local/* r+w
/httpd/-/admin/* r+w
["Area Access"=|/area-identifier-name||=id]
/web/area/* r+w ; r
|!code|

|^ Of course the one account may hold multiple identifiers and so may have
access to various areas.

|code|
UAF> GRANT /IDENTIFIER WASD_WEBADMIN SYSTEM
UAF> GRANT /IDENTIFIER |/area-identifier-name| SYSTEM
|!code|

|^ Using VMS rights identifiers allows significant granularity in providing
access.

|!bullet|

|0After Changes|

|^ If the WASD_CONFIG_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|
$ HTTPD/DO=AUTH=LOAD
$ HTTPD/DO=AUTH=PURGE
|!code|

|2Other Authentication|

|^ Other sources of authentication are available, either by themselves or used
in the same configuration file (different realms and paths) as those already
discussed
(|link%|../features/##Authentication Sources| of
|link%|../features/##|WASD Features and Facilities||).
Non-SYSUAF sources do not require any startup qualifier to be enabled.

|bullet|

|item| |*ACME| DOIs (Authentication and Credential Management Extension,
Domains of Interpretation) may be used to authenticate requests.

|code|
["Whatever you want to call it!"=|/doi||=ACME]
/web/area/* r+w
|!code|

|item| |*Simple lists| contain usernames and unencrypted passwords.  These are
plain-text files, created and modified using any desired editor.

|code|
["Whatever you want to call it!"=|/list-name||=list]
/web/area/* r+w
|!code|

|^ This is a |_very| simple arrangement, with little inherent security.  Lists
are more useful when grouping names together for specifying which group may do
what to where.

|item| |*HTA databases| are WASD-specific, binary repositories of usernames,
encrypted passwords, capabilities, user and other detail.

|code|
["Whatever you want to call it!"=|/HTA-database-name||=HTA]
/web/area/* r+w
|!code|

|^ These databases may be administered using the online Server Administration
facility
(|link%|../features/##HTTPd Server Revise| of
|link%|../features/##|WASD Features and Facilities||).
 
or the HTAdmin command-line utility
(|link%|../features/##HTAdmin| of
|link%|../features/##|WASD Features and Facilities||).

are quite secure and versatile.

|item| |*External agents| 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 its own, custom authorization agent.

|code|
["Whatever you want to call it!"=|/agent-name||=agent]
/web/area/* r+w
|!code|

Two variations on a versatile LDAP authenticator and a CEL-compatible
authenticator, along with example code is available in the
|link%|/wasd_root/src/agent/"|WASD_ROOT:[SRC.AGENT]| directory.

|item| |*X.509| establishes identity based on Public Key
Infrastructure (PKI) authentication certificates.  This is only available for
SSL transactions.

|code|
[X509]
/web/area/* r+w
|!code|

|item| |*RFC1413| IETF document describes an identification protocol that can
be used as a form of |/authentication| within this realm.

|code|
["Whatever you want to call it!"=RFC1413;A_PROJECT=list]
/web/area/* r+w ; r
|!code|

|!bullet|

|2Read and Write Groupings|

|^ WASD allows separate sources for groups of usernames to control read and
write access in a particular realm
(|link%|../features/##Realm, Full-Access, Read-Only| of
|link%|../features/##|WASD Features and Facilities||).

|^ 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|
["Realm Name"=|/identifier_name||=id;|/full_access_name||=list;|/read-only_name||=list]
/web/area/* r+w ; 
/web/another-area/* r+w ; r
|!code|

|2Considerations|

|^ Multiple authentication sources (realms) may be configured in the one
WASD_CONFIG_AUTH file.

|^ Multiple paths may be mapped against a single authentication source.

|^ Any path may be mapped only once (for any single virtual service).

|^ Paths may have additional access restrictions placed on them, including
client host name, username, etc.
(|link%|../features/##Access Restriction Keywords| of
|link%|../features/##|WASD Features and Facilities||).

|^ 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|
$ HTTPD/DO=AUTH=LOAD
|!code|

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

|code|
$ HTTPD/DO=AUTH=PURGE
|!code|

|^ 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|
$ HTTPD/DO=AUTH=PURGE
|!code|