Properties/Configuration¶
This section describes the configuration properties for the Onegini Token Server.
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 |
Cookie settings¶
| Environment variable | Default | Description |
|---|---|---|
| COOKIES_SAMESITE | None (engine), Lax (admin) | 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. Use Unset to omit the SameSite flag on cookies. The OpenID Provider browser state cookie will always have the flag SameSite=None. |
| COOKIES_LEGACY_SUPPORTFALLBACK | true (engine), false (admin) | Some older browsers ignore cookies with a SameSite flag. Any browser on iOS 12 treats cookies with the SameSite=None flag as SameSite=Lax. To support these browsers, the Onegini Token Server can send a second cookie without a SameSite flag. This fallback cookie may also be returned by browsers that do support the SameSite flag. They treat the cookie as if SameSite=Lax is configured. |
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 |
|
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 |
|---|---|---|
| RESTSERVICES_WAITFORAVAILABLECONNECTIONINPOOLTIMEOUT | 5s | Maximum time the application waits for an available connection in the pool to perform a REST call to external services |
| RESTSERVICES_REQUESTCONNECTIONPOOLMAXSIZETOTAL | 30 | Maximum amount of available connections in the pool for REST calls |
| RESTSERVICES_REQUESTCONNECTIONPOOLMAXSIZEPERROUTE | 5 | Maximum amount of concurrent connections to a host |
| RESTSERVICES_REQUESTCONNECTIONPOOLVALIDATEAFTERINACTIVITY | 2s | Defines period of inactivity in milliseconds after which persistent connections must be re-validated |
| RESTSERVICES_READTIMEOUT | 10s | The socket read timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 10 seconds. |
| RESTSERVICES_CONNECTIONTIMEOUT | 2500ms | The connection timeout for REST service calls in milliseconds. A timeout value of 0 specifies an infinite timeout, the default is 2.5 seconds. |
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¶
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, which can be configured 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.cmSmsGateway- A gateway implementation that uses CM.com to send SMS messages.twilioSmsGateway- A gateway implementation that uses Twilio 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. |
Some SMS gateways will require additional properties:
Rest SMS gateway properties¶
The following properties are required when TOKEN_SERVER_ENGINE_CUSTOM_HOOKS_SMS_GATEWAY has the value restSmsGateway.
| 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.
CM sms gateway properties¶
The following properties are required when TOKEN_SERVER_ENGINE_CUSTOM_HOOKS_SMS_GATEWAY has the value cmSmsGateway.
| Environment variable | Description |
|---|---|
| TOKEN_SERVER_ENGINE_SMS_GATEWAY_CM_PRODUCT_TOKEN | CM's product token |
| TOKEN_SERVER_ENGINE_SMS_GATEWAY_CM_SENDER | The sender ID, short code or phone number of the message sender. Phone numbers should be in international format starting with 00, e.g. 0012345556789. |
| TOKEN_SERVER_ENGINE_SMS_GATEWAY_CM_URL | The API endpoint for CM. The Global Endpoint URL is configured by default. |
Twilio sms gateway properties¶
The following properties are required when TOKEN_SERVER_ENGINE_CUSTOM_HOOKS_SMS_GATEWAY has the value twilioSmsGateway.
| 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 sender ID, short code or phone number of the message sender. Phone numbers should be in E.164 format, e.g. +12345556789. |
Cookie properties¶
| Environment variable | Default | Description |
|---|---|---|
| TOKEN_SERVER_ENGINE_COOKIES_SECURE_BOOLEAN | true | Usage of secure cookies. |
Security properties¶
The list of properties related with the security of the application.
| Environment variable | Default | Description |
|---|---|---|
| TOKEN_SERVER_ENGINE_SECURITY_X_FRAME_OPTIONS | DENY | Configures the value for the X-Frame-Options header. Possible values are DENY, SAMEORIGIN, NONE. |
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 | The default notification type, can be set to NONE, EMAIL or SMS. When no default notification type is provided the value NONE is used. |
OAuth¶
| Environment variable | Default | Example | Description |
|---|---|---|---|
| OAUTH_TOKEN_MINIMUM_AGE | 0 | 2m or PT0.1S | The minimum age of a token before it can be removed. Tokens that are refreshed are eligible for removal. Valid vales are ISO-8601 formatted or use a simple format with a number and a unit e.g. "1h". If the unit is omitted, the number is interpreted as milliseconds. If set to 0 no time restriction will be applied. |
| AUTHENTICATION_FLOW_RENDER_PAGE_BEFORE_REDIRECT_TO_IDP | false | false | During the authentication the end user is sent from the authorization endpoint to an endpoint that is specific for that type of identity provider. The default behaviour is to use an HTTP redirect. When set to true, an intermediary page will be rendered instead. |
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(
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>'