Installing IAM Version 2.3

Setting Up IAM

To set up IAM, follow these steps:

1. Ensure that your system has the required prerequisites:

   1. Install Docker if your system does not already have it. You must have the Docker engine version 17.04 or later. See Running InterSystems Products in ContainersOpens in a new tab for a brief introduction to containers and Docker.

   2. Install the docker-compose command line interface version 1.12.0 or later if your system does not already have it.

   3. Install the curl utility on the UNIX® system. The script files that start and test IAM use curl.

   4. Ensure that you have a running instance of InterSystems IRIS, InterSystems IRIS for Health, or HealthShare Health Connect that support IAM. InterSystems IRIS and InterSystems IRIS for Health first supported IAM in version 2019.1.1, and HealthShare Health Connect first supported IAM in version 2020.1.

   5. Ensure that your InterSystems IRIS license file specifies “API Management enabled”. If it doesn't, contact InterSystems to obtain a license file that enables IAM.

   6. Download the distribution archive (tarball file) with the IAM software and setup script files from the InterSystems WRC download site. You can download distribution archive from the following WRC download page: https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab. To show only the IAM kits, type IAM in the Name column.

   7. Extract the files from the distribution archive.

2. Enable the IAM user and web application on the InterSystems IRIS instance. The purpose of the IAM user is to allow the setup script to get a copy of the IAM license from the instance of InterSystems IRIS; the IAM user has very limited privileges and is only used to access the IAM license information. In the Management Portal for the instance of InterSystems IRIS, InterSystems IRIS for Health, or HealthShare Health Connect:

   1. Select System Administration > Security > Applications > Web Applications and select the /api/iam web application.

   2. Select the Enable Application check box.

   3. Select Save.

   4. Select System Administration > Security > Users and select the IAM user.

   5. Enter a new password and select the User enabled check box.

   6. Select Save.

3. Execute the following command (in the directory where you extracted the IAM archive) to load the IAM image into your local repository:

   docker load -i iam_image.tar
   

   

4. Run the setup script and start IAM:

   1. Run the IAM setup script.

      In a UNIX bash shell, enter:

      source ./scripts/iam-setup.sh
      

      

      Or in another UNIX shell, enter the equivalent dot command:

      . ./scripts/iam-setup.sh
      

      

   2. Enter the full image repository, name and tag for your IAM docker image. For example, it could be:

      intersystems/iam:2.3.3.2-1

   3. Enter the IP address for your InterSystems IRIS instance. If your instance is on your local machine, please use your externally visible local IP address, not "localhost". If the instance is running in a container, use the IP address of the host environment, not the IP address of the container. To avoid any DNS issues, use the numeric form of the IP address.

   4. Enter the web server port for your InterSystems IRIS instance.

   5. Enter the password for the IAM user on your InterSystems IRIS instance.

   6. Re-enter the password.

   7. If you want IAM to request the license from InterSystems IRIS using HTTPS instead of HTTP, provide the full path to your CA Certificate file; otherwise, click the Enter key.

   8. With certain InterSystems IRIS configurations, the instance is not accessible by using the instance server name. In these cases, your InterSystems IRIS instance is only accessible via its CSPConfigName URL prefix (see Changing the InterSystems IRIS Server Name in the URLOpens in a new tab) and you need to provide the prefix with a trailing slash (/) now. If this does not apply, click the Enter key.

   9. Confirm your entries.

This script sets the two environment variables required by the docker-compose file.

Environment Variables

The following environment variables are used by the docker-compose file. These are set by the startup script. If you do not use the startup script, you must define these variables.

• ISC_IAM_IMAGE — contains the respository, name, and tag of the IAM docker image. The docker-compose file uses this variable to access the docker image. The value has the format:

  repository/name:tag

• ISC_IRIS_URL — contains the URL to access the InterSystems IRIS instance to get the IAM license. The docker-compose file defines this environment variable. The value has the format:

  IAM:password@ip-address:port-number/api/iam/license

  where password is the password of the IAM account on the InterSystems IRIS instance and ip-address:port-number are the IP address and web server port of the instance.

• ISC_CA_CERT — optionally contains the contents of the CA certificate file for the server running InterSystems IRIS. If local policy requires that HTTPS be used for communication, then this environment variable must contain the contents of the server’s CA certificate.

These environment variables are defined in the shell and allow the docker-compose file to access the IAM container and the InterSystems IRIS image. If you are not in the shell where you executed the setup script, these environment variables are not defined. You can either re-run the script or define them in another way.

By default IAM listens on the following ports:

• :8000 on which IAM listens for incoming HTTP traffic from your clients, and forwards it to your upstream services.

• :8443  on which IAM listens for incoming HTTPS traffic. This port has a similar behavior as the :8000  port, except that it expects HTTPS traffic only. This port can be disabled via the configuration file.

• :8003  on which IAM listens for  Developer Portal GUI traffic — if the Developer Portal is enabled.

• :8004 on which IAM listens for   Developer Portal /files traffic — if the Developer Portal is enabled.

• :8001  on which the Administration API listens.

• :8444  on which the Administration API listens for HTTPS traffic.

• :8002 on which IAM listens for management portal GUI traffic.

• :8445 on which IAM listens for HTTPS management portal GUI traffic.

Start and Test API Manager

The docker-compose.yml file is a convenient way to start and stop IAM in the docker container. To start IAM, navigate to the /scripts directory with the docker-compose.yml file and execute the following command to start IAM:

docker-compose up -d

You can access the user interface at http://localhost:8002/.

To test the IAM setup, navigate to the directory scripts), and run the iam-test script. This script sets up a route and a service in IAM and allows you to check connectivity with your InterSystems IRIS instance.

Stop API Manager

To stop the IAM container navigate to the directory with the docker-compose.yml file and execute the following command:

docker-compose down

Note that you need to be in the same shell as the one that you ran the setup scripts or you need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables.

Restart API Manager

To restart the IAM container, navigate to the /scripts directory with the docker-compose.yml file and execute the following command to start IAM:

docker-compose up -d

Note that you need to be in the same shell as the one that you ran the setup scripts or you need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables.

Troubleshooting IAM Installations

This topic covers some common issues you can run into when installing IAM. We will add additional issues when we discover them.

Getting the IAM Logs

If you run into installation problems, it may help to view the install logs. If you are running IAM using the supplied setup scripts with Docker, you can find the logs with:

docker logs scripts_iam_1
docker logs scripts_db_1