4.1 Configuration |
4.2 Password Change |
4.3 Login Alias |
4.4 External Authentication Agent |
4.5 LOGIN.HTML |
4.6 CHANGE.HTML |
4.7 Access Log |
↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |
Access to private Mail via soyMAIL always requires user authentication. This may be performed as HTTP authorization by the supporting Web server (and passed as CGI variable REMOTE_USER), or by having soyMAIL maintain it's own authentication state. This section describes the latter.
The main advantage in allowing soyMAIL to manage it's own authentication environment is a clearly defined login-usage-logout life-cycle, something at best a kludge with HTTP authorization. It provides a one-click [logout] button that really works!
The client browser must support and have enabled HTTP cookie functionality. A cookie is used to store and propagate the authentication state. The cookie expires at the close of the browser. The cookie value is encrypted using the industry standard RC4 algorithm. This data is only present as plain values inside the processing of soyMAIL.
soyMAIL authentication
In addition soyMAIL
The internal authentication mechanism (site-specific, external authentication is possible, see 4.4 External Authentication Agent) depends on the VMS platform and version.
Further discussion will be confined to ACME authentication.
With autogenous authentication any account that can normally login to the supporting VMS system can access soyMAIL. To restrict an account it is necessary to deny access using the [private-access] directive (section 3.6 [private-access]).
Technical detail on the encryption algorithm, authentication code, cookie structure, etc., can be obtained from the descriptive prologue of the LOGIN.C source code module.
If Web server authorization for soyMAIL is currently configured then disable this before proceeding further. Behaviour with both enabled is indeterminate.
Autogenous authorization is enabled by configuring a value against the soyMAIL configuration directive [login-secret]. This is used as a key to encrypt the soyMAIL credential cookie value. When this directive has a value against it soyMAIL attempts to establish it's own authentication state. As this is an encryption key care should be taken to ensure it is
An example configuration might be
soyMAIL authentication will detect an expired password for DIALUP, LOCAL and REMOTE login types. ACME does report expiration for NETWORK (the default). An expired password will fail unless [login-no-pwdexp] is ENABLED or soyMAIL password change is configured and the password must be changed at login.
Password change is enabled by specifying the location of the change dialog HTML (also see 4.6 CHANGE.HTML). Using the default file that would be
As with authentication password change is either performed by ACME or a soyMAIL code path. The latter is rudimentary and does not include such desirable facets as dictionary and password history checking. Platforms without ACME available should avoid enabling password change.
The following configuration directives will modify the login type from the default NETWORK. Choose a type in-line with site policy.
[login-type] 3 | LOCAL |
[login-type] 4 | DIALUP |
[login-type] 5 | REMOTE |
For autogenous authentication the configuration directive [login-alias] allows the supplied user name string to be mapped to another string before being used for authentication. For example, this might allow the user email address, or local mailbox name, to be used as the user name and mapped to an actual VMS username before authenticating against the SYSUAF. In fact any arbitrary string can be mapped to any other. The alias mapping is performed using a case-insensitive match.
The format is one alias mapping per line, with the supplied user name to be matched on the left, a forward-slash, and the username to be authenticated against on the right.
If a match is not made and no mapping has occurred the default (drop-through) behaviour is to use the original supplied user name string and so in the above configuration both "Mark.Daniel" and "DANIEL" would authenticate against the DANIEL account, "Fred.Bloggs" and "BLOGGS" against BLOGGS. Of course any other supplied user name could also authenticate directly. To prevent any other than an aliased user name being used for authentication conclude the list with "*/-".
In the above example only "Mark.Daniel" and "Freg.Bloggs" can be authenticated.
The (somewhat redundant) mapping "*/*" will terminate alias processing and explicitly direct authentication to occur using the supplied user name (the default drop-through behaviour anyway).
The configuration directive [login-alias-smtp-from] when ENABLED uses any such mapped alias as the local part of a compose page self address ("From:") In this way an alias such as "Mark.Daniel" would be used to build an address Mark.Daniel@the.host.name
This provides a site-specific, external-to-soyMAIL authentication mechanism. If the [login-agent] configuration directive exists then it activates an external authentication DCL procedure within a subprocess. The DCL procedure must be specified following an '@' symbol and must have execute permission for the scripting account. For example
Optional parameters can be provided as part of the configuration directive:
When activated the procedure has a further three parameters appended to any supplied in the above configuration directive; "<username>", "<password>" and "<remote_addr>", to be used in the authentication processing.
The procedure should exit with any success status (e.g. SS$_NORMAL) to indicate successful authentication or any error status (e.g. SS$_NOPRIV) to indicate authentication failure.
This is a (very simple) example.
This would probably be more like a working one.
The HTML used in the login page is derived from a file. The default is [.THEME]LOGIN.HTML and contains a functional login form and layout. This can be customized to include a site theme, logo, information, etc. Care must be taken not to disturb any of the core functionality of the HTML form, form fields, etc.
So that subsequent updates to not overwrite modifications to the base LOGIN.HTML It is suggested to copy this to something like _LOGIN.HTML and then set that as the login page via soyMAIL configuration.
The HTML used by the password change page (see 4.2 Password Change) is also derived from a file. The default is [.THEME]CHANGE.HTML and contains the required elements to support the change dialog. Like the login page it can receive some customisation where care is taken not to disturb its core functionality.
As with the login page it is suggested a copy be modified and configured.
When autogenous authentication is in use the Web server does not perform the authorization function itself and as a result the 'remote user' datum, usually included in server-access logs, is not available. Which accounts are using soyMAIL is often useful or mandatory audit information and so soyMAIL provides this as a supplemental access log file.
A configuration directive enables the facility and allows a file specification to locate the log.
To assist in the maintenance of such logs soyMAIL will rotate the file name based on time using (perhaps familiar) formatting directives included in the configuration directive. For example, to include the year in a soyMAIL access log file name use
In a similar fashion, to include the month add a second numeric formatting string, and the day-of-month a third, as illustrated in the following two examples.
soyMAIL enables SYSPRV to access the file and so it may be located in a protected area of the file-system.
This file is provided in the NCSA-style 'combined' format only to allow processing by common access log file tools if desired. All fields are present and valid except the 'bytes' datum which always contains zero. Of course this log is only intended to supplement the server log, not supplant it.
↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |