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

Connector server installation
Adding trusted certificates
Adding connectors
(optional) Adding WinRM scripts
(optional) Configuring Kerberos support
Connector server start
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.

Configuring Kerberos support

Configuring this is optional. For Kerberos support to work, you need to install iam-app-connector-server >= 0.3.

Connector Server container comes with bindings to Kerberos utilities for Python3 and therefore it supports calling WinRM with Kerberos authentication. For the authentication to work, you have to properly configure the krb5.conf file located in /data/volumes/connector-server/config/krb5.conf.

In the file, replace all mentions of domain.tld, DOMAIN.TLD and ad.domain.tld according to your infrastructure. Preserve lowercase and uppercase letters from the template. As an example, we will use AD domain APPLIANCE.TLD with our KDC on kdc1.appliance.tld. You can use options standard to krb5.conf file on Linux, however, adjusting some options (e.g. ticket cache location) may break things.

Example configuration for krb5.conf

[logging]
    default = FILE:/var/log/krb5libs.log
    kdc = FILE:/var/log/krb5kdc.log
    admin_server = FILE:/var/log/kadmind.log

[libdefaults]
    dns_lookup_realm = false
    dns_lookup_kdc = false
    ticket_lifetime = 1h
    renew_lifetime = 1d
    forwardable = true
    rdns = false
    pkinit_anchors = FILE:/etc/pki/tls/certs/ca-bundle.crt
    spake_preauth_groups = edwards25519
    default_realm = DOMAIN.TLD      # change DOMAIN.TLD to APPLIANCE.TLD

[realms]
 DOMAIN.TLD = {                     # change DOMAIN.TLD to APPLIANCE.TLD
     kdc = ad.domain.tld:88         # change ad.domain.tld to kdc1.appliance.tld ; add other KDCs as needed
 }

[domain_realm]
 .domain.tld = DOMAIN.TLD           # change .domain.tld to .appliance.tld , change DOMAIN.TLD to APPLIANCE.TLD
 domain.tld = DOMAIN.TLD            # change domain.tld to appliance.tld , change DOMAIN.TLD to APPLIANCE.TLD

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.