Date: Fri, 29 Mar 2024 11:53:19 +0000 (UTC) Message-ID: <355667695.4129.1711713199524@skald.opmantek.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_4128_872199358.1711713199524" ------=_Part_4128_872199358.1711713199524 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Opmantek Applications released after 22 Feb 2017 support a new authentic=
ation method called token
, which offers delegated authent=
ication: an external party can pre-authenticate a user, who can access the =
Opmantek applications without having to log in with username and password.<=
/p>
To enable token authentication, a few configuration settings must be add=
ed to /usr/local/omk/conf/opCommon.nmis
for legacy modules or =
/usr/local/omk/conf/opCommon.json
for current:
auth_token_key
,<=
/li>
a=
uth_token_maxage
,token
must be =
added as one of the three supported authentication methods.Once these changes are made, the Opmantek daemon must be restarted (
Here is an example opCommon.nmis
snippet, showing just=
the relevant items:
'authentication' = =3D> { # skipped other stuff... 'auth_method_1' =3D> 'token', 'auth_method_2' =3D> 'htpasswd', 'auth_method_3' =3D> '', 'auth_token_key' =3D> [ 'whateverSuitsU!', 'ForAnotherTrustedTP', ], 'auth_token_maxage' =3D> 100,
The auth_token_key
list specifies which shared k=
eys should be accepted and tried in sequence. Setting just one key is ok. I=
f you have multiple external parties that you want to delegate authenticati=
on duties to, then it is recommended that you give each their own key.
The auth_token_maxage
setting must be a positive=
number, and defines how long a token remains valid after creation (in seco=
nds). If not present, the default of 300 seconds is used.
The token
authentication method is active if and only if on=
e of the auth_method_1
, 2 or 3 entries is set to to=
ken
. Please note that it is not relevant which of the three is set t=
o token; the token
method is ignored when the normal user=
name and password login form is used, and conversely the other methods are =
ignored if the token access URL is visited (see next section).
Opmantek applications released after May 2017 ship with a small token ge=
nerator helper in /usr/local/omk/bin/generate_auth_token.pl (and also compiled into a standalone
.exe
program, in the s=
ame location).
This token generator must be passed the shared key to use, and the usern= ame to generate a token for. The encrypted token is created with and for th= at username and contains the current time (in UTC). Finally, the generator = prints the resulting token, as in the following example:
$ /usr/local/omk/= bin/generate_auth_token.pl 'whateverSuitsU!' operator 53616c7465645f5fd95eadb039692ea599441f8089daf1d7f04ab9ccf479e37fb3afda85b30= 44f4cde5b15844e9be616
Token length varies depending on the username, and each execution does c= reate a different token. Please note that if your shared key contains shell= metacharacters (like "!" in the example above) you will have to quote them= with single quotes when passing them to the token generator.
To use a token with an Opmantek application, the token generating party =
should direct the user to a URL in the following format: http://<y=
ourserver>/omk/<applicationkey>/login/<token>
. <=
/p>
As a concrete example, to access opCharts with the token from before we'=
d usehttps://testsystem1.opmantek.com/omk/opCharts/login/53616c74=
65645f5fd95eadb039692ea599441f8089daf1d7f04ab9ccf479e37fb3afda85b3044f4cde5=
b15844e9be616
If your system is configured for secure HTTP then it's fine to use =
https://
. Token authentication works for all commercial Opmant=
ek applications (e.g. application keys opEvents
, opConfi=
g
and so on).
When the user accesses this URL using their browser, the authentication =
subsystem detects the presence of a token and attempts to verify it. If a s=
uitable shared key was configured on the receiving system, and if the token=
could be decrypted and is not too old, then authentication succeeds, suita=
ble cookies are created and returned, and the user is redirected to the mai=
n page for the given application.
If the token is invalid, the user is shown the classic login form, with a s=
uitable error message.
If you need to direct the user to a particular page rather than their De= fault page/Dashboard you can extend the authentication URL with "?redirect_= url=3D" for example with the token above we can direct someone direct= ly to the topn page as follows:
https://testsystem1.opmantek.com/omk/opCharts/l=
ogin/53616c7465645f5fd95eadb039692ea599441f8089daf1d7f04ab9ccf479e37fb3afda=
85b3044f4cde5b15844e9be616?redirect_url=3D/omk/opCharts/topn
Once the client has accessed the first page, they have been issued auth = cookies and all standard URLs work without the token string in the URL.&nbs= p; You will want to consider how the user is handled to re-authenticate the= m if the session expires.
We can make API requests against the Opmantek product by passing your ge= nerated token within the header of your request.
Authorization: To= ken <data>
The "payload" data of the token consists of
This data is then encrypted symmetrically using the shared key, with the= following parameters:
auth_token_key
is used as passphra=
se to derive the actual key, not as a literal binary 128-bit key.The resulting encrypted data is binary, and must be encoded for use as a=
URL component.
The encoding is a trivial hex-encoding: each binary byte is replaced by its=
representation as two hexadecimal digits.
auth.log
.The following block contains essentially the same code as the token gene=
rator shipped as bin/generate_auth_token.pl
:
#!/usr/bin/perl use strict; use Crypt::CBC; my ($key, $username, $tokentime) =3D @ARGV; die "Usage: $0 <key> <username> [timestamp] key: passphrase of arbitrary length. timestamp: optional, default: now\n" if (!$key or !$username or (defined $tokentime && !int($tok= entime))); $tokentime ||=3D time; # what goes into the token? the token time stamp (in unix-seconds, UTC), # as a plain string, followed by exactly one space and the username. my $plain =3D $tokentime." ".$username; # defaults: RFC2898/pkcs#5 padding, openssl-compatible salted header mode, # and openssl-compatible key derivation function (PBKDF) - # see https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html # but crypt::cbc's default keysize is an incompatible 64 bits my $engine =3D Crypt::CBC->new(-key =3D> $key, -cipher =3D> "R= ijndael", -keysize =3D> 1= 28/8); my $crypted =3D $engine->encrypt_hex($plain); print $crypted,"\n"; exit 0;
The following small shell script requires the openssl
=
command line tool and hexdump
to perform the token genera=
tion (with the key being the first argument, username second):
#!/bin/sh KEY=3D$1 USER=3D$2 TEMPFILE=3D`mktemp /tmp/gentoken.XXXXXX` NOW=3D`date +%s` echo -n "$NOW $USER" > $TEMPFILE # see man enc: -salt -e are default, could be omitted; # openssl requires a real file as input, so we need a temp file # hexdump converts the binary bytes into their hex representation openssl aes-128-cbc -in $TEMPFILE -salt -e -pass "pass:$KEY" | \ hexdump -v -e '/1 "%02x"' echo rm -f $TEMPFILE exit 0
Python's pycrypto module should contain everything required, excep= t the OpenSSL-specific PBKDF which can be found here.