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_​ALIAS onegini Alias of the keystore
TOKEN_​SERVER_​KEYSTORE_​PASSWORD onegini Keystore 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.
TOKEN_​SERVER_​ADMIN_​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_ADMIN_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.

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.
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.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 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.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.

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

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.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 10 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. For oracle: /db/scripts/oracle. For Mssql: /db/scripts/mssql
SPRING_​FLYWAY_​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:

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