Overview
Opmantek Applications released after 22 Feb 2017 support a new authentication method called token
, which offers delegated authentication: an external party can pre-authenticate a user, who can access the Opmantek applications without having to log in with username and password.
How does it work?
The core idea is similar to Kerberos: the Opmantek application and the external party share a cryptographic key, and thus a trust relationship is established. When the external party is satisfied that a user should be pre-authenticated for Opmantek apps, then it uses that shared key to create a 'token' or 'ticket', which the user can present to the Opmantek application in lieu of logging in interactively; if the ticket verifies as valid, the Opmantek application accepts the user as authenticated and logged in.
Configuration
To enable token authentication, a few configuration settings must be added to conf/opCommon.nmis
:
- One or more shared keys must be set up,
- the maximum validity for tokens may be specified optionally,
- and finally, the authentication method
token
must be added as one of the three supported authentication methods.
Here is an example opCommon.nmis
snippet, showing just the relevant items:
'authentication' => { # skipped other stuff... 'auth_method_1' => 'token', 'auth_method_2' => 'htpasswd', 'auth_method_3' => '', 'auth_token_key' => [ 'whateverSuitsU!', 'ForAnotherTrustedTP', ], 'auth_token_maxage' => 100,
The auth_token_key
list specifies which shared keys should be accepted and tried in sequence. Setting just one key is ok.
The auth_token_maxage
setting must be a positive number, and defines how long a token remains valid after creation (in seconds). If not set, the default of 300 seconds is used.
The token
authentication method is active if and only if one of the auth_method_1
, 2 or 3 entries is set to token
. Please note that it is not relevant which of the three is set to token; The token
method is ignored when the normal username and password login form is used, and other methods are ignored if the token access URL is visited (see next section).
Generating a Token
Our applications ship with a small token generator helper in /usr/local/omk/bin/generate_auth_token.pl
(plus the same code but compiled into a standalone .exe
file in the same location).
This token generator must be passed the shared key to use, and the username to generate a token for. The encrypted token is set up with and for that username and also containing the current time (in UTC), and the resulting token is printed, as in the following example:
$ /usr/local/omk/bin/generate_auth_token.pl 'whateverSuitsU!' operator 53616c7465645f5fd95eadb039692ea599441f8089daf1d7f04ab9ccf479e37fb3afda85b3044f4cde5b15844e9be616
Token length varies depending on the username, and each execution will create a different token. Please note that if your shared key contains shell metacharacters (like "!" in the example above) you will have to quote them when passing them to the example token generator.
Logging in with a Token
To use a token with an Opmantek application, the token generating party should provide the user with a URL in the following format:
http://<yourserver>/omk/<applicationkey>/login/<token>
. As a concrete example, to access opCharts with the token from before we'd use
https://testsystem1.opmantek.com/omk/opCharts/login/53616c7465645f5fd95eadb039692ea599441f8089daf1d7f04ab9ccf479e37fb3afda85b3044f4cde5b15844e9be616
If your system is configured for secure HTTP then it's fine to use https://
.
When the user visits this URL with their browser, the authentication subsystem detects the presence of a token and attempts to verify it. If a suitable shared key exists to decrypt the token and if the token is not too old, then authentication succeeds, suitable cookies are created and returned and the user is redirected to the main page for the given application.
If the token is invalid, the user is shown the classic login form, with a suitable error message.
Token Format and Interoperability Notes
TBC
what goes in, time seconds string, space, username
passphrase derived key, openssl-compatible salted header mode, pkcs#5 padding, finally hex-encoded.
Limitations
TBC
- no n-tries lockout
- time synchronisation critical
- token works any number of times, as long as within the validity period
Code Examples
Perl
plain openssl CLI