Differences

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

--- devel:documentation:adm:systems:connectors:remote_server [2019/02/26 09:35]
kotisovam created part moved from devel section - and edited
+++ devel:documentation:adm:systems:connectors:remote_server [2023/11/07 14:55] (current)
urbanl [Remote connector server configuration - Linux] Úprava verze Javy pro connector server
@@ Line 1: / Line 1: @@
 ====== Remote connector server ======
 {{tag> system connector configuration }}
-===== Why use a remote connector server? =====
+Remote connector server is a standalone daemon used for interfacing some of the more difficult systems. You deploy connector bundles into the connector server. Then, you configure CzechIdM to use connectors from within the remote connector server. As far as IdM is concerned, there is no difference if actions on end system are performed by connector server or IdM itself. The only difference is in the point of origin of network communication.
-System CzechIdM has available only certain types of connectors. If we want to use other connectors, such as **Active Directory** or **Google Apps**, we need to use a remote connector server allowing for other connectors.
+===== Why use remote connector server? =====
+CzechIdM comes bundled only with certain types of connectors. For some deployments, it is necessary to use **Remote connector server** ("connector server" from now on). There are generally four reasons for this:
+   * We cannot run Java code on the target system (e. g. .NET code is needed).
+  * The OS does not have some normal API (e. g. old Windows without WinRM) so we need to run commands on it locally.
+  * Security reasons - we do not want to run the connector code under the same user as the CzechIdM.
+  * You need to use two different versions of one connector (or two connectors which bundle different versions of the same library - for example Apache CXF). If you did deploy them both into one Java context, libraries would break due to Java Class FQDN conflicts.
+===== How does a remote connector server work in CzechIdM? =====
+The remote server connector configuration form behaves just like the local connector form - this means that definition is stored in the EAV attributes for system which it belongs to. System name, connector name and connector version are the key to EAV attributes in the CzechIdM. It is therefore possible to have multiple connectors with different versions in one remote connector server.
+===== Connector server setup =====
+==== Obtaining connector server ====
+  * Simply download the all-in-one prepared bundle from [[https://github.com/bcvsolutions/connector-server|there]].
+<note> If you need to do some other things or if you have a do-it-yourself attitude, you can base the setup on original ConnId Connector Server.
+  - Download connector server from the [[https://connid.atlassian.net/wiki/spaces/BASE/pages/360458/Downloads#Downloads-JavaConnectorServer|ConnId project]].
+  - **Use version 1.4.5.1**  of remote connector server and version **1.4.3.0**  of connector framework.
+  - Download following libraries and add them to the ''lib''  directory of the connector server:
+      * jackson-annotations-2.9.8
+      * jackson-core-2.9.8
+      * jackson-databind-2.9.8
+  - Add those libraries to the ''classpath''  inside ''ConnectorServer.sh''  script (for Linux) or ''ConnectorServer.bat''  script (for Windows).
+</note>
+==== Remote connector server configuration - Linux ====
+  - Install Java 11 (OpenJDK headless is preferred).
+  - Create new OS user the connector server will run under. By default, we create user ''connector-server''  with home under ''/opt''.
+<code>
+useradd -b /opt -m -s /bin/bash connector-server
+chmod 750 /opt/connector-server/
+</code>
+  - Copy over the connector server and unpack it.
+<code>
+cp connector-server-master.tar.gz /opt/connector-server/
+chown connector-server:connector-server /opt/connector-server/connector-server-master.tar.gz
+su - connector-server
+cd /opt/connector-server
+tar xzf connector-server-master.tar.gz
+rm connector-server-master.tar.gz
+</code>
+  - Correct directory permissions:
+<code>
+cd /opt/connector-server/connid-connector-server
+chmod 750 bin/ bundles/ certs/ conf/ lib/ logs/ scripts/
+</code>
+  - Your setup should look like this:
+<code>
+ls -l /opt/connector-server/
+total 4
+drwxrwxr-x 9 connector-server connector-server 4096 Oct 10 16:45 connid-connector-server
+ls -l /opt/connector-server/connid-connector-server/
+total 23448
+drwxr-x--- 5 connector-server connector-server     4096 Mar 10 10:09 bin
+drwxr-x--- 2 connector-server connector-server     4096 Oct 18 09:08 bundles
+drwxr-x--- 2 connector-server connector-server     4096 Mar 10 10:14 certs
+drwxr-x--- 2 connector-server connector-server     4096 Mar 10 10:04 conf
+-rw-rw-r-- 1 connector-server connector-server 11976830 Oct 10 16:45 datetime
+drwxr-x--- 3 connector-server connector-server     4096 Oct 10 16:45 lib
+-rw-rw-r-- 1 connector-server connector-server    19982 Oct 10 16:45 LICENSE
+drwxr-x--- 2 connector-server connector-server     4096 Mar 10 11:02 logs
+drwxr-x--- 3 connector-server connector-server     4096 Mar 10 09:50 scripts
+-rw-rw-r-- 1 connector-server connector-server 11976825 Oct 10 16:45 sys
+</code>
+  - Set executable permission on the main script.
+<code>
+cd connid-connector-server
+chmod +x bin/ConnectorServer.sh
+</code>
+  - Create strong password for the connector server (use ''pwgen -1 16''  or something similar).
+<code>
+./bin/ConnectorServer.sh -setKey -key PASSWORD_HERE -properties conf/connectorserver.properties
+</code>
+  - If you plan to connect to remote connector server remotely (not locally on ''localhost''), edit the ''conf/connectorserver.properties''  and set/comment out the ''connectorserver.ifaddress''.
+  - As root, create systemd unit ''/etc/systemd/system/connector-server.service'':
+<file txt connector-server.service>
+[Unit]
+Description=Java Connector Server Service
+After=network-online.target
+[Service]
+User=connector-server
+WorkingDirectory=/opt/connector-server/connid-connector-server
+ExecStart=/bin/bash /opt/connector-server/connid-connector-server/bin/ConnectorServer.sh -run -properties /opt/connector-server/connid-connector-server/conf/connectorserver.properties
+SuccessExitStatus=143
+[Install]
+WantedBy=multi-user.target
+</file>
+  - Reload systemd, start and enable the connector server.
+<code>
+systemctl daemon-reload
+systemctl start connector-server
+systemctl enable connector-server
+</code>
+  - For additional configuration, see ''conf/connectorserver.properties''  and ''conf/logging.properties''  files.
+  - Connector server is now configured. You can deploy connector bundles into it. You have to restart the connector server for changes to take effect.
+      - Add connector bundles (''.jar''s) into the ''bundles''  directory.
+      - Add custom scripts the CzechIdM will use under the ''scripts''  directory.
+      - Add certificates to be used under ''cert''  directory. CzechIdM scripts by default look there.
+=== Configuring log rotation ===
+The principle of rotating logs on Linux is the same as for the CzechIdM. Just create a proper logrotate file ''/etc/logrotate.d/connector-server'':
+<code>
+/opt/connector-server/connid-connector-server/logs/connectorserver*.log {
+    rotate 90
+    daily
+    dateext
+    copytruncate
+    missingok
+    notifempty
+    compress
+}
+</code>
+=== Configuring SSL truststore ===
+When you interface end systems remotely, you **have to**  secure the communication with TLS. For this to work, you need a Java truststore. This short howto will show you how to create one.
+  - Get (or create - as we do there) a certificate of the end system.
+<code>
+su - connector-server
+cd /opt/connector-server/connid-connector-server/conf
+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=Connector placeholder cert"
+openssl x509 -req -in fakecert.csr -signkey fakecert.key -days 1 -sha256 -out fakecert.crt
+</code>
+  - Import the certificate into the truststore. If the ''truststore.jks''  does not exist, the ''keytool''  will create it.
+<code>
+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
+</code>
+  - Just some cleanup.
+<code>
+rm fakecert.key fakecert.csr fakecert.crt
+chmod 644 truststore.jks
+# the connector server user should not be able to write the truststore, only read it
+chown root:connector-server truststore.jks
+</code>
+  - Add truststore to startup script ''ConnectorServer.sh'':
+<code>
+cd /opt/connector-server/connid-connector-server
+vim bin/ConnectorServer.sh
+# add this snippet to the command line that executes the connector server
+-Djavax.net.ssl.trustStore=/opt/connector-server/connid-connector-server/conf/truststore.jks -Djavax.net.ssl.trustStorePassword=PUT_KEYSTORE_PASSWORD_HERE
+</code>
+  - Restart the connector server.
+==== Remote connector server configuration - Windows ====
+) Install Java 1.8 (OpenJDK headless is preferred).
+<note important> Use version 1.8 and not later versions!</note>
+) Unpack connector server to his root directory "C:\connid-connector-server".
+) Create trustore for connector server. Use git bash in direcotory "C:\connid-connector-server\conf".
+  * Get (or create - as we do there) a certificate of the end system.
+<code>
+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=Connector placeholder cert"
+openssl x509 -req -in fakecert.csr -signkey fakecert.key -days 1 -sha256 -out fakecert.crt
+</code>
+  * Import the certificate into the truststore. If the truststore.jks does not exist, the keytool will create it.
+<code>
+/c/Program\ Files/Java/jdk-1.9.8/bin/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
+</code>
+  * Just some cleanup.
+<code>
+rm fakecert.key fakecert.csr fakecert.crt
+</code>
+) Add trustore location and password to service installation in „bin\ConnectorServer.bat“(windows). These parameters are in script already, so just trustore path and password.
+<code>
+"-Djavax.net.ssl.trustStore=C:\connid-connector-server\conf\truststore.jks";"-Djavax.net.ssl.trustStorePassword=TODO_PASSWORD"
+</code>
+) Start CMD under system admin. Then go to connector-server root directory.
+<code>
+cd C:\connid-connector-server
+bin\ConnectorServer.bat /setkey
+</code>
+<note important> Run the setkey command from the path C:\connid-connector-server </note>
+) Add connectors to "C:\connid-connector-server\bundles" and scripts to "C:\connid-connector-server\scripts".
+) Then setup connector-server key and install windows service(connector_server).
+<code>
+bin\ConnectorServer.bat /install connector_server
+</code>
+) Then start service in "services.msc". If connector_server service started correctly set this service to automatic start.
+===== Remote connector server agenda =====
+@since 10.8.0
+Standalone connector server agenda is available from main menu ''System''  → ''Connector servers'':
+  * Remote connector servers can be configured here, configuration is effective for all related systems,
+  * connectors installed on the same server together with CzechIdM are shown,
+  * systems related to remote connector server or to concrete connector can be found on server or connector detail.
+{{  .:remote-connector-servers.png  }}
+===== Connecting CzechIdM to a remote connector server =====
+  - In CzechIdM, go to ''Systems''  → ''Connector servers''  from menu and add new remote connector server.
+  - In the detail of this remote connector server fill in every form field that IdM needs to connect to the remote system. It is necessary to supply the host and port on which the connector is available on remote server. If the server is secured by password, you will need to fill in the password in order to successfully connect to the remote connector server. Password will be stored in local confidential storage.
+  - When you are done, ''save''  the form.
+  - In CzechIdM, on the system tab, create a new system.
+  - In the detail of this system, select previously added remote connector server in ''Use remote connector server''  field.
+  - When you are done, ''save''  the form.
+  - Go to the ''Configurations''  tab. There, only connectors that are deployed inside remote connector server, will be available.
+  - Configure everything else as you would do if you were not using remote connector server.
+<note tip>If you change the key (password) of the remote connector server, you must change the key also in the remote connector server configuration in IdM. You may need to restart IdM (i.e. the application server Tomcat) to force the IdM to start using the new key. Otherwise, you would get this exception when testing the connection:
-===== How to set up a remote connector server? =====
+<code>
-On the system tab, you create a new system. In the detail of this system, check the option **"Use remote connector server"**, filling in all form fields that the new system requires in order to connect to the remote system. To be able to connect, it is necessary to fill the host and port on which the connector is available on the remote server. If a server is secured by a password you need to fill in the password for connecting to the remote connector server. Password for connection is stored in the local confidential storage.
+org.identityconnectors.framework.common.exceptions.InvalidCredentialException: Remote framework key is invalid
-{{ .:remote-001.png?300 |}}
+</code>
-After saving all the necessary information to the remote connector of the server, you go to the **"Configurations"** tab. From now on, only connectors on the remote connector server will be available.
+</note>
-The functionality of the remote connector server can be verified, just like the functionality of a local connector, using the **"Test connector"** button.
-{{ .:remote-002.png?300 |}}
-===== How does a remote connector server works in CzechIdM? =====
-The remote server connector configuration form behaves just like a local connector form, meaning its definition is stored in the EAV attributes for the system it belongs to. As a key to EAV attributes are used the system name, connector name, and connector version. Therefore, it is possible on the remote connector server to have multiple connectors with a different version.