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.

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.

Proxy settings

The following environment variables can be configured when Onegini Token Server is behind a reverse proxy. The Onegini Token Server will then create redirects based on these values instead of the http header for the host and the port it is running on.

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
Environment variable Default Example Description
COOKIES_SAMESITE None SameSite restriction of cookies when the user comes from a third party site, e.g. the SAML identity provider. Values are None, Lax, Strict and Unset.

Truststore

Refer to the documentation how to configure the truststore.

Environment variable Default Description
TOKEN_​SERVER_​TRUSTSTORE_​ENABLED false Enable or disable the truststore
TOKEN_​SERVER_​TRUSTSTORE_​PASSWORD Truststore password
TOKEN_​SERVER_​TRUSTSTORE_​PATH /opt/data/truststore/truststore.jks Location of the truststore within the container

Keystore

Refer to the documentation how to configure the keystore.

Environment variable Default Description
TOKEN_​SERVER_​KEYSTORE_​ALIAS token-server Alias of the keystore
TOKEN_​SERVER_​KEYSTORE_​ENABLED false Enable or disable the keystore. This also enables or disables the SSL connector.
TOKEN_​SERVER_​KEYSTORE_​PASSWORD token-server Keystore password
TOKEN_​SERVER_​KEYSTORE_​PATH
  • Admin: /opt/token-server/admin/data/keystore.jks
  • Engine: /opt/token-server/engine/data/keystore.jks
Location of the keystore within the container

Endpoints

Environment variable Example default Description
TOKEN_​SERVER_​COMMON_​ENGINE_​BASE_​URI https://token-server.example.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..example.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.

Database

Encryption

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

Datasource

Environment variable Example Description
DATABASE_TYPE oracle The database type name. Supported databases types: mysql, oracle, h2, mssql.
SPRING_​DATASOURCE_​USERNAME onegini The database user for this datasource
SPRING_​DATASOURCE_​PASSWORD VeryHardToGuessPassword The database password for this datasource
SPRING_​DATASOURCE_​URL jdbc:oracle:thin:@db_host:1521:ORCL The JDBC url
SPRING_​DATASOURCE_​HIKARI_​MINIMUM_​IDLE 10 The minimum number of idle connections that HikariCP tries to maintain in the pool.
SPRING_​DATASOURCE_​HIKARI_​MAXIMUM_​POOL_​SIZE 100 The maximum size that the pool is allowed to reach, including both idle and in-use connections.
SPRING_​DATASOURCE_​HIKARI_​CONNECTION_​TIMEOUT 500 The maximum number of ms that a client will wait for a connection from the pool.
SPRING_​DATASOURCE_​HIKARI_​MAX_​LIFETIME 1800000 The maximum lifetime of a connection in the pool. Strongly recommended to set this value, and it should be several seconds shorter than any database or infrastructure imposed connection time limit. 0 means infinite lifetime.

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 SPRING_FLYWAY_ENABLED setting and set the value to false. For the other properties please see the table below.

Environment variable Example Description
SPRING_​FLYWAY_​ENABLED true The flag that indicates whether automatic flyway migrations are enabled (true) or not (false).
SPRING_​FLYWAY_​BASELINE_​VERSION 0 The db version from which the automatic schema migrations are performed.
SPRING_​FLYWAY_​LOCATIONS /db/scripts/mysql The location for the database migrations.
SPRING_​FLYWAY_​OUT_​OF_​ORDER true Flag to support hotfix migrations for earlier versions. This property is enabled by default.

General REST properties

These properties are used for outgoing http connections to external services.

Environment variable Default value Description
REST_​SERVICES_​WAIT_​FOR_​AVAILABLE_​CONNECTION_​IN_​POOL_​TIMEOUT_​MILLIS 5000 Maximum time the application waits for an available connection in the pool to perform a REST call to external services
REST_​SERVICES_​REQUEST_​CONNECTION_​POOL_​MAX_​SIZE_​TOTAL 100 Maximum amount of available connections in the pool for REST calls
REST_​SERVICES_​REQUEST_​CONNECTION_​POOL_​MAX_​SIZE_​PER_​ROUTE 10 Maximum amount of concurrent connections to a host
REST_​SERVICES_​REQUEST_​CONNECTION_​POOL_​VALIDATE_​AFTER_​INACTIVITY_​MILLIS 2000 Defines period of inactivity in milliseconds after which persistent connections must be re-validated

AWS properties

The properties required to connect the Onegini Token Server to AWS services.

Environment variable Description
AWS_REGION AWS region in which services are available

OneSee events

The Token Server supports sending events to the OneSee platform using AWS Firehose streams. The configuration is described below:

Environment variable Description
ONESEE_STREAMTYPE Specifies which stream type will be used to send events. Available values: firehose
ONESEE_STREAM Name of the stream inside streaming service
ONESEE_ACCESSKEY Access key to the streaming service
ONESEE_SECRET Access secret key to the streaming service

Each event sent to OneSee has a source_name and source_version. Under normal circumstances, you won't need to override the default values but if necessary, you can use the properties APPLICATION_NAME and APPLICATION_VERSION.

The feature must also be enabled in the admin console.

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.
TOKEN_​SERVER_​ADMIN_​REST_​SERVICES_​READ_​TIMEOUT_​MILLIS 10000 The socket read timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 10 seconds.
TOKEN_SERVER_ADMIN_REST_SERVICES​_CONNECT_TIMEOUT 2500 The connection timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 2.5 seconds.

See also general REST properties.

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.

Zip archive handling

Environment variable Default Example Description
TOKEN_​SERVER_​ADMIN_​ZIP_​IGNORED_​FILES .DS_Store .DS_Store,.gitignore List of the files that are ignored when deflating the archive.
TOKEN_​SERVER_​ADMIN_​ZIP_​MAX_​FILE_​COUNT 100 100 Maximum count of files within the zip archive.
TOKEN_​SERVER_​ADMIN_​ZIP_​MAX_​BYTE_​SIZE 10485760 10485760 Maximum size of the deflated archive.

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.

Note: the custom identity provider is deprecated in favor of the custom API identity provider and will be removed in a future release.
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.example.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 10000 The socket read timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 10 seconds.
TOKEN_​SERVER_​ENGINE_​REST_​SERVICES_​CONNECT_​TIMEOUT 2500 The connection timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 2.5 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
JWT_​MAX_​ACCESS_​TOKEN_​SIZE_​TO_​INCLUDE_​GROUP_​PERMISSIONS 4096 Maximum number of characters for the JWT Access token to include groups and permissions.

See also general REST properties.

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.example.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 noOpScopeVerificationService The Spring Bean identifier of the class that implements the ScopeVerificationService.

Note: the scope verification configuration via a Spring Bean is deprecated in favor of the REST based scope verification service and will be removed in a future release.

Rest Scope Verification Service properties

Environment variable Example Description
TOKEN_​SERVER_​ENGINE_​SCOPE_​VERIFICATION_​SERVICE_​URL https://some-external-service.example.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 noreply@ 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 noreply@ 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

Redis

Environment variable Default Description
TOKEN_​SERVER_​REDIS_​SENTINEL_​NODES Comma separated list of Redis sentinel nodes in the form of host:port. (e.g. redis1.example.com:6379,redis2.example.com:6379)
TOKEN_​SERVER_​REDIS_​SENTINEL_​MASTER_​ID The name of the Redis master, e.g. mymaster.
TOKEN_​SERVER_​REDIS_​PASSWORD The password used to authenticate with the Redis server.
REDIS_​DEFAULT_​JWKS_​URI_​RESPONSE_​TTL 60m Default TTL for the jwks_uri response cache for ID Token encryption. This is the fallback value, the max-age directive on the Cache-Control header should be provided and will be used in place of this value. Specified as a 'Duration'.

How to 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:

SPRING_DATASOURCE_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>'