Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
tutorial:adm:czechidm_installation [2017/10/04 18:45] tsunami [Set the key for JWT token encryption] |
tutorial:adm:czechidm_installation [2021/05/10 16:05] urbanl [5. Create CzechIdM configuration] Changed DB logback appender to support IdM 11 |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Installation of CzechIdM - Linux - CentOS8 ====== | ||
+ | |||
+ | {{tag> | ||
+ | |||
+ | We expect that the server is prepared as described in [[tutorial: | ||
+ | |||
+ | 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 [[: | ||
+ | |||
+ | <note tip>If you install CzechIdM on with Microsoft SQL Server database backend, please skip PostgreSQL-related sections and [[tutorial: | ||
+ | ==== 1. Create DB user and database in PostgreSQL ==== | ||
+ | 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 ' | ||
+ | |||
+ | # Choose appropriate collation and create database. | ||
+ | # with czech collation (- typical) | ||
+ | CREATE DATABASE " | ||
+ | # or with english collation | ||
+ | # CREATE DATABASE " | ||
+ | </ | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | czechidm=> | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | hostssl czechidm czechidm {IP address}/ | ||
+ | </ | ||
+ | and restart PostgreSQL. | ||
+ | </ | ||
+ | ==== 2. JDBC driver installation - CentOS8 ==== | ||
+ | **CentOS** | ||
+ | |||
+ | Download PostgreSQL JDBC driver from [[https:// | ||
+ | In this example we download version 42.2.11. | ||
+ | |||
+ | <code bash> | ||
+ | wget https:// | ||
+ | </ | ||
+ | |||
+ | ==== 3. Configure environment properties. Select application profile ==== | ||
+ | |||
+ | Edit the configuration file ''/ | ||
+ | < | ||
+ | |||
+ | |||
+ | Change the following line: | ||
+ | <code bash> | ||
+ | Environment=' | ||
+ | </ | ||
+ | into: | ||
+ | <code bash> | ||
+ | Environment=' | ||
+ | </ | ||
+ | |||
+ | Reload systemd after the changes: | ||
+ | <code bash> | ||
+ | systemctl daemon-reload | ||
+ | </ | ||
+ | ==== 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: | ||
+ | < | ||
+ | mkdir -p / | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ==== 5. Create CzechIdM configuration ==== | ||
+ | Now we will create configuration files the CzechIdM will use. | ||
+ | < | ||
+ | * The **/ | ||
+ | cat / | ||
+ | </ | ||
+ | * The **/ | ||
+ | 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_ | ||
+ | </ | ||
+ | * The **/ | ||
+ | |||
+ | <file xml logback-spring.xml> | ||
+ | <?xml version=" | ||
+ | <!-- https:// | ||
+ | <!-- http:// | ||
+ | < | ||
+ | <include resource=" | ||
+ | < | ||
+ | < | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | |||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | <logger name=" | ||
+ | < | ||
+ | </ | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | <logger name=" | ||
+ | |||
+ | </ | ||
+ | |||
+ | </ | ||
+ | </ | ||
+ | * The most important file is **/ | ||
+ | # Doc: https:// | ||
+ | |||
+ | idm.pub.app.instanceId=idm-primary | ||
+ | idm.pub.app.stage=production | ||
+ | |||
+ | spring.datasource.url=jdbc: | ||
+ | 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=/ | ||
+ | |||
+ | 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(" | ||
+ | idm.sec.core.attachment.storagePath=/ | ||
+ | # configuration property for default backup | ||
+ | idm.sec.core.backups.default.folder.path=/ | ||
+ | |||
+ | |||
+ | idm.pub.security.allowed-origins=http:// | ||
+ | # Generate JWT token security string as "cat / | ||
+ | # 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.keyPath=/ | ||
+ | |||
+ | # Defaults for: emailer.* | ||
+ | # test.enabled=true means mail WILL NOT be sent | ||
+ | idm.sec.core.emailer.test.enabled=true | ||
+ | # http:// | ||
+ | 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, | ||
+ | # 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 " | ||
+ | spring.servlet.multipart.max-file-size=100MB | ||
+ | spring.servlet.multipart.max-request-size=100MB | ||
+ | </ | ||
+ | |||
+ | === 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: | ||
+ | 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 | ||
+ | </ | ||
+ | |||
+ | === Generate JWT token === | ||
+ | Set value of the **idm.sec.security.jwt.secret.token** property as is described in the template file:< | ||
+ | # Generate JWT token security string as "cat / | ||
+ | # We recommend the VALUE to be at least 25. | ||
+ | idm.sec.security.jwt.secret.token=********** TODO ********* | ||
+ | </ | ||
+ | |||
+ | === Local confidential storage === | ||
+ | |||
+ | Local confidential storage is encrypted by AES algoritm. [[https:// | ||
+ | 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 '' | ||
+ | |||
+ | <note warning> | ||
+ | |||
+ | Confidential storage uses AES/ | ||
+ | < | ||
+ | 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, | ||
+ | |||
+ | </ | ||
+ | |||
+ | === 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 / | ||
+ | |||
+ | <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(" | ||
+ | idm.sec.core.attachment.storagePath=/ | ||
+ | </ | ||
+ | |||
+ | === Environment === | ||
+ | |||
+ | If you install CzechIdM in multiple environments (typically test and production), | ||
+ | <code properties> | ||
+ | # Application stage (development, | ||
+ | idm.pub.app.stage=production | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ==== 6. Set correct permissions on CzechIdM files ==== | ||
+ | < | ||
+ | chown tomcat: | ||
+ | chown -R tomcat: | ||
+ | chmod 750 / | ||
+ | chmod 640 / | ||
+ | </ | ||
+ | |||
+ | ==== 7. Adjust Tomcat' | ||
+ | Apache Tomcat has to know where the new configuration is. Because CzechIdM uses SpringBoot project, we simply add the ''/ | ||
+ | |||
+ | Create new file ''/ | ||
+ | |||
+ | <code bash:> | ||
+ | CLASSPATH=/ | ||
+ | </ | ||
+ | |||
+ | And change owner of the file to tomcat: | ||
+ | < | ||
+ | chown root:tomcat / | ||
+ | </ | ||
+ | |||
+ | ==== 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. | ||
+ | < | ||
+ | cd / | ||
+ | openssl genrsa -out fakecert.key | ||
+ | openssl req -new -key fakecert.key -out fakecert.csr -subj "/ | ||
+ | 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: | ||
+ | Re-enter new password: | ||
+ | ... | ||
+ | Trust this certificate? | ||
+ | Certificate was added to keystore | ||
+ | |||
+ | rm fakecert.key fakecert.csr fakecert.crt | ||
+ | chmod 644 truststore.jks | ||
+ | chown root:root truststore.jks | ||
+ | </ | ||
+ | |||
+ | Edit the Tomcat service file ''/ | ||
+ | < | ||
+ | systemctl daemon-reload | ||
+ | systemctl restart tomcat.service | ||
+ | </ | ||
+ | ==== 9. Deploy the CzechIdM ==== | ||
+ | Download the latest CzechIdM version. Currently it is idm-app-10.4.1.war. | ||
+ | |||
+ | Ensure Tomcat is stopped: | ||
+ | < | ||
+ | systemctl stop tomcat.service | ||
+ | </ | ||
+ | Copy the identity manager WAR into webapps folder in Tomcat and name it '' | ||
+ | < | ||
+ | cp idm-app-10.4.1.war / | ||
+ | </ | ||
+ | Check that the idm.war file is owned by Tomcat: | ||
+ | < | ||
+ | ls -l / | ||
+ | </ | ||
+ | If not, change its owner: | ||
+ | < | ||
+ | chown tomcat: | ||
+ | </ | ||
+ | Start the Tomcat container:< | ||
+ | systemctl start tomcat.service | ||
+ | </ | ||
+ | If everything is set up right, the CzechIdM will deploy. Default log is ''/ | ||
+ | |||
+ | |||
+ | ==== 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/ | ||
+ | firewall-cmd --permanent --add-port=443/ | ||
+ | firewall-cmd --reload | ||
+ | </ | ||
+ | |||
+ | === Change default admin password === | ||
+ | In the fresh CzechIdM installation, | ||
+ | |||
+ | === Configure IdM === | ||
+ | |||
+ | Follow some final configuration steps: [[tutorial: | ||