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) is required, the change has to be made in this file. Any further changes have to be made in the following file.

  3. [data.directory.location]/application.properties
    Editing this file is the recommended way to make configuration changes. The default data directory (data.directory.location) of the Identity Service is ${user.home}/.identity-service.

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

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

configuration.watch.changes

Monitoring of the ${data.directory.location}/application.properties file.

If enabled, configuration settings can be changed without restarting the web application. The configuration file must be present when the web application is started so that it can be monitored.

Default: true

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

Some rules are generated automatically for the configured identity provider and the Identity Service.

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, the session cookie is not bound to any domain.

security.session.enforceSecureAndSameSiteNone

Forces the flags samesite=none and secure on the session cookie. This setting may be relevant for implementing cross-domain scenarios. The default value is false.

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.