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
- HTTP/Proxy
- Truststore
- Keystore
- Admin console
- Runtime engine
- Generic properties (used by both the Admin and runtime Engine))
- Encrypt properties
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
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. |
Cookie properties
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.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 | 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 |
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 |
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_SECONDS | 3600 | Default TTL seconds 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. |
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. |
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 FLYWAY_ENABLED
setting and set the value to false
. For the other properties please see the table below.
Environment variable | Example | Description |
---|---|---|
FLYWAY_ENABLED | true | The flag that indicates whether automatic flyway migrations are enabled (true) or not (false). |
FLYWAY_BASELINE_VERSION | 0 | The db version from which the automatic schema migrations are performed. |
FLYWAY_LOCATIONS | /db/scripts/mysql | The location for the database migrations. For oracle: /db/scripts/oracle. For Mssql: /db/scripts/mssql |
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(
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>'