Connector server setup

Connector server is an optional part of the IAM appliance and it is not necessary for its standard functioning. Its use is necessary in the case of more complicated environments where the identity manager manages systems such as Microsoft Exchange or other systems managed via an .exe application.

Steps to set up the connector server

  1. Connector server installation

  2. Adding trusted certificates

  3. Adding connectors

  4. (optional) Adding WinRM scripts

  5. Connector server start

  6. Integration with CzechIdM

Connector server installation

It is advised to have IAM appliance version 0.5 or above before installing the connector server. You can install the connector server using command dnf install iam-app-connector-server.

During installation, the service generates a password which is saved in the /data/volumes/connector-server/secrets/cserver.pwfile file. This password is set internally in the service during its start and it needs to be configured in the CzechIdM as the next step of this tutorial.

Adding trusted certificates

Connector server is a Java application integrated with the Python library pywinrm. For TLS-secured communication, you need to configure certificates which the service should trust.

Trusted certificates for Java

Certificates are loaded from the directory /data/volumes-shared/cacerts. Each trusted certificate must be created in a separate file in PEM format. File names cannot contain spaces, diacritics or special characters.

Trusted certificates for Python

If you are not using the winrm-ad connector or you are not calling WinRM script, you can skip this part.

When using WinRM, a certificate CA in PEM format must be placed in the file /data/volumes/connector-server/winrm-cacert/winrm_ca.pem. You must not use a certificate of a server with which the the communication occurs directly but only a CA certificate. Comments (lines starting with #) must be removed from the file. If you use multiple certificate authorities, place all their certificates in PEM format (including header -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) into the file.

Adding connectors

Connectors are Java .jar packages. Connectors which are needed should be placed in a directory /data/volumes/connector-server/bundles. The connector server will load them during its startup.

Adding WinRM scripts

If you are not using the winrm-ad connector or are not calling WinRM script, you can skip this part.

WinRM scripts are a combination of scripts written in Python and PowerShell and they usually exists in an entire directory structure which has to be followed. This directory structure should be placed in /data/volumes/connector-server/winrm-scripts. The connector server will change the ownership and permission of these files as needed during its startup.

If the connector server is already running, changes in WinRM scripts will occur immediately.

Connector server start

Connector server is controlled in the same way as other services in the IAM appliance using the command systemctl start/stop/restart iam-connector-server.service.

Automatic connector server startup can be enabled by using the command systemctl enable iam-connector-server.service.

Integration with CzechIdM

Because the connector server is an optional part of the IAM appliance it needs to be configured manually in the identity manager CzechIdM. Follow the official tutorial for the identity manager.

As a location where the connector server service runs, you can use:

Table 1. Information for the connector server configuration
Parameter Value

Hostname

connector-server

Port

8759

Use SSL

no

Password

contained in the /data/volumes/connector-server/secrets/cserver.pwfile file on the appliance filesystem

Connector server sizing

By default, the connector server is permitted to use 512 MB RAM at most. This is sufficient for basic use (e. g., managing MS Exchange accounts). However, if the connector server should process more complex operations (e. g., regular synchronization of MS Active Directory) it will require more memory. We recommend you start with 1024 MB RAM but in cases like daily synchronization of a large number of objects (10,000 groups or users), you may need to give it 2048 MB RAM or more.

If you want to add memory for the connector server, using the tools nano or vim change the configuration file of the connector server located in /data/registry/node-active-config/docker-compose-connector-server.yml.

Find the variable:

- JAVA_XMX=512M

Change the value 512M to the required size of available memory, e. g., 1024M:

- JAVA_XMX=1024M

After the change, restart the connector server using the command systemctl restart iam-connector-server.service.