====== Installation of CzechIdM - Linux - CentOS8 ======

{{tag>installation jdbc quickstart encryption}}

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

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

<code bash>
su - postgres
psql 
CREATE USER czechidm PASSWORD 'XXXXXXXXXXXX';

# Choose appropriate collation and create database.
# with czech collation (- typical)
CREATE DATABASE "czechidm" WITH OWNER 'czechidm' ENCODING 'UTF8' LC_COLLATE = 'cs_CZ.UTF-8' LC_CTYPE = 'cs_CZ.UTF-8' template 'template0';
# or with english collation
# CREATE DATABASE "czechidm" WITH OWNER 'czechidm' ENCODING 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' template 'template0';
</code>

Try the access to new database with new user:

<code bash>
[root@tomcat1 data]# psql -h localhost -U czechidm
Password for czechidm user: 
psql (9.6.1)
For more information type "help".

czechidm=> 
</code>

<note>If yout have the database installed on a different server than the application itself (Tomcat etc.), don't forget to configure PostgreSQL to allow remote SSL connection from that server and add this line to /data/pgsql/9.6/pg_hba.conf replacing {IP address} and {Mask} with the IP and mask of the CzechIdM application server:
<code>
hostssl	czechidm	czechidm	{IP address}/{Mask}	md5
</code>
and restart PostgreSQL.
</note>
==== 2. JDBC driver installation ​- CentOS8 ​==== 
**CentOS**

Download PostgreSQL JDBC driver from [[https://jdbc.postgresql.org/download.html|official page]].
In this example we download version 42.2.11.

<code bash>
wget https://jdbc.postgresql.org/download/postgresql-42.2.11.jar -P /opt/tomcat/current/lib/
</code>

==== 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. <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:

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

</code>

into:

<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 -Dlog4j2.formatMsgNoLookups=true -Dspring.profiles.active=production'

</code>

Reload ​systemd after the changes:

<code bash>
systemctl daemon-reload

</code>


==== 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.
  * The **etc** directory stores configuration files.
  * The **lib** directory stores additional jar libraries such as database drivers.
  * The **backup** directory stored Groovy scripts backups.
  * The **data** directory stores various user-attached files.
  * 
Create the directory structure:
<code>
mkdir -p /opt/czechidm/{etc,lib,backup,data}
</code>



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

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

  * 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.instanceId=AUTO
org.quartz.scheduler.skipUpdateCheck=true
org.quartz.threadPool.class=org.quartz.simpl.SimpleThreadPool
org.quartz.threadPool.threadCount=10
org.quartz.threadPool.threadPriority=4
org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
org.quartz.jobStore.useProperties=false
org.quartz.jobStore.misfireThreshold=60000
org.quartz.jobStore.tablePrefix=qrtz_


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

<file xml logback-spring.xml>
<?xml version="1.0" encoding="UTF-8"?>
<!-- https://springframework.guru/using-logback-spring-boot/ -->
<!-- http://logback.qos.ch/manual/appenders.html -->
<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"/>
    <springProperty name="spring.profiles.active" source="spring.profiles.active"/>
    <springProfile name="default">
        <logger name="eu.bcvsolutions" level="INFO"/>
        <logger name="org.springframework" level="INFO"/>
        <logger name="org.springframework.web" level="INFO"/>
        <logger name="org.hibernate.SQL" level="INFO"/>
        <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="INFO"/>
        <logger name="AUDIT" level="INFO"/>
    </springProfile>

    <springProfile name="production">
        <springProperty name="spring.datasource.driver-class-name" source="spring.datasource.driver-class-name"/>
        <springProperty name="spring.datasource.url" source="spring.datasource.url"/>
        <springProperty name="spring.datasource.username" source="spring.datasource.username"/>
        <springProperty name="spring.datasource.password" source="spring.datasource.password"/>

        <appender name="DB" class="eu.bcvsolutions.idm.core.exception.IdmDbAppender">

        </appender>

        <appender name="DB_ASYNC" class="ch.qos.logback.classic.AsyncAppender">
            <appender-ref ref="DB" />
            <includeCallerData>true</includeCallerData>
        </appender>

        <logger name="eu.bcvsolutions" level="INFO">
            <appender-ref ref="DB_ASYNC" />
        </logger>
        <logger name="org.springframework" level="INFO"/>
        <logger name="org.springframework.web" level="INFO"/>
        <logger name="org.hibernate.SQL" level="INFO"/>
        <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="INFO"/>
        <logger name="AUDIT" level="INFO"/>

    </springProfile>

</configuration>


</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>
# Doc: https://wiki.czechidm.com/devel/dev/configuration/backend

idm.pub.app.instanceId=idm-primary
idm.pub.app.stage=production

spring.datasource.jdbcUrl=jdbc:postgresql://localhost:5432/czechidm
spring.datasource.username=czechidm
spring.datasource.password=********** TODO *********
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.validationQuery=SELECT 1
spring.datasource.test-on-borrow=true
spring.jpa.generate-ddl=false
spring.jpa.hibernate.ddl-auto=none
flyway.enabled=true

scheduler.properties.location=quartz-production.properties

logging.config=/opt/czechidm/etc/logback-spring.xml

idm.sec.core.demo.data.enabled=false

# attachments will be stored under this path.
# new directories for attachment will be created in this folder (permissions has to be added)
# System.getProperty("user.home")/idm_data will be used if no path is given
idm.sec.core.attachment.storagePath=/opt/czechidm/data
# configuration property for default backup
idm.sec.core.backups.default.folder.path=/opt/czechidm/backup

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.
# We recommend the VALUE to be at least 25.
idm.sec.security.jwt.secret.token=********** TODO *********
idm.sec.security.jwt.expirationTimeout=36000000

# Cipher secret key for crypt values in confidential storage
# for crypt values is used secretKey or secretKey defined by file - secretKeyPath
#cipher.crypt.secret.key=XXXXXXXXXXXXXXXX
cipher.crypt.secret.keyPath=/opt/czechidm/etc/secret.key

# Defaults for: emailer.*
# test.enabled=true means mail WILL NOT be sent
idm.sec.core.emailer.test.enabled=true
# http://camel.apache.org/mail.html
idm.sec.core.emailer.protocol=smtp
idm.sec.core.emailer.host=something.tld
idm.sec.core.emailer.port=25
# idm.sec.core.emailer.username=czechidm@domain.tld
# idm.sec.core.emailer.password=password
idm.sec.core.emailer.from=czechidm@localhost

# 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

# Max file size of uploaded file. Values can use the suffixed "MB" or "KB" to indicate a Megabyte or Kilobyte size.
spring.servlet.multipart.max-file-size=100MB
spring.servlet.multipart.max-request-size=100MB


</file>

=== 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>
spring.datasource.url=jdbc:postgresql://localhost:5432/czechidm
spring.datasource.username=czechidm
spring.datasource.password=********** TODO *********
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.validationQuery=SELECT 1
spring.datasource.test-on-borrow=true


</code>

=== Generate JWT token ===

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.
# We recommend the VALUE to be at least 25.
idm.sec.security.jwt.secret.token=********** TODO *********


</code>

=== 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]]. 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:

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

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.

  * OpenJDK/JDK 1.8u161 and all higher versions support AES-256 by default.
  * Older versions (below 1.8u161) do not offer it. On those Java distributions, you can use AES-128 or obtain the [[https://www.oracle.com/java/technologies/javase-jce8-downloads.html|Unlimited Strength Jurisdiction Policy Files]] to enable AES-256.

</note>

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

<code properties>
# attachments will be stored under this path.
# new directories for attachment will be created in this folder (permissions has to be added)
# System.getProperty("user.home")/idm_data will be used if no path is given
idm.sec.core.attachment.storagePath=/opt/czechidm/data


</code>

=== 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>
# Application stage (development, test, production (default))
idm.pub.app.stage=production


</code>


==== 6. Set correct permissions on CzechIdM files ====
<code>
chown tomcat:tomcat /opt/czechidm
chown -R tomcat:tomcat /opt/czechidm/{etc,data,backup,lib}
chmod 750 /opt/czechidm/{etc,data,backup,lib}
chmod 640 /opt/czechidm/etc/*
</code>

==== 7. Adjust Tomcat's classpath ====
Apache Tomcat has to know where the new configuration is. Because CzechIdM uses SpringBoot project, we simply add the ''/opt/czechidm/etc'' directory (and others) on the classpath.

Create new file ''/opt/tomcat/current/bin/setenv.sh'' with following ​content:

<code bash:>
CLASSPATH=/opt/czechidm/etc:/opt/czechidm/lib/*
</code>

And change owner of the file to tomcat:
<code>
chown root:tomcat /opt/tomcat/current/bin/setenv.sh
</code>

==== 8. Create dedicated Java truststore ====
Java truststore is a file which contains SSL certificates which we consider trusted. Usually this means some certificates of end systems or their respective certificate authorities.
When we need CzechIdM to communicate with some new system with SSL-encrypted way, we need to import particular certificate here and restart the Tomcat container.

At this point, we do not have any certificate to put into the truststore so we create a fake one with only one-day validity.
<code>
cd /opt/czechidm/etc
openssl genrsa -out fakecert.key
openssl req -new -key fakecert.key -out fakecert.csr -subj "/C=CZ/ST=Czech Republic/L=Prague/O=BCV/CN=CzechIdM placeholder cert"
openssl x509 -req -in fakecert.csr -signkey fakecert.key -days 1 -sha256 -out fakecert.crt
keytool -importcert -file fakecert.crt -alias placeholder-cert -keystore truststore.jks
    Enter keystore password:  ENTER SOME PASSWORD HERE AND REMEMBER IT FOR LATER
    Re-enter new password:
    ...
    Trust this certificate? [no]:  yes
    Certificate was added to keystore

rm fakecert.key fakecert.csr fakecert.crt
chmod 644 truststore.jks
chown root:root truststore.jks
</code>

Edit the Tomcat service file ''/etc/systemd/system/tomcat.service'' and add path to the truststore ''-Djavax.net.ssl.trustStore=/opt/czechidm/etc/truststore.jks'' and truststore password ''-Djavax.net.ssl.trustStorePassword=THE PASSWORD YOU ENTERED WHEN CREATING KEYSTORE'' to the Java options. Finally, reload the systemd and restart Tomcat.
<code>
systemctl daemon-reload
systemctl restart tomcat.service
</code>
==== 9. Deploy the CzechIdM ====

Download the latest CzechIdM version. Currently it is idm-app-12.2.3.war.

Ensure Tomcat is stopped:

<code>
systemctl stop tomcat.service

</code>

Copy the identity manager WAR into webapps folder in Tomcat and name it ''idm.war'':
<code>
cp idm-app-10.4.1.war /opt/tomcat/current/webapps/idm.war

</code>

Start the Tomcat container:

<code>
systemctl start tomcat.service

</code>

If everything is set up right, the CzechIdM will deploy. Default log is ''/opt/tomcat/​current/logs/​catalina.out''.


==== 10. Final Steps ==== 

=== Allow network services ===
Firewall may restrict the access to all port except ssh (22/tcp). To be able to use CzechIdM, allow port 443/tcp and reload firewalld:

<code bash>
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --reload
</code>

=== Change default admin password ===
In the fresh CzechIdM installation, there is one user identity - **admin** with password **admin**. Right after you install the application, go to https://yourserver.tld/idm and change the default password.

=== Configure IdM ===

Follow some final configuration steps: [[tutorial:adm:czechidm_installation_finalize|]].