Overview

...

To enable token authentication, a few configuration settings must be added to to /usr/local/omk/conf/opCommon.nmis for legacy modules or /usr/local/omk/conf/opCommon.json for current:

1. One or more shared keys must be set up in auth_token_key,
2. optionally, the maximum validity for tokens may be specified in auth_token_maxage,
3. and finally, the authentication method token must be added as one of the three supported authentication methods.

...

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 conversely the other methods are ignored if the token access URL is visited (see next section).

Generating a Token

Our Opmantek applications released after May 2017 ship with a small token generator helper in /usr/local/omk/bin/generate_auth_token.pl (and also compiled into a standalone .exe program, in the same location).

...

If your system is configured for secure HTTP then it's fine to use https://. Ttoken Token authentication works for all commercial Opmantek applications (e.g. application keys opEvents, opConfig 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 suitable shared key was configured on the receiving system, and if the token could be decrypted and 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.

If you need to direct the user to a particular page rather than their Default page/Dashboard you can extend the authentication URL with "?redirect_url="  for example with the token above we can direct someone directly to the topn page as follows:

https://testsystem1.opmantek.com/omk/opCharts/login/53616c7465645f5fd95eadb039692ea599441f8089daf1d7f04ab9ccf479e37fb3afda85b3044f4cde5b15844e9be616?redirect_url=/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.  You will want to consider how the user is handled to re-authenticate them if the session expires.

Using the token based authentication in the header

We can make API requests against the Opmantek product by passing your generated token within the header of your request.

Authorization: Token <data>

Token Content and Interoperability Notes

...

• The token authentication system does not support locking out users after N unsuccessful login attempts.
• As the token contains the current time at the creating system and is valid for a limited time only, reasonably precise time synchronisation is critical for this method to work.
  If a token could be decrypted but was rejected because it was deemed too old, then a suitable log entry is written to the auth.log.
• Tokens are not single-use: a token works any number of times as long as it is presented within the configured validity period.

Code Examples for Token Generation

Perl

The following block contains essentially the same code as the token generator shipped as bin/generate_auth_token.pl:

#!/usr/bin/perl
use strict;
use Crypt::CBC;

my ($key, $username, $tokentime) = @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($tokentime)));
$tokentime ||= 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 = $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 incompatiblyincompatible 64 bits
my $engine = Crypt::CBC->new(-key => $key,
                                                         -cipher => "Rijndael",
                                                         -keysize => 128/8);
my $crypted = $engine->encrypt_hex($plain);

print $crypted,"\n";
exit 0;

Shell using the OpenSSL CLI

...

#!/bin/sh
KEY=$1
USER=$2
TEMPFILE=`mktemp /tmp/gentoken.XXXXXX`
NOW=`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

Python's pycrypto module should contain everything  required, except the OpenSSL-specific PBKDF which can be found  here.