Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
tutorial:adm:czechidm_installation [2021/03/08 10:37]
svandav 		tutorial:adm:czechidm_installation [2022/12/20 10:11] (current)
kralikf [9. Deploy the CzechIdM]
Line 3: Line 3:
 {{tag>installation jdbc quickstart encryption}} {{tag>installation jdbc quickstart encryption}}
  
-We expect that the server is prepared as described in [[tutorial:adm:server_preparation|]].+We expect that the server is prepared as described in [[.:server_preparation|]].
  
 This tutorial shows how to install full production-ready version of CzechIdM on standard software setup (Java, PostgreSQL, Tomcat, Apache HTTPd). If you are looking for a demo installation please see [[:getting-started|]]. This tutorial shows how to install full production-ready version of CzechIdM on standard software setup (Java, PostgreSQL, Tomcat, Apache HTTPd). If you are looking for a demo installation please see [[:getting-started|]].
  
-<note tip>If you install CzechIdM on with Microsoft SQL Server database backend, please skip PostgreSQL-related sections and [[tutorial:adm:mssql_database_support|swap them for this tutorial]] instead.</note>+<note tip>If you install CzechIdM on with Microsoft SQL Server database backend, please skip PostgreSQL-related sections and [[.:mssql_database_support|swap them for this tutorial]] instead.</note> 
 + 
 ==== 1. Create DB user and database in PostgreSQL ==== ==== 1. Create DB user and database in PostgreSQL ====
 +If czech database collation should be used, install the czech language packs.
 +<code bash>
 +dnf install langpacks-cs
 +</code>
 +
 +
 Switch the user from root to postgres and use **psql** to add the user and database into PostgreSQL: Switch the user from root to postgres and use **psql** to add the user and database into PostgreSQL:
  
Line 52: Line 60:
 ==== 3. Configure environment properties. Select application profile ==== ==== 3. Configure environment properties. Select application profile ====
  
-Edit the configuration file ''/etc/systemd/system/tomcat.service'' - edit the line with environment variable choosing the appropriate application profile. We use **production** profile in our example, which enables you to configure production-ready instace of the identity manager. +Edit the configuration file ''/etc/systemd/system/tomcat.service'' - edit the line with environment variable choosing the appropriate application profile. We use **production** profile in our example, which enables you to configure production-ready instace of the identity manager. <note>The **dev** profile is for development and testing environments and as such it has debug logging enabled. For production deployment, use a profile named **production** as is shown in the example. The profile naming convention is mandatory because other CzechIdM configuration depends on it.</note>
-<note>The **dev** profile is for development and testing environments and as such it has debug logging enabled. For production deployment, use a profile named **production** as is shown in the example. The profile naming convention is mandatory because other CzechIdM configuration depends on it.</note> +
  
 Change ​the following line: Change ​the following line:
 +
 <code bash> <code bash>
 Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Djavax.servlet.request.encoding=UTF-8' Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Djavax.servlet.request.encoding=UTF-8'
 +
 </code> </code>
 +
 into: into:
 +
 <code bash> <code bash>
-Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Djavax.servlet.request.encoding=UTF-8 -Dspring.profiles.active=production' +Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Djavax.servlet.request.encoding=UTF-8 -Dlog4j2.formatMsgNoLookups=true -Dspring.profiles.active=production' 
 </code> </code>
  
 Reload ​systemd after the changes: Reload ​systemd after the changes:
 +
 <code bash> <code bash>
 systemctl daemon-reload systemctl daemon-reload
 +
 </code> </code>
 +
 +
 ==== 4. Create CzechIdM configuration folders ==== ==== 4. Create CzechIdM configuration folders ====
 In CzechIdM, you can store all deployment-specific configuration (i.e. database credentials) outside the war file. This is a configure-once approach which greatly simplifies future deployments. In CzechIdM, you can store all deployment-specific configuration (i.e. database credentials) outside the war file. This is a configure-once approach which greatly simplifies future deployments.
Line 84: Line 99:
  
 ==== 5. Create CzechIdM configuration ==== ==== 5. Create CzechIdM configuration ====
-Now we will create configuration files the CzechIdM will use. + 
-<note>Code snippets in this chapter can be **mostly** copy-pasted or (but please read through whole chapter to be aware of setting you have to adjust). Configuring the CzechIdM is about altering four or five lines altogether.</note> +Now we will create configuration files the CzechIdM will use. <note>Code snippets in this chapter can be **mostly** copy-pasted or (but please read through whole chapter to be aware of setting you have to adjust). Configuring the CzechIdM is about altering four or five lines altogether.</note> 
-  * The **/opt/czechidm/etc/secret.key** is a file with confidential storage secret key. This key has to have 128 bit (= 16 bytes) or 256 bit (= 32b bytes). The length of the key determines the AES cipher used (AES-128 od AES-256).<code> + 
-cat /dev/urandom | tr -dc 'a-z0-9' | head -c 32 > /opt/czechidm/etc/secret.key+   * The **/opt/czechidm/etc/secret.key**  is a file with confidential storage secret key. This key has to have 128 bit (= 16 bytes) or 256 bit (= 32b bytes). The length of the key determines the AES cipher used (AES-128 od AES-256). 
 + 
 +<code> 
 +cat /dev/urandom | tr -dc 'a-z0-9' | head -c 32> /opt/czechidm/etc/secret.key 
 </code> </code>
-  * The **/opt/czechidm/etc/quartz-production.properties** file stores, the Quartz scheduler configuration. You can use the following snippet as a production-safe configuration file.<file properties quartz-production.properties>+ 
 +  * The **/opt/czechidm/etc/quartz-production.properties**  file stores, the Quartz scheduler configuration. You can use the following snippet as a production-safe configuration file. 
 + 
 +<file properties quartz-production.properties>
 org.quartz.scheduler.instanceName=idm-scheduler-instance org.quartz.scheduler.instanceName=idm-scheduler-instance
 org.quartz.scheduler.instanceId=AUTO org.quartz.scheduler.instanceId=AUTO
Line 101: Line 123:
 org.quartz.jobStore.misfireThreshold=60000 org.quartz.jobStore.misfireThreshold=60000
 org.quartz.jobStore.tablePrefix=qrtz_ org.quartz.jobStore.tablePrefix=qrtz_
 +
 +
 </file> </file>
-  * The **/opt/czechidm/etc/logback-spring.xml** specifies logging configuration. This is the default logging configuration that you can use out of the box. + 
-<note important>Since IdM version **11.0.0** use DB appender `eu.bcvsolutions.idm.core.exception.IdmDBAppender` instead `ch.qos.logback.classic.db.DBAppender`!</note>+  * The **/opt/czechidm/etc/logback-spring.xml**  specifies logging configuration. This is the default logging configuration that you can use out of the box. 
 <file xml logback-spring.xml> <file xml logback-spring.xml>
 <?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
Line 109: Line 134:
 <!-- http://logback.qos.ch/manual/appenders.html --> <!-- http://logback.qos.ch/manual/appenders.html -->
 <configuration> <configuration>
 +    <!-- !!!BEWARE!!! The specification of the LOG PATTERNS overrides the default configuration and increases the maximum length of the %logger{<size>} attribute.
 +    It is neccessary for correct function of the AUDIT logging feature (redmine ticket #2717). If AUDIT logger key is longer then the set limit it gets shortened
 +    and SIEM software is not able to parse logs properly. -->
 +    <property name="CONSOLE_LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} %5level %relative --- [%thread] %logger{60}.%M : %msg%n"/>
 +    <property name="FILE_LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} %5level %relative --- [%thread] %logger{60}.%M : %msg%n"/>
 +
     <include resource="org/springframework/boot/logging/logback/base.xml"/>     <include resource="org/springframework/boot/logging/logback/base.xml"/>
     <springProperty name="spring.profiles.active" source="spring.profiles.active"/>     <springProperty name="spring.profiles.active" source="spring.profiles.active"/>
Line 117: Line 148:
         <logger name="org.hibernate.SQL" level="INFO"/>         <logger name="org.hibernate.SQL" level="INFO"/>
         <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="INFO"/>         <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="INFO"/>
 +        <logger name="AUDIT" level="INFO"/>
     </springProfile>     </springProfile>
  
Line 125: Line 157:
         <springProperty name="spring.datasource.password" source="spring.datasource.password"/>         <springProperty name="spring.datasource.password" source="spring.datasource.password"/>
  
-        <appender name="DB" class="ch.qos.logback.classic.db.DBAppender"> +        <appender name="DB" class="eu.bcvsolutions.idm.core.exception.IdmDbAppender"> 
-            <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource"> +
-                <driverClass>${spring.datasource.driver-class-name}</driverClass> +
-                <url>${spring.datasource.url}</url> +
-                <user>${spring.datasource.username}</user> +
-                <password>${spring.datasource.password}</password> +
-            </connectionSource>+
         </appender>         </appender>
  
Line 146: Line 173:
         <logger name="org.hibernate.SQL" level="INFO"/>         <logger name="org.hibernate.SQL" level="INFO"/>
         <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="INFO"/>         <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="INFO"/>
 +        <logger name="AUDIT" level="INFO"/>
  
     </springProfile>     </springProfile>
  
 </configuration> </configuration>
 +
 +
 </file> </file>
-  * The most important file is **/opt/czechidm/etc/application-production.properties** (application-PROFILE.properties, where the PROFILE is the profile you run the IdM under). You can use most of the file as-is, there is a bit of configuration needed though. This is a template file:<file properties application-production.properties>+ 
 +  * The most important file is **/opt/czechidm/etc/application-production.properties**  (application-PROFILE.properties, where the PROFILE is the profile you run the IdM under). You can use most of the file as-is, there is a bit of configuration needed though. This is a template file: 
 + 
 +<file properties application-production.properties>
 # Doc: https://wiki.czechidm.com/devel/dev/configuration/backend # Doc: https://wiki.czechidm.com/devel/dev/configuration/backend
- +
 idm.pub.app.instanceId=idm-primary idm.pub.app.instanceId=idm-primary
 idm.pub.app.stage=production idm.pub.app.stage=production
-  + 
-spring.datasource.url=jdbc:postgresql://localhost:5432/czechidm+spring.datasource.jdbcUrl=jdbc:postgresql://localhost:5432/czechidm
 spring.datasource.username=czechidm spring.datasource.username=czechidm
 spring.datasource.password=********** TODO ********* spring.datasource.password=********** TODO *********
Line 166: Line 199:
 spring.jpa.hibernate.ddl-auto=none spring.jpa.hibernate.ddl-auto=none
 flyway.enabled=true flyway.enabled=true
-  
  
 scheduler.properties.location=quartz-production.properties scheduler.properties.location=quartz-production.properties
Line 178: Line 210:
 # System.getProperty("user.home")/idm_data will be used if no path is given # System.getProperty("user.home")/idm_data will be used if no path is given
 idm.sec.core.attachment.storagePath=/opt/czechidm/data idm.sec.core.attachment.storagePath=/opt/czechidm/data
-# configuration property for default backup +# configuration property for default backup
 idm.sec.core.backups.default.folder.path=/opt/czechidm/backup idm.sec.core.backups.default.folder.path=/opt/czechidm/backup
  
-  
 idm.pub.security.allowed-origins=http://localhost idm.pub.security.allowed-origins=http://localhost
 # Generate JWT token security string as "cat /dev/urandom | tr -dc 'a-z0-9' | head -c VALUE" where VALUE can be from 1 to 255. # Generate JWT token security string as "cat /dev/urandom | tr -dc 'a-z0-9' | head -c VALUE" where VALUE can be from 1 to 255.
Line 203: Line 234:
 # idm.sec.core.emailer.password=password # idm.sec.core.emailer.password=password
 idm.sec.core.emailer.from=czechidm@localhost idm.sec.core.emailer.from=czechidm@localhost
- +
 # Default user role will be added automatically, after an identity is logged in # Default user role will be added automatically, after an identity is logged in
 # could contains default authorities and authority policies configuration # could contains default authorities and authority policies configuration
Line 214: Line 245:
 spring.servlet.multipart.max-file-size=100MB spring.servlet.multipart.max-file-size=100MB
 spring.servlet.multipart.max-request-size=100MB spring.servlet.multipart.max-request-size=100MB
 +
 +
 </file> </file>
  
 === Adjust database configuration === === Adjust database configuration ===
-If you followed this howto, the only thing you should need to adjust is a **spring.datasource.password** propetry. Set it to the password for czechidm user in PostgreSQL. + 
-If necessary, adjust other database connection properties... <code properties>+If you followed this howto, the only thing you should need to adjust is a **spring.datasource.password**  propetry. Set it to the password for czechidm user in PostgreSQL. If necessary, adjust other database connection properties… 
 + 
 +<code properties>
 spring.datasource.url=jdbc:postgresql://localhost:5432/czechidm spring.datasource.url=jdbc:postgresql://localhost:5432/czechidm
 spring.datasource.username=czechidm spring.datasource.username=czechidm
Line 225: Line 260:
 spring.datasource.validationQuery=SELECT 1 spring.datasource.validationQuery=SELECT 1
 spring.datasource.test-on-borrow=true spring.datasource.test-on-borrow=true
 +
 +
 </code> </code>
  
 === Generate JWT token === === Generate JWT token ===
-Set value of the **idm.sec.security.jwt.secret.token** property as is described in the template file:<code properties>+ 
 +Set value of the **idm.sec.security.jwt.secret.token**  property as is described in the template file: 
 + 
 +<code properties>
 # Generate JWT token security string as "cat /dev/urandom | tr -dc 'a-z0-9' | head -c VALUE" where VALUE can be from 1 to 255. # Generate JWT token security string as "cat /dev/urandom | tr -dc 'a-z0-9' | head -c VALUE" where VALUE can be from 1 to 255.
 # We recommend the VALUE to be at least 25. # We recommend the VALUE to be at least 25.
 idm.sec.security.jwt.secret.token=********** TODO ********* idm.sec.security.jwt.secret.token=********** TODO *********
 +
 +
 </code> </code>
  
 === Local confidential storage === === Local confidential storage ===
  
-Local confidential storage is encrypted by AES algoritm. [[https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html|Read more]].  +Local confidential storage is encrypted by AES algoritm. [[https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html|Read more]]. Confidential storage is encrypted by a key found in **secret.key**  file you already created.
-Confidential storage is encrypted by a key found in **secret.key** file you already created.+
  
 There are two properties in application-production.properties that influence the confidential storage: There are two properties in application-production.properties that influence the confidential storage:
-  * You can set the key directly in the property file using **cipher.crypt.secret.key** property + 
-  * or (better) you can create separate file ''secret.key'' containing a random string. Then you reference this file with **cipher.crypt.secret.keyPath** property.+  * You can set the key directly in the property file using **cipher.crypt.secret.key**  property 
 +  * or (better) you can create separate file ''secret.key''  containing a random string. Then you reference this file with **cipher.crypt.secret.keyPath**  property.
  
 <note warning>CzechIdM doesn't contain any default key for crypt confidential storage. Please define it before you start using the IdM.</note> <note warning>CzechIdM doesn't contain any default key for crypt confidential storage. Please define it before you start using the IdM.</note>
  
-Confidential storage uses AES/CBC/PKCS5Padding ([[https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html|more info]]) algorithm which operates with 128bit or 256bit key. +Confidential storage uses AES/CBC/PKCS5Padding ([[https://docs.oracle.com/javase/7/docs/api/javax/crypto/Cipher.html|more info]]) algorithm which operates with 128bit or 256bit key. <note> Length of the key determines the cipher which will be used. If you use 128b (16byte) key, CzechIdM will use AES-128. If you use 256b (32byte) key, CzechIdM will use AES-256.
-<note> +
-Length of the key determines the cipher which will be used. If you use 128b (16byte) key, CzechIdM will use AES-128. If you use 256b (32byte) key, CzechIdM will use AES-256.+
  
   * OpenJDK/JDK 1.8u161 and all higher versions support AES-256 by default.   * OpenJDK/JDK 1.8u161 and all higher versions support AES-256 by default.
Line 255: Line 295:
  
 === Attachment store === === Attachment store ===
-In CzechIdM, users can sometimes add attachments (say, attach *.jpeg photo to their employee card request). Those files are stored in the attachment store. + 
-With the following property, you can configure, where the store is. If you used sample property file, the store is by-default located under /opt/czechidm/data .+In CzechIdM, users can sometimes add attachments (say, attach *.jpeg photo to their employee card request). Those files are stored in the attachment store. With the following property, you can configure, where the store is. If you used sample property file, the store is by-default located under /opt/czechidm/data .
  
 <code properties> <code properties>
Line 263: Line 303:
 # System.getProperty("user.home")/idm_data will be used if no path is given # System.getProperty("user.home")/idm_data will be used if no path is given
 idm.sec.core.attachment.storagePath=/opt/czechidm/data idm.sec.core.attachment.storagePath=/opt/czechidm/data
 +
 +
 </code> </code>
  
 === Environment === === Environment ===
  
-If you install CzechIdM in multiple environments (typically test and production), you can display a label in the navigation bar which will tell the users in which environment they work. The default value "production" doesn't display any label. Set the value to ''test'' to display the label marking the Test environment.+If you install CzechIdM in multiple environments (typically test and production), you can display a label in the navigation bar which will tell the users in which environment they work. The default value "production" doesn't display any label. Set the value to ''test''  to display the label marking the Test environment. 
 <code properties> <code properties>
 # Application stage (development, test, production (default)) # Application stage (development, test, production (default))
 idm.pub.app.stage=production idm.pub.app.stage=production
-</code> 
  
 +
 +</code>
  
  
Line 325: Line 369:
 </code> </code>
 ==== 9. Deploy the CzechIdM ==== ==== 9. Deploy the CzechIdM ====
-Download the latest CzechIdM version. Currently it is idm-app-10.4.1.war.+ 
 +Download the latest CzechIdM version. Currently it is idm-app-12.2.3.war.
  
 Ensure Tomcat is stopped: Ensure Tomcat is stopped:
 +
 <code> <code>
 systemctl stop tomcat.service systemctl stop tomcat.service
 +
 </code> </code>
 +
 Copy the identity manager WAR into webapps folder in Tomcat and name it ''idm.war'': Copy the identity manager WAR into webapps folder in Tomcat and name it ''idm.war'':
 <code> <code>
 cp idm-app-10.4.1.war /opt/tomcat/current/webapps/idm.war cp idm-app-10.4.1.war /opt/tomcat/current/webapps/idm.war
 +
 </code> </code>
-Check that the idm.war file is owned by Tomcat:+ 
 +Start the Tomcat container: 
 <code> <code>
-ls -l /opt/tomcat/current/webapps 
-</code> 
-If not, change its owner: 
-<code> 
-chown tomcat:tomcat /opt/tomcat/current/webapps/idm.war 
-</code> 
-Start the Tomcat container:<code> 
 systemctl start tomcat.service systemctl start tomcat.service
 +
 </code> </code>
 +
 If everything is set up right, the CzechIdM will deploy. Default log is ''/opt/tomcat/​current/logs/​catalina.out''. If everything is set up right, the CzechIdM will deploy. Default log is ''/opt/tomcat/​current/logs/​catalina.out''.
  
  • by svandav