Configuration

Configuration files

Identity Service processes configuration files in the following order:

  1. WEB-INF/classes/default-application.properties (DO NOT EDIT)
    This file contains all configuration options with their default values.

  2. WEB-INF/classes/custom-application.properties
    If a change to the data directory data.directory.location or configuration directory config.directory.location is required, the change must be made in this file.

All further adjustments are made in the following files:

  • [config.directory.location]/application.properties
    In the standard installation the configuration directory config.directory.location is ${user.home}/.identity-service.

  • [config.directory.location]/secrets.properties
    Store sensitive data such as passwords in this file and reference them in application.properties as described in the example.

Editing these two files is the recommended way to make configuration changes. The files are not created automatically. A template can be found in the resources folder of the distribution package.

The format of the configuration files must correspond to the Java Properties file format .

Sample .properties file
# The files have to be UTF-8 encoded, otherwise special characters can lead to errors!
# A safe method is to use Unicode syntax e.g: รค = \u00E4 (see http://0xcc.net/jsescape/)

# comments use the hash sign

# the syntax is:
key = value

# a value can reference another key
key1 = http://${key.with.server}/test

If you make changes to configuration files, you must restart the web application or, alternatively, the entire Tomcat server for the changes to take effect.

Environment variables

You can also set the value of all configuration parameters using environment variables. These always override the values you set in the application.properties. This allows to easily customize the Identity Service configuration in containerized environments, for example.

You need to translate the names of the configuration properties when using them as environment variables: Only use uppercase letters and replace any dot . by an underscore _.

Example: security.oauth.provider becomes SECURITY_OAUTH_PROVIDER. This pattern applies to all configuration parameters.

Configuration of passwords and secrets

Store sensitive data, such as passwords, in the file [config.directory.location]/secrets.properties following the pattern secretKey=value. For example, define the password for database access like this:

secrets.properties
# Password for database
db.jdbc.password=mySecretValue

Do not store secrets in the application.properties.

Storing the secrets separately in the secrets.properties file prevents gaining knowledge of configured secrets by retrieving the application.properties file.

Configuration parameters

General settings

This section describes the parameters that most often need to be changed in a standard installation. Further parameters are described in comments in the file WEB-INF/classes/default-application.properties.

data.directory.location

Data directory where the local configuration of the Identity Service is stored.

In case the Tomcat server is running as a Windows service, the .identity-service directory is located in the user directory of the Tomcat user who started the service. Path separators must be specified as either / or \\.

Tomcat User on Windows
If no Tomcat user has been created, the Tomcat server runs with the system user (not recommended!). Depending on how the Tomcat has been installed the user directory is created either under %systemroot%/config/systemprofile/.identity-service or %systemroot%/ServiceProfiles/LocalService/.identity-service.

A divergent data directory can be configured in WEB-INF/classes/custom-application.properties.

Default: data.directory.location=${user.home}/.identity-service

config.directory.location

Config directory where Identity Service searches for the application.properties and secret.properties file. By default, this option refers to the data directory ${data.directory.location}.

Database connection

Identity Service uses an HSQL database by default, which is included in the release. It is automatically created in the file system for testing purposes and requires no further configuration.
Do not use the HSQL database in production environments.

HSQLDB

If you run multiple instances of Identity Service in parallel, do not use the same HSQL database. Change the parameter data.directory.location of every instance accordingly.

Microsoft SQL Server

When using Microsoft SQL Server, set the collation to a case-sensitive format (for example, Latin1_General_CS_AS) when creating the database.

Change the database connection by editing the following properties:

db.use

Specifies whether a direct database connection (JDBC) or a container-managed database connection (JNDI) is established.

Use JNDI if there are several web applications in the container (such as Apache Tomcat) accessing the same database (see also Apache Tomcat JNDI documentation ). Use JDBC which means that no container configuration is necessary.

Allowed values: jndi, jdbc
Default: jdbc

db.type

Vendor-specific type of the database system used.

This is used internally to generate correct and optimized database queries.

Allowed values:

Database Type Example-URL

PostgreSQL

postgresql

jdbc:postgresql://localhost:5432/identity

Oracle Database

oracle

jdbc:oracle:thin:@myhost:1521:orcl

Microsoft SQL Server

sqlserver

jdbc:sqlserver://localhost:1433;databaseName=identity

HSQLDB

hsqldb

jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

Default: hsqldb

db.hibernate.schemaUpdate

Defines if and how the database schema is updated.

Allowed values: validate and update
Default: update

Direct database connection (JDBC)

To setup a direct database connection, the following parameters have to be set in addition to the preceding attributes:

db.jdbc.url

URL of the JDBC database connection.

Its value depends on the database system in use (see preceding table).

Default: jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

db.jdbc.username

Username of the database user.

Default: sa

db.jdbc.password

Password of the database user.

db.jdbc.maxActiveConnections

Maximum number of active database connections in the deployed Connection Pool.

Default: 50

db.jdbc.minActiveConnections

Minimum number of active database connections in the deployed Connection Pool.

Default: 1

Copy the corresponding JDBC driver to the folder %MAPAPPS%/WEB-INF/lib when using a JDBC connection.

Container managed database connection (JNDI)

To configure a database connection through JNDI, the following parameter has to be configured in addition to the three attributes listed preceding:

db.jndi.name

JNDI name to use by the container to query the database.

Default: java:comp/env/jdbc/identity

Additionally, the following steps have to be performed:

  1. Open the file server.xml which is located in the conf directory of the Apache Tomcat installation folder.

  2. Add the following entry to the <GlobalNamingResources> element:

    server.xml
    <Resource name="identitydb" auth="Container"
      type="javax.sql.DataSource"
      maxTotal="50"
      maxIdle="1"
      maxWaitMillis="10000"
      defaultAutoCommit="false"
      username="postgres"
      password="postgres"
      driverClassName="org.postgresql.Driver"
      url="jdbc:postgresql://localhost:5432/identity" />

    In this example this element is adjusted to the PostgreSQL database. If you are using a different database than PostgreSQL, adjust the attributes driverClassName and URL. The preceding table lists the driverClassNames and example database URLs for various databases.

  3. Adjust the values of the attributes username and password to the conditions in your system.

  4. Copy the JAR file that contains the JDBC driver for your database to the lib directory of your Apache Tomcat.

  5. Open the file context.xml from the META-INF directory of the Identity Service web application. To enable the element <ResourceLink name="jdbc/identity" global="identitydb" type="javax.sql.DataSource"/> remove the enclosing comment tags.

  6. Save all modified files and restart Apache Tomcat.

Container managed database connection with HikariCP (JNDI)

We recommend the usage of the Database Connection Pool HikariCP .

The configuration inside the server.xml looks then like:

server.xml
<Resource name="identitydb" auth="Container"
        factory="com.zaxxer.hikari.HikariJNDIFactory"
        type="javax.sql.DataSource"
        minimumIdle="1"
        maximumPoolSize="50"
        connectionTimeout="10000"
        dataSourceClassName="org.postgresql.ds.PGSimpleDataSource"
        dataSource.url="jdbc:postgresql://localhost:5432/identity"
        dataSource.user="postgres"
        dataSource.password="postgres" />

Next to the database driver it is required to install the following libraries inside the Tomcat lib directory:

Log settings

logging.logger.level

Level of detail for the log messages.

Possible values: TRACE, DEBUG, INFO, WARN, ERROR
Default value: WARN

logging.file.location

Log file location.

The default value is the folder of the Tomcat log files. To create Identity Service log files in the data directory of the web application use ${data.directory.location}/logs.

Default: ${catalina.base}/logs

logging.file.prefix

Name of the log files.

Default value: ct-identity-service

Additional logging options are described in the default-application.properties file, for example to enable or disable logging into the console, into files, and GELF logging.

Security settings

Changing the settings does not affect active sessions. New settings are applied only after a user logs in again. Active sessions can be terminated immediately by changing the value of the security.sharedSecret property.
security.ssl.trustAny

Enables support for self-signed certificates for HTTPS connections.

You should not enable this in production installations.

Allowed values: true, false
Default: false

security.login.redirect.trusted.hosts

Comma-separated list of accepted hostnames.

This list defines redirection destinations accepted if the Identity Service login process is using redirects to forward the client to a specific site after successful login. This ensures that users are protected from attackers who intend to redirect them to a malicious site.

Adding hostnames to this property is only required in special situations, for example if applications are integrated with Identity Service login that are deployed on a different host. This often occurs while using development projects.

Wildcards can also be used to achieve trust on a domain basis.

Default: localhost
Example: *.gishost.org

security.oauth.clientId

OAuth client ID available after registering the Identity Service at the identity provider.

security.oauth.clientSecret

OAuth client secret available after registering the Identity Service at the identity provider.

security.oauth.token.minimalLifetimeSecondsLeft

Minimum lifetime of an access token in seconds before it should be refreshed.

security.oauth.provider

Defines the current identity provider. Possible values are arcgis or keycloak.

security.oauth.provider.arcgis.url

The URL of the ArcGIS Enterprise portal or the ArcGIS Online organization. Example: https://myorg.maps.arcgis.com or https://www.example.com/portal.

security.oauth.provider.arcgis.url.internal

The URL of the ArcGIS Enterprise portal which should be used for internal communication. This configuration is optional. By default the value of security.oauth.provider.arcgis.url is used. Example: https://myhost.example.com/portal.

security.oauth.provider.arcgis.organizations

If you set security.oauth.provider.arcgis.url=https://www.arcgis.com, use this parameter to specify which ArcGIS Online organizations can be connected. Example: myorg.maps.arcgis.com,anotherorg.maps.arcgis.com.

security.oauth.provider.arcgis.roles

Defines a mapping of roles names and group names in ArcGIS Enterprise portal or ArcGIS Online to role names used in applications connecting to this Identity Service. The syntax is as follows: <name1>=<role1>,<role2>; <name2>=<role3>.

For example, the value org_admin=maAdmin,otherAdmin; Editors::admin=maEditor defines that the role name org_admin is translated into the roles names maAdmin and otherAdmin. The Editors group of the admin group owner is translated to the maEditor role.

Instead of specifying group name and owner, you can also use the group ID:

For example, the value org_admin=maAdmin,otherAdmin; 12a12ab1a1a12345678abc1abc1abcd1=maEditor defines that group 12a12ab1a1a12345678abc1abc1abcd1 is translated to the maEditor role.

Default: org_admin=maAdmin,solrAdmin,mon_Administrator,tc_Administrator;org_publisher=maEditor.

security.oauth.provider.arcgis.roles.encodeGroupsWithTitleAndOwner

Defines, whether group names from ArcGIS Enterprise portal or ArcGIS Online are encoded as 'Title::owner'.

If the value is true, group names are encoded as title::owner. If the value is false, the group ID is used instead.

The default value is true.

security.oauth.provider.arcgis.roles.includeMappedRolesOnly

If the value is true, only those roles are returned which are defined in security.oauth.provider.arcgis.roles. If the value is false, all roles are returned.

The default value is false.

security.oauth.provider.arcgis.groups

Defines a mapping of group names in ArcGIS Enterprise portal or ArcGIS Online to group names used in applications connecting to this Identity Service. The syntax is as follows: <name1>=<group1>,<group2>; <name2>=<group3>

For example, the value Editors::admin=Editors defines that the Editors group of the admin group owner is translated to the Editors group.

Instead of specifying group name and owner, you can also use the group ID:

For example, the value 12a12ab1a1a12345678abc1abc1abcd1=Editors defines that group 12a12ab1a1a12345678abc1abc1abcd1 is translated to the Editors group.

The default value is empty.

security.oauth.provider.arcgis.groups.encodeGroupsWithTitleAndOwner

Defines, whether group names from ArcGIS Enterprise portal or ArcGIS Online are encoded as 'Title::owner'.

If the value is true, group names are encoded as title::owner. If the value is false, the group ID is used instead.

The default value is true.

security.oauth.provider.arcgis.groups.includeMappedGroupsOnly

If the value is true, only those groups are returned which are defined in security.oauth.provider.arcgis.groups. If the value is false, all groups are returned.

The default value is true.

security.oauth.provider.keycloak.url

The base URL of the Keycloak instance.

Example: https://www.example.com/authn

security.oauth.provider.keycloak.realm

The name of the Keycloak realm for which access is allowed.

security.oauth.provider.keycloak.revokeRefreshTokens

Enables the revocation of refresh tokens on logout or when a user session expires. As a side effect, revocation of tokens leads to a global logout of the user at Keycloak. Set to false to disable this behavior.

security.oauth.provider.keycloak.scopes

Enables the definition of custom OpenID Connect scopes sent on login and token retrieval. If empty, then the default is openid,profile,email,offline_access.

security.oauth.provider.keycloak.roles

Defines a mapping of roles names from Keycloak to role names used in applications connecting to this Identity Service. The syntax is as follows: <name1>=<role1>,<role2>; <name2>=<role3>.

For example, the value some_keycloak_role=maAdmin,otherAdmin; some_other_keycloak_role=maEditor defines that the role name some_other_keycloak_role is translated into the roles names maAdmin and otherAdmin. The role some_other_keycloak_role is translated to the maEditor role.

Default value is empty (all roles are forwarded without alteration).

security.oauth.provider.keycloak.roles.includeMappedRolesOnly

If the value is true, only those roles are returned which are defined in security.oauth.provider.keycloak.roles. If the value is false, all roles are returned.

The default value is false.

security.oauth.provider.keycloak.groups

Defines a mapping of group names from Keycloak to group names used in applications connecting to this Identity Service. The syntax is as follows: <name1>=<group1>,<group2>; <name2>=<group3>

For example, the value some_keycloak_group=Editors defines that the group some_keycloak_group is translated to the Editors group.

The default value is empty (all group names are forwarded without alteration).

security.oauth.provider.keycloak.groups.includeMappedGroupsOnly

If the value is true, only those groups are returned which are defined in security.oauth.provider.keycloak.groups. If the value is false, all groups of a user are returned.

The default value is false.

security.oauth.tokenRules

Declares URLs to which access tokens are sent and how they should be transmitted.

The value is a semicolon-separated list of rules: <rule_1>[;<rule_n>]…​

A rule is a comma-separated list of URLs followed by a transport mode: <url_1>[,<url_n>]…​[,<transport_mode>]

Supported transport modes are:

  • BEARER (default): The token should be sent as HTTP Header Authorization: Bearer <token>.

  • TOKEN: The token should be sent as URL query parameter …​&token=<token>.

  • ACCESS_TOKEN: The token should be sent as URL query parameter …​&access_token=<token>.

Example:

http://www.example.com/arcgis,TOKEN;http://other.example.com/service1,http://other.example.com/service2,ACCESS_TOKEN

The example defines that an access token should be sent to http://www.example.com/arcgis as …​&token=<token>. In addition, an access token should also be sent to http://other.example.com/service1 and http://other.example.com/service2 as …​&access_token=<token>.

Use the URL prefix deny: to define that no access tokens should be sent to a URL. Example: deny:http://my.example.com/service;

security.oauth.tokenRules.addDefaults

If the value is true, some values for security.oauth.tokenRules are automatically added for the configured identity provider and the Identity Service. If the value is false, no automatic values are created.

The default value is false. The configuration option should not be used anymore and will be removed in future versions.

security.session.maxIdleTimeInSeconds

The allowed idle time for sessions in seconds. Sessions that are idle for longer than this value are invalidated by a background task. The default value is 3600 seconds, which is one hour.

security.session.cookieName

The name of the session cookie. The default is ctIDENTITY.

security.session.cookieDomain

The name of the session cookie’s domain, e.g. example.com. By default this value is empty, which means that the session cookie is bound to the hostname from which it was set.

security.session.enforceSecureAndSameSiteNone

Forces the flags samesite=none and secure on the session cookie. The default value is false. The setting only has an effect if the Identity Service is requested via an HTTPS connection

security.sharedSecret

The text you enter here will be used as a key for encrypting data that needs to be exchanged between different parts of the application. To prevent unauthorized access or manipulation of data you should keep this secret private, like a password. You must create this key yourself. It must have a length of at least 32 characters for security reasons.

You can create a secure key with these commands, for example:

Windows PowerShell
> [Convert]::ToBase64String((1..32|%{[byte](Get-Random -Minimum ([byte]::MinValue) -Maximum ([byte]::MaxValue))}))
Linux
$ openssl rand -base64 32

CORS settings

The following settings are required for Cross Origin Request support.

cors.allowed.origins

List of base URLs of websites which are allowed to access the service with CORS.

* can be used as wildcard.

Sample:

  • http://mydomain.net,http://otherdomain.de

  • http*://*.mydomain.net:*
    Allows access from any subdomain of mydomain.net via http and https from any port.