As indicated in other sections, before you can use a connector you must ensure that it has been:

• deployed;
• started;
• registered.

These three prerequisite steps must be performed before attempting to use any of the connectors. This section describes how you can perform these steps in a Docker environment.

Deploying a connector

In a Docker deployment the activation of the connector is controlled by the setup.sh file found in the /usr/local/openiam/openiam-docker-compose directory. The setup.sh file contains a series of pull commands for each of the connectors. Except for the LDAP connector, all connectors have been commented out to reduce the number of resources which are consumed.

#connectors
docker pull "openiamdocker/ldap-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/google-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/linux-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/oracle-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/scim-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/aws-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/script-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/oracle-ebs-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/freshdesk-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/oracle-idcs-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/tableau-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/adp-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/ipa-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/salesforce-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/jdbc-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/box-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/kronos-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/workday-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/boomi-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/lastpass-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/thales-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/thales-wsdl-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/postgresql-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"
#docker pull "openiamdocker/rexx-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"

To deploy a connector, follow the steps below:

• Open the setup.sh script using an editor like nano.
• Scroll to the section noted by #connectors. Here you will see the list of out-of-the-box connectors, as shown above.
• Uncomment the connector(s) that you need.
  • For example, to enable the GSuite connector, uncomment the line shown below.

docker pull "openiamdocker/google-connector-rabbitmq${EDITION}:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"

• Save the updated setup.sh script.
• Run the setup.sh script. This will download the new connectors from the docker repository (hub.docker.com by default).

sudo ./setup.sh

Starting the connector

Once the connector(s) have been downloaded, the next step is to update the start-up process to include the new connector. Follow the steps below:

• Edit the startup.sh script so that the new connector container starts along with the others. You will notice that the LDAP connector is included in this process by default.
  • Scroll to the part of the file which contains # deploy the ldap connector
  • Uncomment the line pertaining to your connector as shown below.

docker stack deploy --compose-file connectors/google/docker-compose.yaml --with-registry-auth google-connector

• Save your changes

• Stop the containers

sudo ./shutdown.sh

• Wait for the containers to fully stop and then restart the containers. This will start the newly activated connectors as well.

sudo ./startup.sh

You will notice that in the docker stack deploy command, we are passing the docker-compose file related to the connector. The connector yaml files can be found in the /usr/local/openiam/openiam-docker-compose/3.2/connectors/[connector name] directory. The yaml files define a number of parameters to determine how the connector container will operate. These parameters include:

• Environment variables such as the heap space and log level. The environment variable can be expanded to include custom message queue names as well. This is described in the section below titled “Options”.
• Volumes.
• Network.
• Restart policy.
• Health check interval.

After seeing that the connector container has been successfully started, the next step is to register the connector with OpenIAM as described below.

Important disclaimer

OpenIAM provides out-of-the-box set of connectors. These connectors use a default queue, we highly recommend using out-of-the-box connector configurations to avoid misconfiguration and creating unnecessary complications.

Registering the connector

After a connector has been started, it must be registered with OpenIAM so that it can receive messages that are being sent by the other services in OpenIAM. These messages will tell the connector what to do. Examples of messages include:

• find a user;
• create a user;
• reset a password.

To register a connector, go to: Webconsole -> Provisioning -> Connectors

You will see a list of connectors that have already been registered out-of-the-box. Unless you are working with a custom connector, your connector should already be registered and on this list. To configure, click on the actions button next to the connector and you will see the screen below.

Make note of the value in the Connector Queue. The out-of-the-box connectors already have predefined queue names. If it's a custom connector, then you will need to provide this value. If you change this value, then you must update the connector yaml file as described below.

Deploying remote connectors

Remote connectors are connectors that are deployed outside of the OpenIAM environment. For example: if OpenIAM is deployed in Docker, but the connector started as a Java application, even on the same VM, it's considered to be a remote connector.

All Microsoft applications and SAP connectors are remote connectors.

To allow remote connectors to connect to RabbitMQ, we should ensure that access to port 5672 is enabled. Follow the steps below to enable communication over this port:

• Edit file 3.2/infrastructure/rabbitmq/docker-compose.yaml and uncomment the ports section and run startup.sh command to apply changes.
• Ensure that firewalls or other network configurations do not block this port. Before starting the connector you can test the connection by running the following telnet command:

telnet [RabbitMQ host] 5672

where RabbitMQ host is the IP address of the host where RabbitMQ is installed.

Options

The following sections provide details about configuration and deployment options.

Adding the queue name to the connector configuration

If you want to create a custom connector queue, then you need to do the following:

• Determine the queue name - let's assume that it will be LDAP_Connector_2
• Update the yaml file for the respective connector at: /usr/local/openiam/openiam-docker-compose/3.2/connectors/[connector name]
  • Update the OPENIAM_JAVA_OPT_ARGS with the connector queue information. Note there is a Request and Response queue. You must add request and response as suffixes as shown below.

    environment:
      OPENIAM_JAVA_HEAP_SIZE: 128M
      VAULT_KEYPASS: "${VAULT_JKS_PASSWORD}"
      OPENIAM_LOG_LEVEL: "${OPENIAM_BASH_LOG_LEVEL}"
      OPENIAM_JAVA_OPT_ARGS: "-Dlogging.level.root=${LOGGING_LEVEL} -Dorg.openiam.connector.queue=LDAP_Connector_2_Request -Dorg.openiam.connector.queueResponseName=LDAP_Connector_2_Response"

• Save the yaml file and restart the connector.
• Update the connector registration using the Webconsole as described above.
  • You will need to enter the queue name that you came up with in the first example.

Deploying a connector without restarting the application

In production settings, it may be necessary to expand the solution by adding a new connector. In these cases, it is not necessary to incur an outage. The section below describes how you add a new connector to a running OpenIAM deployment.

• First determine which connector needs to be deployed (in the example below we will use the Google connector).
• Create a shell script as shown below. Note the following parts of the script:
  • removing an existing connector;
  • pulling the connector from the Docker hub repository;
  • deploying the new connector.

#!/usr/bin/env bash
docker stack rm google-connector

sleep 5
set -x
set -e

. env.sh

if [ -f /opt/openiam/webapps/env.sh ]
then
  . /opt/openiam/webapps/env.sh
fi


docker pull "openiamdocker/google-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}"

cd 3.2

docker stack deploy --compose-file connectors/google/docker-compose.yaml --with-registry-auth google-connector

• Run the new script.

Connector is deployed.