7.5:dev:configuration:backend

The application uses a Spring boot configuration in the application.properties files. All the configuration items which are used solely for idm begin with idm. prefix. The configuration items from the file can be overloaded through a setting agenda in the gui ⇒ a server restart isn't needed for changing the configuration with idm. prefix, which was one of the main goals. The configuration is saved in the database. Use ConfigurationService for reading and saving configuration items.

Naming conventions of the configuration items in idm:

  • idm. - configuration items for the needs of idm
  • idm.pub. - public configuration items - published on a public rest endpoint (e.g. version)
  • idm.sec. - system configuration items - published on a secure rest endpoint and available for configuration by the application administrator. They are used for backend configuration. If configuration item is confidential, then value is stored in confidential storage and value is not send to frontend, application logs etc. Items with key password, token, secret are automatically set as confidential - use it for configuration items defined in property file only.
  • idm.sec.<module>. or idm.pub.<module>. - configuration items of the given module. Use ModuleDescriptor#getId() as <module>.
  • if the name of a configuration item contains thepassword or token chain, the value of the configuration item is hidden in the rest interface listing (or rather replaced with substitute characters).
  • It is better to use constants for keys, e.g. ConfigurationService.IDM_PUBLIC_PROPERTY_PREFIX + "core.identity.delete" - using seperator constant in key name suffix is not preferred - constant can be simply found by key suffix ("ctrl-f" + "core.identity.delete").

Cache is used for reading configuration values - default spring boot cache (ConcurrentHashMap) is configured for now. Value in cache is cleared by an active (save, delete) operation.

We are using Spring profiles: Doc.

Start server under defined profile (add JAVA_OPTS parameters):

-Dspring.profiles.active=production

Configured profiles

  • default - the default profile - configured to db h2. If a developer downloads the project from Git, the application will run without any other configuration over h2 database with demo data (by admin user …). Default profile is used for issuing a demo.
  • dev - developing profile configured to postgresql. In the future, we can move the configuration itself to special profiles - their combinations (e.g. test+ postgresql or dev + mysql). We will be able to cover more variants of environment versus database.
  • test - test profile - configured to db h2.
  • release - release profile - all modules in CzechIdM repository are included, they are released together under one version.

External configuration uses Spring: Doc.

Start server with external path to configuration (add JAVA_OPTS parameters):

--spring.config.location=classpath:/default.properties,classpath:/override.properties

In the application profile (application.properties) and overloadable via ConfigurationService.

# Application stage (development, test, production (default))
idm.pub.app.stage=
# Application instance / server id - is used for scheduler etc.
idm.pub.app.instanceId=idm-primary
# Enable forest index for tree structures
idm.sec.app.forest.index.enabled=true
# global date format on BE. Used in notification templates, logs, etc. FE uses localization key 'core:format.date'.
idm.pub.app.format.date=dd.MM.yyyy
# global datetime format on BE. Used in notification templates, logs, etc. FE uses localization key 'core:format.datetime'.
idm.pub.app.format.datetime=dd.MM.yyyy HH:mm
# create demo data at application start
idm.sec.core.demo.data.enabled=true
# demo data was created - prevent to create demo data duplicitly
idm.sec.core.demo.data.created=false

In the application profile (application.properties)

# audit table suffix
spring.jpa.properties.org.hibernate.envers.audit_table_suffix=_a
# modified flag for all audited columns
spring.jpa.properties.org.hibernate.envers.global_with_modified_flag=true
# prevent to modify attributes created, creator etc.
spring.jpa.properties.hibernate.ejb.interceptor=eu.bcvsolutions.idm.core.model.repository.listener.AuditableInterceptor
# enable / disable audit (envers)
spring.jpa.properties.hibernate.listeners.envers.autoRegister=true
 
#
# DB ddl auto generation by hibernate is disabled - flyway database migration is used
spring.jpa.generate-ddl=true
spring.jpa.hibernate.ddl-auto=update
#
# DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
spring.datasource.url=jdbc:postgresql://localhost:5432/bcv_idm_storage
spring.datasource.username=*****
spring.datasource.password=*****
spring.datasource.driver-class-name=org.postgresql.Driver
# String boot properties for Activiti workflow engine
# https://github.com/Activiti/Activiti/blob/master/modules/activiti-spring-boot/spring-boot-starters/activiti-spring-boot-starter-basic/src/main/java/org/activiti/spring/boot/ActivitiProperties.java
# let activiti to manage their schema
spring.activiti.databaseSchemaUpdate=true
# disable automatic jpa entities persisting - dto usage is prefered
spring.activiti.jpaEnabled=false
# Automatic process deployment
spring.activiti.checkProcessDefinitions=true
# path to automatically deployed definitions - should be the same in all modules
spring.activiti.processDefinitionLocationPrefix=classpath*:eu/bcvsolutions/idm/workflow/
# definitions name pattern - subfolders can be used
spring.activiti.processDefinitionLocationSuffixes=**/**.bpmn20.xml

In the application profile (application.properties) and overloadable via ConfigurationService.

# allowed origins for FE
# the first value is used as frontend url to notification templates
idm.pub.security.allowed-origins=http://localhost:3000,http://localhost
# auth token
# - expiration in milis
idm.sec.security.jwt.expirationTimeout=36000000
# - secret jwt password
idm.sec.security.jwt.secret.token=idmSecret
# - extend JWT token expiration period on each successful request
idm.sec.security.jwt.token.extend.expiration=true
# recaptcha
# - recaptchaservice endpoint 
idm.sec.security.recaptcha.url=https://www.google.com/recaptcha/api/siteverify
# - secret key, can be generated here https://www.google.com/recaptcha/admin
idm.sec.security.recaptcha.secretKey=xxx

Allowed-origins defines, which resources can use backend API methods. e.g. When there is a web server serving as reverse proxy on the same server as BE, the http://localhost:3000 may be the right value.

In the application profile (application.properties)

# Enable flyway migrations. 
# @see https://proj.bcvsolutions.eu/ngidm/doku.php?id=navrh:databazove_scripty
flyway.enabled=false

Module configuration (flyway-core.properties)

## Core Flyway configuration
#
# Whether to automatically call baseline when migrate is executed against a non-empty schema with no metadata table. 
# This schema will then be baselined with the baselineVersion before executing the migrations. 
# Only migrations above baselineVersion will then be applied.
# This is useful for initial Flyway production deployments on projects with an existing DB.
# Be careful when enabling this as it removes the safety net that ensures Flyway does not migrate the wrong database in case of a configuration mistake!
flyway.core.baselineOnMigrate=true
#
# The name of Flyway's metadata table (default **schema_version**).
# By default (single-schema mode) the metadata table is placed in the default schema for the connection provided by the datasource.
flyway.core.table=idm_schema_version_core
#
# Comma-separated list of locations to scan recursively for migrations. The location type is determined by its prefix.
# Unprefixed locations or locations starting with classpath: point to a package on the classpath and may contain both sql and java-based migrations.
# Locations starting with filesystem: point to a directory on the filesystem and may only contain sql migrations. 
# IdmFlywayMigrationStrategy resolves used jdbc database dynamically - ${dbName} in location could be used.
flyway.core.locations=classpath:eu/bcvsolutions/idm/core/sql/${dbName}

Information about module can be defined in property file (module-<module>.properties - e.g. module-core.properties). This property file is loaded by PropertyModuleDescriptor. Module properties are not editable through ConfigurationService (idm.pub. prefix is not used).

# mapping pom.xml properties by default
# add custom properties if needed
#
# module version
module.<module>.build.version=@project.version@
# TODO: build number
# module.<module>.build.number=@buildNumber@
# module.<module>.build.timestamp=@timestamp@
# module vendor
module.<module>.build.vendor=@project.organization.name@
module.<module>.build.vendorUrl=@project.organization.url@
module.<module>.build.vendorEmail=info@bcvsolutions.eu
# module description
module.<module>.build.name=@project.name@
module.<module>.build.description=@project.description@

In the application profile (application.properties)

## Swagger config
# enable swagger endpoint (can be disabled for development etc.)
springfox.documentation.swagger.enabled=true
# endpoint with exposed documentations. Documentations are exposed by module e.g. <server>/api/doc?group=core
springfox.documentation.swagger.v2.path=/api/doc
#
# for static documentation generation puprose => internal usage mainly in test stage. Swagger specification on then rest endpoint is exported to given file e.g. <module>/target/swagger/swagger.json. Properties with @ are automatically filled from pom.xml properties.
# output directory and filename for swagger export - other build parts are dependent on this.
springfox.documentation.swagger.outputDir=@swagger.output.dir@
springfox.documentation.swagger.outputFilename=@swagger.output.filename@

In the application profile (application.properties) - overloadable via ConfigurationService.

idm.sec.core.emailer.test.enabled=false # enable test mode - in this mode, emails are not send
idm.sec.core.emailer.protocol=smtps # http://camel.apache.org/mail.html
idm.sec.core.emailer.host=smtp.gmail.com
idm.sec.core.emailer.port=465
idm.sec.core.emailer.username=servis.bcvsolutions@gmail.com
idm.sec.core.emailer.password=SuperHesloBCV
idm.sec.core.emailer.from=idm@bcvsolutions.eu # The FROM email address.

In the application profile (application.properties) - overloadable via ConfigurationService.

idm.sec.core.notification.template.folder=classpath*:/templates/ # classpath for loading templates
idm.sec.core.notification.template.fileSuffix=**/**.xml # template suffix

In the application profile (application.properties) - overloadable via ConfigurationService.

idm.sec.core.script.folder=classpath*:/eu/bcvsolutions/idm/scripts/ # classpath for loading scripts
idm.sec.core.script.fileSuffix=**/**.xml

In the application profile (application.properties).

# Enable scheduler
scheduler.enabled=true
# How many times will be trigger cron tasks (ms)
scheduler.task.queue.process=3600000
# Application settings for QUARTZ (for current mvn profile)
scheduler.properties.location=/quartz-dev.properties

In the application profile (application.properties) - overloadable via ConfigurationService.

# supports delete identity
idm.pub.core.identity.delete=true
#
# default password change type for custom users, one of values: 
# DISABLED - password change is disable
# ALL_ONLY - users can change passwords only for all accounts
# CUSTOM - users can choose for which accounts change password
idm.pub.core.identity.passwordChange=ALL_ONLY
#
# required old password for change password
idm.pub.core.identity.passwordChange.requireOldPassword=true
#
# create default identity's contract, when identity is created
idm.pub.core.identity.create.defaultContract.enabled=true

In the application profile (application.properties) - overloadable via ConfigurationService.

# Default user role will be added automatically, after an identity is logged in
# could contains default authorities and authority policies configuration
# for adding autocomplete or all record read permission etc.
idm.sec.core.role.default=userRole
# Admin user role
idm.sec.core.role.admin=superAdminRole

Tree structures configuration properties.

In the application profile (application.properties) - overloadable via ConfigurationService.

# Default tree type (uuid or code). More in Default organizational structure doc.
idm.sec.core.tree.defaultType=
# Default tree node (uuid) - is used, when default contract is created. More in Contractual relationship doc.
idm.sec.core.tree.defaultNode=

Internal properties used for tree indexing (forest index) - holds index state:

# forest index is valid. Is set to false, when index exception occurs and tree index has to be rebuild 
idm.sec.core.treeType.<tree-code>.valid=true
# rebuild index in progress (true). When tree type index rebuild is in progress, then tree node cannot be created / updated / deleted.
idm.sec.core.treeType.<tree-code>.rebuild=false

In the application profile (application.properties) - overloadable via ConfigurationService. Every processor could have his own configuration properties under prefix:

# disable / enable event procesor
idm.sec.<module>.processor.<name>.enabled=true
# override event types for given processor
idm.sec.<module>.processor.<name>.eventTypes=CREATE,UPDATE

Where <module> is processor's module a <name> is processor's name (see overridable processor's methods). Filled configuration properties will be shown on processor's content.

Common configuration properties for all processors:

  • enabled - on / off
  • order - comming soon
  • eventTypes - list of event types (separated by comma) to which given processor reacts

Exists processors configuration: implemented proccessors.

## Global property that allow disable or enable sending notification from WF
idm.sec.core.wf.notification.send=false
## Enable sending notification of changing roles to user, whose account will be modified
idm.sec.core.wf.notification.applicant.enabled=true
## Enable sending notification of changing roles to user, who made request
idm.sec.core.wf.notification.requester.enabled=false

Properties is not overloadable via ConfigurationService. For more info see

# Cipher secret key for crypt values in confidential storage
# for crypt values is used secretKey - secret.key
# Can be empty => confidential storage will not be crypted, application cannot be used in production (dev, test only).
cipher.crypt.secret.key=
# or secretKey defined in the external file - secret.keyPath
# cipher.crypt.secret.keyPath=/path/to/key

In the application profile (application.properties) - overloadable via ConfigurationService. Every filter could have his own configuration properties under prefix:

# filter implementation
idm.sec.<module>.filter.<entity>.<name>.impl=<beanName>

Where:

  • <module> is filter's module - overriden module has to be used (e.g. default filter is in core module, then core module identifier has to be used)
  • <entity> is entity class simple name - filter will be applied to this domain type (e.g. IdmIdentity)
  • <name> is filter's bean name - see implemented filters

Common configuration properties for all filters:

  • impl - contains implementation (Spring bean name) of given filter. When property of given <name> will be set for filter, then this implementation will be used for filtering. New module could register new filter for defined entity and name - by this configuration one of provided implementation will be selected and used.

Exists filters configuration: implemented filters.

UUID of system, against which to user will be authenticated.

# ID system against which to authenticate
idm.sec.security.auth.systemId=

If you want to use redeploy and backup for example in agenda (notification template), you must define default backup folder see:

# configuration property for default backup 
idm.sec.core.backups.default.folder.path=/tmp/backup

For outgoing http communication, you can set a proxy (currently used only by ReCaptcha).

Server restart is needed to apply this configuration change.

# Proxy for HTTP requests
idm.sec.core.http.proxy=12.34.56.78:1234

CGLIB for creating proxies has to be enforced. Is possible to use annotations on methods, which is not defined in service interface. Prevent to use some logic in service constructors (will be called twice) and always define annotations in implementation class, read more.

# use cglib for proxies by default
spring.aop.proxy-target-class=true

VS configurations allows define implementers via assigned IdM role or directly by selected identities. If you do not define none directly implementers and none role in VS configuration, then will be used implementers from default role. Default role can be defined in configuration:

# If you do not define default role, then will be used **superAdminRole** as default!
idm.sec.vs.role.default=<some-code-of-role>
# It's possible to send additional attributes, when password is changed (mapped attributes with flag sendOnPasswordChange)
# - true: additional password attributes will be send in one provisioning operation together with password
# - false: additional password attributes will be send in new provisioning operation, after password change operation
idm.sec.acc.provisioning.sendPasswordAttributesTogether=true