Connectors via Docker

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

  • Deployed
  • Started
  • Registered

These three steps are a prerequisite to using all 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. 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 included in this release
  • 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.
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.
    • 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 re-start the containers. This will start the newly activated connectors as well.
sudo ./startup.sh

You will notice in the docker stack deploy command, we are passing it 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 below.
  • Volumes
  • Network
  • Restart policy
  • Health check interval

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

Registering a 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.

Connector registration

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.

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 -- 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 a 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 for the docker hub repository
    • Deploy 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