Skip to main content
Skip table of contents

Set up OATH tokens in Digital Access

This article is valid for Digital Access component 6.1.2 and later.

This article describes how to import and assign OATH-compliant authentication tokens in Smart ID Digital Access component

OATH is an open standard for generating one-time passwords for user authentication. Before an OATH security token can be used for user authentication, you must import and assign it to a user account.

Step-by-step instruction

OATH tokens, description

Each OATH security token has a serial number, seed value, and a counter. The seed and counter values are used to calculate the next OTP and must be known to both the server and the OATH device and the serial number is used to create a binding between the OATH device and its seed and counter values. Digital Access component stores this information in an internal database and before a token can be assigned to a user, it needs to be imported to the database.

The easiest way to import tokens is by importing a text file containing the relevant information. We strongly recommend to use a base64 encoded format as described below.

Each OATH token device is associated with one line in the text file, and in this example, the values are ordered using “:” as the delimiter:

<serial number>:<seed value>:<counter value>

Example of text file


Each line has three information holders; position 0, position 1 and position 2. In the example above, position 0 holds the device serial number (LAHE00005501), position 2 holds the base64 encoded seed value (DPO38uKecdNRVX1c5kbd3cHa65U=) and position 2 holds the base64 encoded counter (AA==).

Import OATH tokens to the Digital Access database
  1. Log in to Digital Access Admin with an administrator account.
  2. Go to Manage System > OATH Configuration.
  3. In this example we will import tokens to a new provider, so click Import tokens to new provider.
  4. Enter import configuration:
    1. In Provider Name, enter a unique display name for the token provider (this display name will be used later when enabling OATH authentication).
    2. In OTP Length, enter the length of the OATH produced by the OATH device. Consult your OATH device supplier for the correct value.
    3. In Delimiter, enter the symbol used to separate the fields in the text file. In the above example, under heading "OATH tokens, description", the correct value would be : (a colon). Delimiter value is vendor specific. Consult your token vendor if in doubt.
    4. In TokenId position, enter the field position of TokenId within the token text file. In the example above, TokenId position is 0.
    5. In Seed Position, enter the field position of seed within the token text file. In the example above, seed position is 1. 
    6. In Counter Position, enter the field position of counter within the token text file. In the example above, counter position is 2.
    7. Check Seed and counter is base64 encoded (recommended).
    8. Browse to the Token File that contains the token information and click Continue.
  5. The information for the first token in the file is presented. Verify that the input is formatted correctly. If everything seems correct, click Start import.
  6. After the tokens have been imported you will get a report. If you get import failed you need to start over again and make sure the import configuration is correct, according to your OATH device vendor.
Enable OATH authentication

Currently you can only use one OATH token provider per authentication method. If you have imported tokens from different vendors, you should create a specific OATH authentication mechanism per token provider, unless the different providers are using the same OTP length. In that case you can import tokens from different vendors into the same OATH provider.

  1. Log in to Digital Access Admin with an administrator account.
  2. Go to Manage System > Authentication Methods.
  3. Click Add Authentication Method... and select PortWise OATH. Click Next.
  4. Enter a Display Name and select the OATH Provider that you want to use.
  5. Select if you want to use Two Factor Authentication and if so, if you want to use one or two fields for entering password and OTP.

    • One screen: Password and OTP are entered in the same screen. In case of Active directory users, the OTP will be validated first and if the OTP is valid, the password will be validated. This avoids the AD account from easily getting locked.
    • Two screens: Separate input fields are used, one to enter <password> and one to enter <otp>.
  6. Click Add Authentication Method Server... to chose which Authentication service(s) to use.
  7. Chose the Authentication Service you want to use from the drop down menu and click Next. If you have multiple Authentication Services implemented in your Digital Access architecture you can add another authentication method service to the authentication mechanism to enable redundancy. When you are finished, click Next.
  8. if you want to customize the information sent to the user you can edit the RADIUS reply templates. If not, click Next.
  9. Customization can be done in the Extended Properties tab. Click the ?-sign for help.
  10. Click Publish to publish the new configuration.
Assign an OATH device to a user
  1. Log in to Digital Access Admin with an administrator account.
  2. Go to Manage Accounts and Storage.
  3. Click User Accounts and search for and select the specific user account. Go to the PortWise Authentication tab. For information on how to add a user account, refer to Add user account in Digital Access.
  4. Check Enable PortWise OATH for the user account.
    1. Click New token.
    2. Select the OATH provider you want to use.
    3. Enter the device Serial Number.
    4. To activate the token, change token status from On Hold to Active.
  5. If Two Factor Authentication has been enabled, choose a password for the user.

    1. For manual password: enter a new password.

    2. For automatic password: check Generate Password.

    3. To use the user’s existing password from the user storage: check Use password from directory service.

  6. If a notification channel has been setup, the new password can be sent to the user through email or SMS. Refer to Set up email or sms notification channel in Digital Access.

Related information

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.