Skip to main content

Installing IAM Version 3.0

This article tells you how to install, start, stop, and test the InterSystems API Manager (IAM). IAM must be installed on a Linux system.

If you are upgrading your existing version of IAM, see Upgrading to IAM Version 3.0.

Since IAM is provided in container format, you need software that supports the Open Container Initiative (OCI)Opens in a new tab to install and run the IAM container. This article uses Docker as an example of software that supports OCI.

Note:

In this article, InterSystems IRIS® refers to any InterSystems product based on InterSystems IRIS that supports IAM. This includes InterSystems IRIS for Health and HealthShare® Health Connect.

New in IAM 3.0

Steps Required to Install IAM

  1. Ensure that the Linux system where you will be installing IAM has the required prerequisites.

  2. Download and extract the IAM installation files from the tar file.

  3. Enable the InterSystems IRIS instance that IAM will connect with, to use IAM.

  4. Set up IAM.

Ensure Your Linux System Has the Required Prerequisites

  1. Install the following tools if you do not already have them:

    1. Docker or Podman. See Running InterSystems Products in ContainersOpens in a new tab for a brief introduction to containers and Docker.

    2. Docker Compose or Podman Compose command line interface tool.

    3. Curl. The script files that set up and test IAM use curl.

  2. Ensure that you have a running instance of InterSystems IRIS, InterSystems IRIS for Health, or HealthShare Health Connect that supports IAM:

    • InterSystems IRIS and InterSystems IRIS for Health first supported IAM in version 2019.1.1.

    • HealthShare Health Connect first supported IAM in version 2020.1.

Download and Extract the IAM Installation Files

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 tar file. Choose the IAM kit if you are installing on x86–64 architecture, or choose the IAM-ARM64 kit if you are installing on ARM64 architecture. Once you uncompress it and extract the files, you will find the following contents in the distribution kit:

  • iam-image.tar — This is the IAM Docker image. Do not extract the files from the archive at this time.

  • scripts directory containing:

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

    • iam-setup.sh script to provide an easy way to set up the environment variables required by IAM

    • iam-test.sh script to provide an easy way to test connectivity to your InterSystems IRIS instance

    • iam-upgrade-db directory which contains the tools and scripts required to upgrade to IAM 3.0

  • readme.txt file containing brief instructions for starting IAM.

  • EULA.pdf file containing terms and conditions

Enable Your InterSystems IRIS Instance to Use IAM

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

    1. In the Management Portal, select System Administration > Licensing > License Key.

    2. Look in the Authorization Key section. If -API Management is listed, this license will allow the instance to use IAM.

  2. Enable the IAM user. 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 that it will connect with. The IAM user has very limited privileges and is only used to access the IAM license information.

    1. In the Management Portal, select System Administration > Security > Users and select the IAM user.

    2. Click the Password radio button.

    3. Enter and confirm a password for the IAM user.

    4. Select the User enabled check box.

    5. Select Save.

  3. Enable the IAM web application.

    1. In the Management Portal 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. Ensure that the IAM application dispatch class is permitted to run. Under a strictly secured system, this class may be disabled. To check, open the ObjectScript shell, switch to the %SYS namespace, and enter the following command:

     zwrite ^SYS('Security','CSP','AllowClass','/api/iam/','%Api.IAM.v1.disp')
    

    You should see the following:

    ^SYS('Security','CSP','AllowClass','/api/iam/','%Api.IAM.v1.disp')=1
    

    If you do not see the above, enter the following command:

     set ^SYS('Security','CSP','AllowClass','/api/iam/','%Api.IAM.v1.disp')=1
    

Set Up IAM

  1. Load the IAM image into your local repository by executing the following command in the directory where you extracted the IAM archive:

    docker load -i iam_image.tar
    
    podman load -i iam_image.tar
    
  2. Make a note of the value of Loaded image from the output of the docker load command. It is required in step 3b.

  3. Run the IAM setup script and enter the requested information at the prompts.

    1. In a UNIX bash shell, enter:

      source ./scripts/iam-setup.sh
      
    2. At the first prompt, enter the container image name. The container image name can be found in the output of the docker load command, as the value of Loaded image. For example, it could be:

      intersystems/iam:3.0.2.0-2

    3. Enter the IP address for your InterSystems IRIS instance. If your instance is on your local machine, use your externally visible local IP address, not localhost or 127.0.0.1. 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, press Enter.

    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, press Enter.

    9. To continue and use the information you entered, press y then press enter.

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

Start IAM

The docker-compose.yml file provides a convenient way to start and stop IAM in the docker container. You must be in the same shell as the one in which you ran the setup script or you will need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables To start IAM, navigate to the scripts directory containing the docker-compose.yml file and execute the following command:

docker compose up -d
docker-compose up -d
podman-compose up -d

You can now access the IAM management portal at http://localhost:8002/ and the developer portal at 127.0.0.1:8003.

Note:

The docker-compose.yml file defines the URLs that are used to access the IAM management portal and the developer portal. To avoid Cross-Origin Resource Sharing (CORS) errors when accessing the IAM management and developer portals, the URLs that you use must match the URLs defined in the docker-compose.yml file in the KONG_ADMIN_GUI_URL and KONG_PORTAL_GUI_HOST environment variables. The default values of these are http://localhost:8002 for the management portal and 127.0.0.1:8003 for the developer portal. If you will be using different URLs to access these portals, you must edit the docker-compose.yml file before you start IAM. For details on how Kong Enterprise handles CORS and other DNS issues, see DNS Considerations for Kong GatewayOpens in a new tab.

Test IAM

To test the IAM setup, use the same shell as the one in which you ran the setup script or you will need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables. Navigate to the scripts directory with the docker-compose.yml file and execute the following command:

./iam-test.sh

This script sets up a route and a service in IAM. To test if requests to IAM are successfully forwarded to your InterSystems IRIS instance, run the curl command provided by the test script.

Stop IAM

You must be in the same shell as the one in which you ran the setup script or you will need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables.

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

docker compose down
docker-compose down
podman-compose down

Environment Variables

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

  • ISC_IAM_IMAGE — set to the container image name of your IAM docker image. The value has the format:

    repository/name:tag

  • ISC_IRIS_URL — set to the username, password, and URL of the InterSystems IRIS instance where IAM will get license from. 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 docker-compose to access the IAM container. 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.

Ports

By default, IAM listens on the following ports:

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

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

  • :8003 IAM listens for HTTP Developer Portal GUI traffic, if the Developer Portal is enabled.

  • :8004 IAM listens for Developer Portal /files traffic over HTTP, if the Developer Portal is enabled.

  • :8001 Administration API. Listens for calls from the command line over HTTP.

  • :8444 Administration API. Listens for calls from the command line over HTTPS.

  • :8002 IAM listens for HTTP management portal GUI traffic.

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

Troubleshooting

This topic covers some common issues you can run into when installing or running IAM.

Get the IAM Logs

It is a good practice to check the logs after installing or updating IAM. If you run into any problems, start your troubleshooting by viewing the logs. When using Docker or Podman and the supplied setup scripts, you can find the logs with:

docker logs scripts-iam-1
docker logs scripts-db-1
docker logs scripts_iam_1
docker logs scripts_db_1
podman logs scripts_iam_1
podman logs scripts_db_1

Error message "FATAL:  sorry, too many clients already" appears in the logs

The number of NGINX worker processes is being computed incorrectly in the IAM container.  This problem can be resolved by explicitly setting the number of worker processes.  You can do this by adding the following line to the iam.environment section of the docker-compose.yml file:

KONG_NGINX_WORKER_PROCESSES: 15

The correct number of worker processes can be difficult to determine. See the Kong documentationOpens in a new tab for more information.

“error calculating” appears in the IAM Portal

The number of NGINX worker processes is being computed incorrectly in the IAM container.  This problem can be resolved by explicitly setting the number of worker processes.  You can do this by adding the following line to the iam.environment section of the docker-compose.yml file:

KONG_NGINX_WORKER_PROCESSES: 15

The correct number of worker processes can be difficult to determine. See the Kong documentationOpens in a new tab for more information.

Cannot Get IAM License

There are multiple reasons why IAM cannot communicate with the InterSystems IRIS instance to get the license. This problem shows up in the following ways:

  • The iam-setup.sh script displays one of the following:

    • The /api/iam web application is disabled. Please enable it before running this script again.

    • Authorization failed. Please make sure to enable the IAM user and reset its password before running this script again. This error may also mean that you entered the wrong password to this script.

    • No content. Either your InterSystems IRIS instance is unlicensed or your license key does not contain an IAM license.

    • Request failed with a 400 status code. You may be trying to use HTTP on an SSL-enabled server port.

    • Couldn't reach InterSystems IRIS at $ip:$port. One or both of your IP and Port are incorrect.

  • In some rarer cases, IAM may not succeed in getting the license even if the script reports “Successfully got IAM license!”. In this case, the symptom would be “could not decode license JSON: No license found” appearing in the IAM log. This condition could be caused by a network setup where the script running on the host has access to the InterSystems IRIS instance but IAM running in a container does not have access to it.

One other reason that IAM cannot access the InterSystems IRIS instance, is if it is configured so that the instance is not accessible by the default URL with the server name or the /api interface is blocked. In this case, you must specify the CSPConfigName URL prefix in the startup script (see Changing the InterSystems IRIS Server Name in the URLOpens in a new tab).

IAM Management Portal or Developer Portal Is Empty

If you enter the URL for the IAM management portal or the developer portal and the portal does not display with content, it is possible that you have entered a URL that may seem correct but is not the URL specified by the docker-compose.yml file. The docker-compose.yml file defines the URLs that are used to access the IAM management portal and the developer portal. To avoid Cross-Origin Resource Sharing (CORS) errors when accessing the IAM management and developer portals, the URLs that you use to access them must match the URLs defined in the docker-compose.yml file in the KONG_ADMIN_GUI_URL and KONG_PORTAL_GUI_HOST environment variables. The default values of these are http://localhost:8002 for the management portal and 127.0.0.1:8003 for the developer portal. If you will be using different URLs to access these portals, you must edit the docker-compose.yml file before you start IAM. For details on how Kong Enterprise handles CORS and other DNS issues, see DNS Considerations for Kong GatewayOpens in a new tab.

FeedbackOpens in a new tab