Skip to main content
Skip table of contents

Digipass DB adapter

The Digipass DB Adapter allows TrustBuilder to use strong authentication using a Digipass token. This token can be a hardware token or a software token.

The Digipass DB adapter uses a specific database schema. A schema for MySQL and Oracle are available.

The Digipass DB adapter will try to authenticate a user and manage the tokens assigned to a user. Two scenarios are possible:

  1. You store the user information in the database.

  2. You have a user repository (identity store) and will use that repository to store your user data.

In case of scenario 1, you will need the PERSON table (see below). In case of scenario 2 (the default) the PERSON table should not exist. Inserting data and updating data in the PERSON table is not part of the Digipass DB adapter.

Database Schema

All the token information will be stored in a database. The structure of this database is explained in this section and is part of a generic authentication model. The database has the following tables for Digipass:

  • PERSON (optional)



Table PERONS has the following columns:

  • ID: The primary key




  • ... (depending on the data you want to store about a user in the database)

Table AUTH_PRINCIPAL has the following columns:

  • PRINCIPAL: if a customer already has an identity store, the type will be a VARCHAR. If the customer does not have an identity store, the type will be an INT referencing to the PERSON(ID) column.

  • AUTH_ID: references to the TOKEN(ID) column. However, no foreign key constraint will be made to the TOKEN table because AUTH_ID will hold a reference to multiple tables. If Digipass is the only authentication mechanism, then a foreign key constraint can be made between this column and the AUTH_ID column.

  • AUTH_TYPE: Will contain the table name where the authentication information is found for this user. For Digipass, this will contain the value ‘TOKEN’.

  • LOGINID: The id used to login to the application.

  • LOGIN_POLICY: A reference to the login policy that should be used. We do not supply means of checking the LOGIN_POLICY. This should be handled separately.

  • STATUS: Will contain the status of this authentication row. At the moment, we have 2 statuses: enabled and disabled.

Table TOKEN has the following columns:

  • ID: The primary key of the table

  • SERIALNR: Will contain the Digipass token serial number.

  • DPBLOB: Will contain a base64 encoded string containing the Digipass token blob.

  • APPLICATION: Will contain the application to which this Digipass token blob applies.

  • DPMODE: Will contain the Digipass token blob mode.

  • DPTYPE: Will contain the Digipass token type.

  • QABLOB: Will contain the Questions and Answers blob.

  • STATUS: Will contain the status of the token.


The DigipassDB adapter allows you to configure the following:

  • The JDBC Adapter that will be used to connect to the external database. This parameter is required.

  • The Vacman controller kernel parameters. For more information on the kernel parameters: see the “VACMAN Controller Product Guide”. The default values are recommended in most situations.

Request - API (Administration)

Import DPX

This is not part of the Digipass DB adapter but is required to import tokens into the database. The class that imports tokens from a DPX file can be found in the TrustBuilder config jar:

This class takes one argument: the path to a properties file. The properties file has the following keys:

  • type: token

  • dpxfile: The (absolute) path to the DPX file you want to import

  • key: The key of the DPX file

  • db.driver: The database driver

  • db.url: The database URL

  • db.password: The database password

  • applmapping1>: These optional fields allow you to map an application in the DPX file to an application in the database. If for instance you specify: “applmapping1=APPL 1, banking”, all the tokens of APPL 1 in the DPX will be stored with application “banking” in the database. The index starts at 1, is ascending and no gaps are allowed. If not specified, the applications are stored as the application specified in the DPX file.

  • appltoimport: A comma separated list of applications in the DPX file you want to import. If not specified, all applications are imported.

  • activationcodefile: The path to the file where the activation codes of the tokens are stored. This file is supplied with the DPX file.

The Digipass Kernel parameters can also be specified. See 'VACMAN Controller Product Guide' for more information. Possible properties:

  • IdentificationTimeWindow

  • SignatureTimeWindow

  • GMTAdjustment

  • CheckChallenge

  • IdentificationThreshold

  • SignatureThreshold

  • CheckInactiveDays

  • DeriveVector

  • SynchronizationWindow

  • OnlineSignature

  • EventWindow

  • HSMSlotId

  • StorageKeyId

  • TransportKeyId

  • StorageDeriveKeys0

  • StorageDeriveKeys1

  • StorageDeriveKeys2

  • StorageDeriveKeys3

Take great care when specifying the Digipass Kernel parameters. Under most circumstances, you should not alter the default values.

Link Token Request (digipassDBLinkTokenRequest)

This request will allow you to link a user to a token.

  • Application (String): required.

  • Serial number (String): required.

  • Loginid (String): required.

  • Principal (String): required.

  • Login Policy (String): optional.

  • Token (Boolean): optional. Defaults to true (single token)

  • User (Boolean): optional. Defaults to true (single user)

Unlink token request (digipassDBUnlinkTokenRequest)

This request will unlink a user from a token.

  • Serialnr (String): Optional.

  • Application (String): Required.

  • Loginid (String): Required.

  • Principal (String): Optional. Required if a token can be linked to multiple users.

Unlock token request (digipassDBUnlockTokenRequest)

This request will unlock a tyoken from a user for a specific application.

  • Application (String): required

  • Serialnr (String): optional

  • Principal (String): optional

  • Loginid (String): required

  • Randomnr (String): required.

Change static password request (digipassDBChangeStaticPasswordRequest)

This request will change the static password of a token.

  • Application (String): required.

  • Loginid (String): optional.

  • Serialnr (String): required.

  • Principal (String): optional.

  • Pwd1 (String): required.

  • Pwd2 (String): required.

Delete Token request (digipassDBDeleteTokenRequest)

This request will delete a token.

  • Application (String): required.

  • Serialnr (String): required.

Free Token Request (digipassDBFindFreeTokenRequest)

Find the first token with status 0 (free).

  • Application (String): required.

  • Type (String): optional.

Find Tokens Request (digipassDBFindTokensRequest)

Find the tokens attached to the principal.

  • Principal (String): The principal you want the tokens for.

Find Users Request (digipassDBFindUsersRequest)

Find the principals linked to a token.

  • Serialnr (String): required.

Force Pin Change Request (digipassDBForcePinChangeRequest)

Trigger a force pin change.

  • Application (String): required.

  • Serialnr (String): required.

Reset Static Password (digipassDBResetStaticPasswordRequest)

Resets Digipass Static PIN.

  • Application (String): required.

  • Serialnr (String): required.

Reset Token Request (digipassDBResetTokenRequest)

Resets a Digipass token.

  • Application (String): required.

  • Serialnr (String): required.

DB Sync Token Request (digipassDBSyncTokenRequest)

Synchronize a Digipass token.

  • Application (String): required.

  • Serialnr (String): required.

  • Pwd1 (String): required.

  • Chl1 (String): required.

  • Pwd2 (String): required.

  • Chl2 (String): required.

Token Info Request (digipassDBTokenInfoRequest)

Retrieve the Digipass token info.

  • Application (String): required.

  • Serialnr (String): required.

Request - API (Authentication)

General Remark

All authentication requests will use the following parameters:

  • Loginid (String): required.

  • Application (String): required.

  • Serial number (String): optional.

  • Principal (String): optional.

Application and login id are required as they are the minimum information you need to login to an application. The serial number is optional if only one token can be assigned to one user (single user). In that case, the serial number will be retrieved using login id and application. An error will be generated if more than one token is found. Principal is also optional but only if a user can be linked to one token (single token). Otherwise we have no means of finding which user is trying to generate the challenge. An error will be generated if the principal was not found.

Generate Challenge Request (digipassDBGenerateChallengeRequest)

This request will generate a challenge for challenge response authentication.

  • Loginid (String): required.

  • Application (String): required.

  • Serial number (String): optional.

  • Principal (String): optional.

Authenticate Token (digipassDBAuthenticateTokenRequest)

Will perform challenge/response or response authentication.

  • Loginid (String): required.

  • Application (String): required.

  • Password (String): required.

  • Challenge (String): optional but required for challenge/response authentication (see Generate Challenge Request)

  • Serialnr (String): optional.

  • Principal (String): optional.

Verify Signature (digipassDBVerifySignatureRequest)

Will perform a signature verification.

  • Signature (String): Required.

  • SignedFields (String array): Required.

  • Loginid (String): Required.

  • Application (String): Required.

  • Serialnr (String): Optional.

  • Principal (String): Optional.

Response - API

Common Properties

All responses have three properties in common:

  • status Status flag indicating whether the response is ok (0) or not (1)

  • substatus Response specific number indicating what the problem was

  • message Response specific message in case there was a problem (can be null)

Some requests return more than these three common properties and are listed below.

JavaScript errors detected

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

If this problem persists, please contact our support.