Generic token REST endpoint

The Adminapp REST API offers an interface to manage arbitrary tokens, i.e. tokens for authentication methods that are not integrated into the product.

The API supports a variety of use cases such as the creation, update, enabling, disabling, and deletion of tokens, as well as the management of activation letters.

The API is protected by role-based access control just like the rest of the Adminapp features.

Although the generic token controller solution has been designed with authentication token management in mind, it may be used to manage any data connected to a user (e.g. display app/device information).

REST API

The REST API of the generic token endpoint is documented here in: Adminapp REST API Reference

The generic token endpoints are: /rest/users/userId/tokens/generic/ followed by the ID configured in the Generic Token Controller plugin.

General Configuration

To configure the token endpoint of a Generic Token Controller:

  1. Go to:
    Adminapp >> Users >> Authentication Tokens (Credentials)
  2. Choose an existing Generic Token Controller or create a new one and in it, choose an ID. The ID is used in the REST endpoints, as authentication method identifier, and in the translation keys for text elements (in case a UI is configured).
  3. In property Token Endpoint, add a Generic Token Endpoint plugin. It controls the behavior of the REST interface. In particular, it defines which repository (persistency) is to be used and which internal token attributes should be available in the REST API.
  4. A UI for the REST API may be configured later: see Generic Token Controller UI configuration.
  5. Open the Token Endpoint configuration and configure a Token Repository as described below.

Token Repository configuration

The token repository defines how token information is obtained from either the IAM database or from 3rd party systems. It also defines how token attributes are mapped to the REST API.

  • There are three types of token repositories:
  • The Token Based Generic Token Repository plugin: the default implementation based on the token data model strong token information in the IAM database. Whenever possible, use this repository.
  • The Credential Based Generic Token Repository plugin: an implementation based on the credential data model storing token information in the IAM database. Use this only if token data is stored directly in the user profile and if there is only one token per user.
  • Custom token repository plugins: use this to connect to 3rd party services.

Attribute mapping

  • Within the plugins Token Based Generic Token Repository and Credential Based Generic Token Repository, the property Token Attribute Mapping defines:
  • Set of token attributes available in the REST API.
  • Names of the attributes in the REST API.

Attribute mapping for the Token Based Generic Token Repository

The following attributes are supported in the token-based token repository implementation.

Attribute

Data Type

Token ID

String

Serial ID

String

Enabled

Boolean

Activation Date

Date

Valid From

Date

Valid To

Date

Generation Date

Date

First Usage Date

Date

Latest Usage Date

Date

Total Usages

Integer

Tracking ID

String

Data

String

Generic Data Element 1 - 12

String

Attribute mapping for the Credential Based Generic Token Repository

The credential-based repository supports a limited set of attributes. At most two credentials (tokens) exist per user. Normally, a current and a next credential. The first can be accessed by Token ID <username>-current, the latter by <username>-next.

Attribute

Data Type

Remark

Data

String

The data is stored either as a String or in binary form on the database.

Binary data is represented as a Base64 String when read from the system.

Data Encoding

String

Value is either 'STRING' or 'BINARY' (see above)

Delivery Date

Date

Generation Date

Date

Serial Number

String

Not Active Before

Date

Not Active After

Date

Context Data Fields

Map

Maps user context data fields to REST attributes. Context data fields are available in data.attributes.contextData. within the REST responses.

Example:

"attributes": {
	"someAttribute": "someValue",
	"contextData": {
		"contextDataName": "contextDataValue"
	}
}

The credential model should not be used for new token implementations. Please use the token-based model with a token-based repository.

Custom token repository plugins

To provide your own repository implementation (e.g. connect to a 3rd party system), implement a custom plugin for interface com.airlock.iam.admin.api.application.configuration.token.generic.GenericTokenRepositoryConfig (configuration) and com.airlock.iam.admin.api.domain.model.token.generic.GenericTokenRepository (logic).

You can request the latest version of the IAM Custom Development Guide by opening a support ticket. See Techzone - Airlock support process) for more information.