Skip to main content

Installing IAM 0.34

Note:

This is not the current version of IAM. For information on using the other versions of IAM, see InterSystems API Manager.

This topic tells you how to install the InterSystems API Manager (IAM) from the installation tar file. IAM is provided in container format. You need software that supports the Open Container Initiative (OCI)Opens in a new tab to be able to install and run the IAM container. This topic uses Docker as an example of software that supports OCI. You can download the installation tar file from the InterSystems Worldwide Response Center (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. IAM is distributed as a compressed tarball archive. Once you uncompress it and extract the files, you will find the following contents in the distribution kit:

  • IAM Docker image, iam-image.tar — do not extract the files from this archive.

  • scripts directory with:

    • docker-compose.yml script to start and stop IAM

    • unix and win directories with UNIX and Windows scripts to setup and test IAM — these optional scripts provide an easy way to start and test IAM. The startup scripts set up the environment variables in the current shell used by IAM. If you do not use the scripts, you need to define these variables some other way. The variables are described in the next section.

  • readme.txt file with brief instructions for starting IAM. This topic is based on the readme but provides some additional information.

  • EULA files with terms and conditions

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. On UNIX systems, install the curl utility. The UNIX script files to start and test IAM use curl. The Windows script file uses PowerShell to invoke web requests and does not require 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 create the container and load the IAM image: 

    docker load -i iam_image.tar

  4. If you want to secure the IAM administrative API, you must add an authentication plug-in to IAM. You should set a password for the IAM Super Admin account by defining the environment variable KONG_PASSWORD in the container before running the setup script. You can either define it in the shell or in the docker-compose file. If this password is defined in the container, IAM creates a user, kong_admin, and specifies the value as the password for an account that can be used to log in to IAM Manager or to make Admin API requests when RBAC is enabled.

  5. Run the setup script and start IAM:

    1. Run the IAM setup script. If you are running the script on UNIX, you must ensure that the script is run in the same process, not a subprocess by using the bash source command or the dot command. In a Windows PowerShell, enter:

      .\scripts\win\iam-setup.ps1

      In a UNIX bash shell, enter:

      source ./scripts/unix/iam-setup.sh

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

      . ./scripts/unix/iam-setup.sh

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

      intersystems/iam:1.5.0.9-4

    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 for 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, type the Enter key.

    8. 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 and by IAM. 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:

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

  • KONG_PASSWORD — contains the password for a Kong administrator account. If this is defined before you run the docker-compose command, IAM creates a user, kong_admin, and specifies the value as the password for an account that can be used to log in to IAM Manager or to make Admin API requests when RBAC is enabled.

  • 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.

  • KONG_ADMIN_GUI_URL — contains the URL of the IAM administration page. The docker-compose file sets this to http://localhost:8002/.

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 the Developer Portal GUI traffic — if the Developer Portal is enabled.

  • :8004 on which IAM listens for  the 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.

  • :8445 on which IAM listens for HTTPS traffic.

Start and Test API Manager

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 with the scripts for the operating system you are running (scripts/win or scripts/unix), 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.


Previous sectionIntroduction to the InterSystems API Manager (IAM) Version 0.34
FeedbackOpens in a new tab