Properties/Configuration

This section describes how to configure the properties for the Onegini Token Server. It's divided into the following subsections:

Application property setup

The Onegini Token Server uses Docker Compose environment variables to manage application properties. Some properties have default values, that will be used if a value for this specific key is not specified (see the Default column). You can find example of how to set a Docker Compose variables in the install section of Onegini Token Server Documentation.

All admin and engine values can be encrypted. Please see the section about property encryption for details.

HTTP/Proxy

HTTP

Environment variable Default Example Description
TOKEN_​SERVER_​HTTP_​ENABLED true Enable or disable HTTP

HTTPS

Environment variable Default Example Description
TOKEN_​SERVER_​HTTPS_​ENABLED true Enable or disable HTTP
TOKEN_​SERVER_​HTTPS_​PROXY_​ENABLED false Enable or disable HTTP proxy
TOKEN_​SERVER_​HTTPS_​PROXY_​PORT 443 HTTP port that the proxy listens on
TOKEN_​SERVER_​HTTPS_​PROXY_​NAME token-server.example.com Hostname that the proxy listens on

Proxy settings

Environment variable Default Example Description
TOKEN_​SERVER_​TOMCAT_​PROXY_​ENABLED false Enable or disable the HTTP proxy
TOKEN_​SERVER_​TOMCAT_​PROXY_​PORT 80 HTTP port that the proxy listens on
TOKEN_​SERVER_​TOMCAT_​PROXY_​NAME token-server.example.com Hostname that the proxy listens on
TOKEN_​SERVER_​TOMCAT_​PROXY_​SCHEME https Default http schema to use
TOKEN_​SERVER_​TOMCAT_​PROXY_​SECURE true Set to true if you use https

Truststore

Environment variable Default Description
TOKEN_​SERVER_​TRUSTSTORE_​ENABLED true Enable or disable truststore
TOKEN_​SERVER_​TRUSTSTORE_​PASSWORD onegini Truststore password

Keystore

Environment variable Default Description
TOKEN_​SERVER_​KEYSTORE_​ENABLED onegini Enable or disable truststore
TOKEN_​SERVER_​KEYSTORE_​ALIAS onegini Truststore password

Admin console

The admin console provides the administrative functions for the runtime engine. It is separated from the runtime engine so access to it can be restricted.

General Properties

Environment variable Default Example Description
TOKEN_​SERVER_​ADMIN_​GENERAL_​PUBLIC_​URL /onegini/admin URL to which the user is redirected after successful logout.
TOKEN_​SERVER_​ADMIN_​GENERAL_​COOKIES_​SECURE_​BOOLEAN true Boolean: Set Secure flag for admin console session cookie.
TOKEN_SERVER_ADMIN_GENERAL_SUPPORTED_LOCALES en,nl,fr,de Comma separated list of supported languages for the OAuth scope descriptions.
TOKEN_​SERVER_​ADMIN_​GENERAL_​CLIENT_​IP_​HEADER x-forwarded-for The header to get the actual client ip from. We assume that the value is according to the (defacto) x-forwarded-for format: client, proxy1, proxy2
TOKEN_​SERVER_​ADMIN_​CERTIFICATES_​MAX_​SIZE_​IN_​BYTES 65000 65000 The maximum certificate file size that can be uploaded in the admin console.
TOKEN_SERVER_ADMIN_FEATURES_​MOBILE_CLIENT_DELETABLE_BY_HELPDESK_BOOLEAN true true Allow helpdesk to manage mobile clients.

Mobile authentication

Environment variable Default Description
TOKEN_SERVER_ADMIN_MOBILE_AUTHENTICATION​_MAXIMUM_MESSAGE_LENGTH_CHARS 155 This is the equivalent to "event.authentication.maximumMessageLength" in the administrator application.
The value should be equal to the value in the engine.
The value in the admin is used to validate the configuration input and has no influence on the engine.

Runtime engine

This section describes the properties for the Token Server engine.

General properties

Environment variable Example Description
TOKEN_SERVER_ENGINE_CUSTOM_HOOKS_IDP noOptAuthenticator A possibility to set a custom authenticator / identity provider bean. The value of this parameter should refer the a Spring bean available in the context and must extend the AbstractAuthenticator class. The authenticator will be used when the identity provider used is of type CUSTOM.
Warning:
The "authenticator" parameter from version 2.2 is not supported anymore, this setting is replaced with a more dynamic setup via the identity provider section in the admin console.
TOKEN_SERVER_ENGINE_API​_BASIC_AUTHENTICATION_USER user The system user that protects the end user API.
TOKEN_SERVER_ENGINE_API​_BASIC_AUTHENTICATION_PASSWORD password The password
TOKEN_SERVER_ENGINE_GENERAL​_CSRF_ENCRYPTION_MASTER_KEY 7C4DE5DE8B6035B91B7 5549B7F556EE9C8D2C7 B93091FCDED86455D41 57FF69F Encryption key used for encrypting the CSRF token. The value must be a 256 bit HEX encoded string (64 characters).
TOKEN_SERVER_ENGINE_GENERAL​_AUTHORIZATION_ENDPOINT https://www.onegini.com​/oauth/authorize The public authorization endpoint. Is used to build the redirect back from the step-up authentication server back to the Token Server.
TOKEN_SERVER_ENGINE_GENERAL​_CLIENT_IP_HEADER x-forwarded-for The header to get the actual client ip from. We assume that the value is according to the (defacto) x-forwarded-for format: client, proxy1, proxy2
TOKEN_SERVER_ENGINE_GENERAL​_TRANSACTION_ID_HEADER transaction-id The name of the header that contains a transaction id. This transaction id will be included in the audit events and requests sent to external systems. When the specified header is not available in the request, a transaction id will be generated by the application prefixed with "ONEGINI-".
Note:
The network gateway, for example WebSEAL, should strip the configured header name from any incoming request to prevent malicious input via this header. This header serves strictly the purpose of enabling a SIEM solution to create a transactional view of the communication flow between systems.
TOKEN_SERVER_ENGINE_REST_SERVICES​_READ_TIMEOUT_MILLIS 30000 The socket read timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 30 seconds.
TOKEN_SERVER_ENGINE_REST_SERVICES​_CONNECT_TIMEOUT 30000 The connection timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 30 seconds.
TOKEN_SERVER_ENGINE_SCOPE_VERIFICATION​_SERVICE_VERIFICATION_FAILED_ENDPOINT https://example.com​/scopes/failed/read Uri the user is redirected to when scope verification fails and no specific failure uri is specified for the scope

Sms gateway properties

The Token Server can send SMS messages for SMS authentication. It can use a number of different gateways or implementations. Below we specify the available options:

  • noOpSmsGateway - This is a dummy service which does not send any messages, so can be used if no SMS messages need to be sent.
  • restSmsGateway - A gateway that provides a REST service that triggers sending SMS messages. The service location and authentication details need to be specified via the rest sms gateway properties.
  • twilioSmsGateway - A gateway implementation that uses the Twilio API to send SMS messages.

Set the following property in order to specify the chosen SMS gateway.

Environment variable Example Description
TOKEN_​SERVER_​ENGINE_​CUSTOM_​HOOKS_​SMS_​GATEWAY restSmsGateway The chosen SMS gateway implementation.

Depending on the SMS gateway property set you may have to set some additional properties:

Rest SMS gateway properties

Environment variable Example Description
TOKEN_SERVER_ENGINE_SMS_GATEWAY_REST​_SMS_GATEWAY_URL https://some-external-gateway.com URL where the external sms gateway service can be reached. The service must implement the API specified in our reference manual.
TOKEN_SERVER_ENGINE_SMS_GATEWAY_REST​_SMS_GATEWAY_BASIC_AUTHENTICATION_USER username The username that is used in basic authentication with the rest sms gateway URL.
TOKEN_SERVER_ENGINE_SMS_GATEWAY_REST​_SMS_GATEWAY_BASIC_AUTHENTICATION_PASSWORD password The password for the user.

Note: The user and password properties should be set only if the sms gateway is protected by basic authentication.

Twilio sms gateway properties

Environment variable Description
TOKEN_​SERVER_​ENGINE_​SMS_​GATEWAY_​TWILIO_​ACCOUNT_​SID A 34 character string that uniquely identifies twilio account.
TOKEN_​SERVER_​ENGINE_​SMS_​GATEWAY_​TWILIO_​AUTH_​TOKEN Password for provided account-sid.
TOKEN_​SERVER_​ENGINE_​SMS_​GATEWAY_​TWILIO_​FROM_​NUMBER The number of message sender.
Environment variable Default Description
TOKEN_​SERVER_​ENGINE_​COOKIES_​SECURE_​BOOLEAN true Usage of secure cookies.

Request header authenticator

The RequestHeaderAuthenticator gets the user information from a number of HTTP headers. The default header names can be overridden by configuring them in the IDP configuration within the Onegini Admin Panel.

Additional header authenticator configuration properties:

Environment variable Example value Description
TOKEN_SERVER_ENGINE_HEADER_AUTH_LANGUAGE​_CODE_DEFAULT_CODE eng Default value used when the language code header value could not be mapped to a valid locale or when the header value is not set.
TOKEN_SERVER_ENGINE_HEADER_AUTH_LANGUAGE​_CODE_COOKIE_NAME Language Cookie name used to determine the language for the user, if set and cookie is available this is preferred over the header value.
TOKEN_SERVER_ENGINE_HEADER_AUTH_PARAMETERS​_WHITE_LIST currency,amount Request parameter names that will be stored as user attributes

Scope verification

Environment variable Default Description
TOKEN_SERVER_ENGINE_CUSTOM_HOOKS​_SCOPE_VERIFICATION_SERVICE noOpScopeVerificatio​nService​ The spring bean identifier of the class that implements the ScopeVerificationService.

Rest Scope Verification Service properties

Environment variable Example Description
TOKEN_SERVER_ENGINE_SCOPE_VERIFICATION​_SERVICE_URL https://some-external-service.com URL where the external scope verification service can be reached. The service must implement the API specification.
TOKEN_SERVER_ENGINE_SCOPE_VERIFICATION​_SERVICE_BASIC_AUTHENTICATION_USER username The username for basic authentication.
TOKEN_SERVER_ENGINE_SCOPE_VERIFICATION​_SERVICE_BASIC_AUTHENTICATION_PASSWORD password The password for basic authentication.

Notifications

Environment variable Example Description
TOKEN_SERVER_ENGINE_NOTIFICATION​_API_ENABLED_BOOLEAN true Via this property sending of notifications can be enabled/disabled. By default it is disabled
TOKEN_SERVER_ENGINE_NOTIFICATION​_API_ENDPOINT http://example.com The endpoint that will be used by the Token Server when a notification must be sent.
TOKEN_SERVER_ENGINE_NOTIFICATION​_API_EMAIL_FROM_ADDRESS [email protected] The email address that the end user will see as the sender of the notification.
TOKEN_SERVER_ENGINE_NOTIFICATION​_API_BASIC_AUTHENTICATION_USERNAME user Username used in the basic authentication challenge to the notification endpoint.
TOKEN_SERVER_ENGINE_NOTIFICATION​_API_BASIC_AUTHENTICATION_PASSWORD password Password used in the basic authentication challenge to the notification endpoint.
TOKEN_SERVER_ENGINE_GENERAL​_DEFAULT_NOTIFICATION_TYPE EMAIL The default notification type, can be set to NONE, EMAIL or SMS. When no default notification type is provided the value NONE is used.

Mobile authentication

Environment variable Default Description
TOKEN_SERVER_ENGINE_MOBILE​_AUTHENTICATION_PGP_IDENTITY_EMAIL [email protected] Identity used in the server side PGP keys used for push notification encryption.
TOKEN_SERVER_ENGINE_MOBILE​_AUTHENTICATION_MAXIMUM_MESSAGE_LENGTH_CHARS 155 Maximum length of messages user for mobile authentication. This message is used in sms and push messages. When using SMS it should not exceed the maximum length of a SMS
TOKEN_SERVER_ENGINE_MOBILE​_AUTHENTICATION_DEPRECATED_API_ENABLED false Allows to enable access to deprecated mobile authentication API endpoint.

Sms step up additional authentication

Environment variable Default Description
TOKEN_​SERVER_​ENGINE_​AUTHENTICATION_​SMS_​STEP_​UP_​VALIDITY_​MILLIS 180000 The time (ms) during which the code sent by sms is valid

Generic properties (used by both the Admin and runtime Engine)

This section describes the properties that are used by both the Token Server Admin and Engine.

Endpoints

Environment variable Example default Description
TOKEN_​SERVER_​COMMON_​ENGINE_​BASE_​URI https://token-server.6634464.com URL where the Token Server engine can be reached on by applications. Include the protocol and hostname and if needed the port number. Example: http://token-server.6634464.com:7878
TOKEN_​SERVER_​COMMON_​ENGINE_​CONTEXT_​ROOT /oauth /oauth The context root of the Token Server engine

Development mode

Environment variable Example Description
TOKEN_SERVER_COMMON_FEATURES_APP​_DEV_MODE_ENABLED_BOOLEAN false This property is used to enable or disable the development mode for applications. Please see the OAuth config section for more information.

Encryption

Environment variable Example Description
TOKEN_​SERVER_​COMMON_​DB_​ENCRYPTION_​PASSWORD 4^sf9)fds^)d$@rd( The encryption password that is used to encrypt database values.
TOKEN_​SERVER_​COMMON_​DB_​ENCRYPTION_​POOLSIZE 10 The size of the pool with encryptors. If not set, the default is 4.

Datasource

Environment variable Example Description
TOKEN_SERVER_COMMON_DB​_USER onegini The database user for this datasource
TOKEN_SERVER_COMMON_DB​_PASSWORD VeryHardToGuessPassw​ord​ The database password for this datasource
TOKEN_SERVER_COMMON_DB​_DRIVER_CLASS oracle.jdbc.driver.OracleDriver The driver classname that is used
TOKEN_SERVER_COMMON_DB​_JDBC_URL jdbc:oracle:thin:@db_host:1521:ORCL The JDBC url
TOKEN_SERVER_COMMON_DB​_VALIDATION_QUERY SELECT 1 FROM DUAL The query that is executed to test whether the connection is still alive
TOKEN_SERVER_COMMON_DB​_CONNECTIONS_MAX_WAIT 500 The maximum time that the datasource will wait for a connection to be returned from the pool
TOKEN_SERVER_COMMON_DB​_CONNECTIONS_INITIAL_SIZE 3 The initial connection pool size
TOKEN_SERVER_COMMON_DB​_CONNECTIONS_MAX_ACTIVE 60 The maximum number of active connections
TOKEN_SERVER_COMMON_DB​_CONNECTIONS_MAX_IDLE 8 The maximum number of idle connections before connections are cleaned up
TOKEN_SERVER_COMMON_DB​_CONNECTIONS_MAX_LIFETIME_MILLIS 60000 The maximum time for a connection to live (after a given time the connection is closed)
TOKEN_SERVER_COMMON_DB​_PLATFORM org.hibernate.dialect.Oracle10gDialect The dialect that this database uses
TOKEN_SERVER_COMMON_DB​_DATABASE_TYPE ORACLE The database type name. supported databases types: MYSQL, ORACLE, H2, MSSQL.

Automatic schema migrations

The Token Server supports automatic schema migrations. By default these are enabled. This means that when a new version is deployed the schema is automatically updated to the new version when the new version of the Token Server starts up for the first time. When you want to disable the automatic schema migrations you need to modify the TOKEN_SERVER_COMMON_DB_MIGRATION_ENABLED setting and set the value to false. For the other properties please see the table below.

Environment variable Example Description
TOKEN_​SERVER_​COMMON_​DB_​MIGRATION_​ENABLED true The flag that indicates whether automatic flyway migrations are enabled (true) or not (false).
TOKEN_​SERVER_​COMMON_​DB_​MIGRATION_​INIT_​VERSION 3.02.01.00 The db version from which the automatic schema migrations are performed.
TOKEN_​SERVER_​COMMON_​DB_​MIGRATION_​FOLDER /db/scripts/mysql The location for the database migrations. For oracle: /db/scripts/oracle. For Mssql: /db/scripts/mssql
TOKEN_​SERVER_​COMMON_​DB_​MIGRATION_​OUT_​OF_​ORDER false Flag to support hotfix migrations for earlier versions.

Encrypt properties

The Onegini Token Server supports encrypting property values. The open source library Jasypt is used for this. Onegini uses a strong encryption algorithm, which is not present in the standard JRE security provider implementation. For this reason we use the BouncyCastle security provider implementation.

Install the Jasypt library

The Onegini Token Server uses Jasypt for property encryption. Download Jasypt. To install it, it only needs to be extracted.

Unzip the library into a directory of your choice, e.g. the /opt directory.

Add Bouncy Castle provider to Jasypt

Download the latest version of the Bouncy Castle provider and place the jar file into <JASYPT_PATH>/lib/.

Encrypt property values

It is possible to encrypt properties such as passwords. The steps below describe how to do this. All properties are encryptable. Navigate to the directory where the Jasypt library is installed.

Generate a master password:

openssl rand -hex 32

Configure the encryption password in docker-compose file:

Environment variable Required Description
TOKEN_​SERVER_​COMMON_​PROPERTY_​ENCRYPTION_​PASSWORD true The password that is used to encrypt and decrypt property values

Next, execute the following command:

cd <JASYPT_PATH>/bin/
./encrypt.sh providerClassName="org.bouncycastle.jce.provider.BouncyCastleProvider" algorithm="PBEWITHSHA256AND256BITAES-CBC-BC" verbose="false" password='<MASTER_PASSWORD>' input='<TEXT_TO_ENCRYPT>'

Note: Don't forget it, the master password is needed when starting / stopping the Token Server instance(s))

If the password or the input contain a single quote you will need to provide each separate single quote with the following sequence: '"'"'

When the above command is executed the encrypted property value is printed to the screen. The last step is to configure the encrypted value as the actual value in the property file. The value has to be surrounded by ENC(). Below is an example of an encrypted database password:

TOKEN_SERVER_COMMON_DB_PASSWORD=ENC(6sCtMDYFi5MhTfRk9x6tzVuc/TouSqLnTsajxGdOq/4=)

You can verify the encryption by running

./decrypt.sh providerClassName="org.bouncycastle.jce.provider.BouncyCastleProvider" algorithm="PBEWITHSHA256AND256BITAES-CBC-BC" verbose="false" password='<MASTER_PASSWORD>' input='<TEXT_TO_DECRYPT>'

Cluster configuration

The Onegini Token Server can run in clustered mode. When running in clustered mode, the application cache will be replicated across all nodes in the cluster.

First cluster mode must be enabled by setting the TOKEN_SERVER_ENGINE_CLUSTER_OPERATIONAL_MODE Docker Compose environment variable to the value CLUSTERED. When this value is specified the application will initialise itself in clustered mode. In order to run in clustered mode the application also requires a HOST_IP environment variable. Several other environment variables are optional.

The table below specifies these environment variables:

Environment variable Example value Description
HOST_IP 203.0.113.1 The external address the cluster replication uses for the other nodes in the cluster.
HOSTNAME 127.0.0.1 The address the cluster replication service binds to.
JGROUPS_​REPLICATION_​PORT 7800 The external port number the cluster replication uses for the other nodes in the cluster.
JGROUPS_​FAILURE_​DETECTION_​PORT 7801 The port number the cluster replication service uses to detect node failures

Warning: if you run the Token Server in clustered mode the following property MUST be set:

  • HOST_IP

Note: Before starting the server it's wise to check the network communication between the nodes that need to replicate caches with each other.

This can be achieved by setting up an SSH connection to one of the servers and executing the following command

telnet <IP_ADDRESS_OR_HOSTNAME_OF_OTHER_NODE> 7800

If the connection is refused or times out this means that no network connection is possible and you need to check your firewall and network settings.