InterSystems IRIS Managed Service Reference Information

In the Deployment Details section of the Overview page for your deployment, you can view the details of your deployment, including:

• Deployment size

• Creation date

• Deployment ID

• Cloud provider and region

• High Availability State

• Underlying InterSystems IRIS platform

The xDBC Details section of the Overview page provides information on how to connect to your InterSystems IRIS Managed Service database using a JDBC or ODBC client. You can also find out how to install the necessary InterSystems IRIS JDBC or ODBC driver.

You also need to create an inbound firewall rule to open port 1972 on the Firewall page.

For more information on querying your InterSystems IRIS Managed Service database using JDBC or ODBC, see Query Your Data.

The Interoperability Details section of the Overview page displays the File System Interoperability directory name to be used by Interoperability Productions Opens in a new tab that need to store files on the file system. If you have a High Availability configuration, files in this directory are copied automatically from the primary mirror member to the backup mirror member.

This section also displays the CIDR Block for the private network used for this deployment, as well as the Virtual IP Address of the deployment. This CIDR block defines the range of IP addresses used for the internal InterSystems IRIS Managed Service components. The Virtual IP address is a static address within the CIDR block that you use to communicate with this InterSystems IRIS Managed Service deployment. If you have a High Availability configuration, this Virtual IP address will continue to work no matter which mirror member is the primary member.

The External IP is displayed only if you have enabled public access on the Firewall page.

When you create an interoperability production, the Cloud Services Portal also creates a namespaceOpens in a new tab for the production, which includes a database for the code and data for that production. After creating a production, you can configure and manageOpens in a new tab it using the Management Portal.

For more information on developing productions, see the InterSystems IRIS documentation setOpens in a new tab.

If your InterSystems IRIS Managed Service deployment was created with the High Availability configuration, the databases for your interoperability productions are automatically mirrored to the backup server.

To create a production:

1. On the Productions page, under Create Interoperability Production, type the desired name of your production.

2. Click Create Production.

After you create a production, it shows up in the Productions list at the top of the page with a Production State of Stopped. When the creation process is finished, the Production State changes to Running. The Production Started column shows the time the production was started, in GMT. You may need to click Refresh to update the status.

To manage the production in the Management Portal, click Manage in the row for that production. You will need to log in as a user that you or a team member has created (and granted production access to) on the Connect Users page

To delete an interoperability production:

1. On the Productions page, click the Delete Production icon in the Actions column for that production.

2. In the Delete Production dialog box, type Permanently Delete, and click Delete.

The production is removed from the Productions list at the top of the page.

To create a new SQL Gateway configuration:

1. On the SQL Gateways page, under Create SQL Gateway Configuration, type the Configuration Name of your SQL Gateway configuration.

   Only alphanumeric characters are allowed. No spaces or special characters.

2. Choose a Driver to use for the connection.

3. In the Server box, type the URL of the server to use for this connection.

4. In the Port box, type the port number to connect to on the server.

5. In the Database box, type the name of the external database.

6. In the User box, type the username to use to connect to the external database.

7. In the Password box, type the password to use to connect to the external database.

8. Click Create Configuration.

After you create a configuration, it shows up in the SQL Gateway Configurations list at the top of the page.

To test a SQL Gateway configuration:

On the SQL Gateways page, click the Test Configuration icon in the Actions column for that configuration.

You should see the message “Successfully connected to remote server.”

If you see the message “There was an issue testing configuration. Please double check configuration parameters.” then edit the SQL Gateway configuration and try again.

To edit a SQL Gateway configuration:

1. On the SQL Gateways page, click the Edit Configuration icon in the Actions column for that configuration.

2. In the dialog box, edit any of the fields, and click Save.

See Create a SQL Gateway Configuration for information on each field.

To delete a SQL Gateway configuration:

1. On the SQL Gateways page, click the Delete Configuration icon in the Actions column for that configuration.

2. In the Delete Configuration dialog box, type Permanently Delete, and click Delete.

The configuration is removed from the SQL Gateway Configurations list at the top of the page.

The Network Connectivity Test section of the Network page allows you to test connectivity from this deployment to a particular server and port. The server could be an external server or an on-premise server accessed over your company’s VPN.

To perform a connectivity test:

1. In the Network Connectivity Test section of the Network page, in the IP or Hostname box, type the IP address (such as 203.0.113.0) or hostname (such as example.com) of the server to which you want to connect.

2. In the Port box, type the port number to which you want to connect on that server.

   You can specify one of the following ports: 22, 53, 443, 465, 587, or a port in the range 1024-65535.

3. Click Test Connection.

   You will see either a success or failure message.

The VPC Flow Logs section of the Network page allows you to monitor the traffic coming in and out of this deployment. This allows you to confirm that your network configuration is correct, debug network issues, monitor traffic patterns, or identify unauthorized access attempts.

To view flow log entries:

1. In the VPC Flow Logs section of the Network page, optionally filter the log by entering one or more of the following fields:

   • Actions — Choose ACCEPT to see only traffic that was permitted to flow from the source to the destination or REJECT to see only traffic that was blocked from reaching its intended destination.

   • Host IP — Type the IP address of either the source or destination.

   • Host Port — Type the port of either the source or destination.

2. Enter the Start Time and End Time of the period of time you want to examine.

   The default window is the most recent 10 minutes. The maximum window is 30 minutes in duration.

3. Click Find.

   Flow log entries matching the entered criteria are displayed.

4. Optionally, click Load More to load more log entries.

   This button only appears if more log entries remain to be loaded.

Before creating a custom API, complete the following prerequisite steps.

1. On the Productions page, create a production and namespace to host the custom API.

2. On the Firewall page, create firewall rules for ports 443, 9080, and 9443 to allow IP addresses in a given CIDR block to connect to the custom API.

3. On the Connect Users page, create a Connect User you can use to connect to the custom API, and make sure the user has access to the production and namespace you created.

4. Create a dispatch class to define the routes of the custom API and associate each with a method in the class.

5. If you are using mTLS, make sure you have the required certificates.

From the System Management page, log in to the InterSystems IRIS Managed Service Management Portal.

In the namespace you created to host the custom API, create a dispatch class using Microsoft VS Code and GitLab. The dispatch class must extend %CSP.RESTOpens in a new tab. (For test purposes, you can create class and upload it to the Management Portal (System Explorer > Classes > Import.)

The following sample class, Sample.RestApp, has three routes that all map to the class method Test(), which accepts up to two arguments.

Class Sample.RestApp Extends %CSP.REST
{

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
<Routes>
<Route Url="/test" Method="GET" Call="Test" Cors="true"/>
<Route Url="/test/:name" Method="GET" Call="Test" Cors="true"/>
<Route Url="/test/:name/:name2" Method="GET" Call="Test" Cors="true"/>
</Routes>
}

ClassMethod Test(name = "World", name2 = "") As %Status
{
    write "Hello ", name_" "_name2, "!<br/>", !
    quit 1
}

}

Before setting up the optional mTLS configuration, make sure you have a Certificate Authority (CA) certificate containing the entire certificate chain and a client certificate signed by the CA.

If you need certificates for testing purposes you can create them with openssl using a procedure like the one below. This example was created on Linux.

First, create a private key (ca.key) for the root CA and a self-signed x.509 certificate (ca.crt) for the CA:

$ openssl genrsa -out ca.key 4096
$ openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt -subj "/CN=MyTestRoot"

Then, create a private key (client.key) for the client, a certificate signing request (client.csr), and a client certificate (client.crt) that is signed by the root CA:

$ openssl genrsa -out client.key 2048
$ openssl req -new -key client.key -out client.csr -subj "/CN=MyTestClient"
$ openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt
Certificate request self-signature ok
subject=CN = MyTestClient

Finally, verify the client certificate to make sure it is properly signed by the CA:

$ openssl verify -CAfile ca.crt client.crt
client.crt: OK

Upload the CA certificate to InterSystems IRIS Managed Service on the mTLS Client CAs tab of the Custom APIs page:

1. On the mTLS Client CAs tab of the Custom APIs page, click Upload CA Cert.

2. In the Upload Client CA Cert for mTLS dialog, in the Hostname Prefix box, type a prefix to distinguish requests that will be handled for the custom API with mTLS, for example, my-app.

   The prefix will be added to the base URL shown on the Custom APIs page in the Cloud Services Portal, for example, my-app.api.<deployment_id>.<server_name>.

3. In the Client Certificate Authority Contents text box, copy and paste the contents of your ca.crt file.

4. Click Save.

   Your CA will appear in the list on the mTLS Client CAs tab of the Custom APIs page.

After you create the custom API, send the client certificate and key along with each request to the custom API and InterSystems IRIS Managed Service will authenticate it against the CA. See Test a Custom API with mTLS for more information.

After performing the prerequisite steps and creating a dispatch class, you are ready to create your custom API, which includes a built-in web gateway to receive requests and direct them to your custom API.

1. On the Custom APIs tab of the Custom APIs page, enable the Custom API feature, if it is not already enabled, by moving the Enable slider to the right.

   It will take a few seconds for the feature to be enabled.

2. On the Custom APIs tab, click Create Custom API.

3. On the Create Custom API dialog:

   1. Type the Custom API Name.

      This is the path representing the endpoint of your REST API, for example, /ics/api.

      Important:

      The path you specify must not start with the following prefixes, as errors could occur: /api, /csp, /cloud, /isc, /ui.

   2. Check the Enabled box to enable the custom API.

   3. Select the Namespace you created to host the custom API.

   4. Type the name of the Dispatch Class you created, for example, Sample.RestApp.

   5. Under Security Settings, type the Rate Limit Count and the Rate Limit Time Window for your custom API.

      For example, entering 1000 and 10 for these settings, respectively, means that you are limiting the number of API requests allowed through the web gateway to 1,000 in a 10-second window.

   6. Select an IP Restrict Mode:

      • None means allow requests from all IP addresses.

      • Allow means allow requests only from the IP addresses and CIDR blocks on the Allow List.

      • Deny means deny requests only from the IP addresses and CIDR blocks on the Deny List.

   7. If applicable, on the Allow List or Deny List, type single IP addresses or CIDR blocks, one per line.

      See the text box for examples.

   8. In the mTLS Client CA drop-down, select the hostname prefix associated with a CA certificate you uploaded earlier.

      If you are not using mTLS, select None.

   9. Click Save.

The custom API now appears in the list at the top of the screen.

Use the icons in the Actions column of the list to edit the settings for a custom API or to delete a custom API.

Before using the custom API, go to the Connect Users page and give your Connect User access to the custom API.

Using a custom API can be broken down into two parts, represented by the following HTTP requests.

The first request is sent to the built-in Cognito instance to authenticate the user and obtain a bearer token:

POST / HTTP/2 
Host: cognito-idp.<aws_region>.amazonaws.com 
x-amz-target: AWSCognitoIdentityProviderService.InitiateAuth 
content-type: application/x-amz-json-1.1 

Once the bearer token is received, it can be used to make subsequent requests to the custom API:

GET /ics/api/test/<arg1>/<arg2> HTTP/2 
Host: api.<deployment_id>.<server_name>:9443 
authorization: Bearer ******

The above GET request uses the custom API name you chose when you created your custom API (in this case, /ics/api) and the sample dispatch class shown above.

The section below gives an example of how to test your custom API from the command line. If you use an API client, such as Postman, you can use it for testing, as well.

Before testing a custom API, go to the Connect Users page and give your Connect User access to the custom API.

Test a Custom API from the Command Line

The following example demonstrates how to test a custom API from the command line, using curl. It is an annotated version of the one shown on the Help tab of the Custom APIs page in the Cloud Services Portal. On the Help tab, select your custom API from the drop-down at the top of the page to enable easier copy and paste from the displayed content.

The example uses jq to make the handling of JSON objects easier. If you don’t have jq, you can download it from https://github.com/jqlangOpens in a new tab.

Perform this workflow from a POSIX-compliant shell.

Make sure shell is POSIX compliant:

$ echo "$SHELLOPTS" | grep -o posix
posix

Set a variable to the cognitoClientId shown on the Help tab of the Custom APIs page in the Cloud Services Portal.

$ connectClientId=<cognitoClientId>

Set variables to hold the username and password of your Connect User:

$ connectUsername=<username>

$ connectPassword=<password>

Set a variable to the custom API name you chose when you created your custom API:

$ customApiName=/ics/api

Use jq to format the body of the request to be sent to Cognito. The arguments in the jq command are passed into the body of the JSON string of the request. The line below is broken for readability.

$ BODY=$(jq -n --arg user "$connectUsername" --arg pwd "$connectPassword" --arg clientId "$connectClientId" \
'{"AuthParameters":{"USERNAME":$user,"PASSWORD":$pwd},"AuthFlow":"USER_PASSWORD_AUTH","ClientId":$clientId}')

Confirm that the JSON string of the body looks good:

$ printf "%s\n" "$BODY"
{
  "AuthParameters": {
    "USERNAME": "<connectUsername>",
    "PASSWORD": "<connectPassword>"
  },
  "AuthFlow": "USER_PASSWORD_AUTH",
  "ClientId": "<connectClientId>"
}

Send the authentication request to Cognito. The <aws_region> in the URL (for example, us-east-2) is shown in the example on the Help tab of the Custom APIs page in the Cloud Services Portal. The line below is broken for readability.

$ RESPONSE=$(curl -X POST --data "$BODY" -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
-H 'Content-Type: application/x-amz-json-1.1' https://cognito-idp.<aws_region>.amazonaws.com/)

Verify that the response looks good. The following JSON string is formatted for readability.

$ echo $RESPONSE
{
  "AuthenticationResult": {
    "AccessToken": "******",
    "ExpiresIn": 3600,
    "IdToken": "******",
    "RefreshToken": "******",
    "TokenType": "Bearer"
  },
  "ChallengeParameters": {}
}

Use jq to extract the access token from the response:

$ ACCESS_TOKEN=$(echo $RESPONSE | jq -r ".AuthenticationResult.AccessToken")

Note:

Make sure to use the access token for all of your requests. If you use the ID token for the request instead of the access token, a 401 status code is returned.

Send a request to the custom API. This example uses the dispatch class above . The <base_url> is the customApiBaseURL shown on the Custom APIs page in the Cloud Services Portal and takes the form https://api.<deployment_id>.<server_name>. The variable $customApiName is the one set near the start of this example.

The client must also have the server’s CA certificate in its certificate store. For testing purposes, this cert can be downloaded and then included with the request (--cacert <server_ca>, in the example below).

$ curl -H "Authorization: Bearer $ACCESS_TOKEN" -vv <base_url>:9443${customApiName}/test/my/friend --cacert <server_ca>

The verbose option (-vv) allows you to see the entire handshake, which can be useful for debugging your configuration.

The response to the request, minus the handshake, is as follows:

Hello my friend !

Test a Custom API with mTLS

Sending a request to a custom API that uses mTLS is the same as for regular custom APIs, with the following differences:

• The hostname prefix is added to the base URL, so requests are sent to <hostname_prefix>.api.<deployment_id>.<server_name>, instead of api.<deployment_id>.<server_name>, where <hostname_prefix> is the prefix you specified when you uploaded the CA certificate associated with this custom API.

• The client certificate (--cert client.crt, in the example below) and client private key (--key client.key) are sent with the request.

• The client must also have the server’s CA certificate in its certificate store. For testing purposes, this cert can be downloaded and then included with the request (--cacert <server_ca>, in the example below).

For more information, see Certificates Needed for mTLS.

Before sending your request to the custom API, set a variable to hold the hostname prefix. If the hostname prefix were my-app, the command would like this:

$ customApiHostPrefix=my-app

If the custom API in the example above were created with mTLS, a request to the custom API might look something like:

$ curl -H "Authorization: Bearer $ACCESS_TOKEN" -vv --cert client.crt --key client.key  --cacert <server_ca> \
https://${customApiHostPrefix}.api.<deployment_id>.<server_name>:9443${customApiName}/test/my/friend

Again, the verbose option (-vv) allows you to see the entire handshake, which can be useful for debugging your configuration.

The response to the request, minus the handshake, is again as follows:

Hello my friend !

InterSystems IRIS Managed Service comes with a built-in custom API that returns interoperability metrics on a deployment. This custom API can also be used for testing purposes and is available from any namespace.

To use the interoperability metrics custom API, create a custom API, giving it a custom API name of your choosing (for example, /ics/monitor) and using the built-in dispatch class ISCCD.RestMetrics.

The route for this custom API is /metrics, so if you created the custom API with the custom API name /ics/monitor, you would test the custom API by sending requests to the URL below. The <base_url> is the customApiBaseURL shown on the Custom APIs page in the Cloud Services Portal and takes the form https://api.<deployment_id>.<server_name>.

<base_url>:9443/ics/monitor/metrics

To filter metrics by namespace, use:

<base_url>:9443/ics/monitor/metrics/<namespace>

The <namespace> is not case sensitive.

For more information on the Interoperability Metrics Custom API, including Swagger documentation, see the Help tab on the Custom APIs page.

The Logs and Metrics tab of the Custom APIs page lets you view metrics and access logs for a particular custom API over a given time period. The Metrics section shows you the number of total requests received by the custom API during that time period and gives a breakdown of the total by HTTP status code. The Logs section shows you a list of the requests received by the custom API during the time period. For each request, the log shows the:

• timestamp (in UTC)

• IP Address of the client making the request

• HTTP status code (for example, 200 for success or 401 for unauthorized)

• method (for example, GET or PUT)

• URI, including any query parameters (for example, /ics/api/test/my/friend)

An entry is only shown in the access log if the custom API received the request. If a valid endpoint is used, but the custom API does not accept the connection, no log entry is displayed (for example, if you configure the custom API to use mTLS, and the mTLS connection does not succeed).

To request metrics and logs for a custom API:

1. On the Custom APIs page, click the Logs and Metrics tab.

2. In the Search section of the page:

   1. In the Custom API drop-down, select a custom API.

   2. Specify a Start Time and End Time of the time period for which you want to view metrics and logs (in UTC).

   3. Optionally, filter the search by Status Code, Client IP, and/or URI Prefix.

   4. Click Search.

The search results appear in the Metrics and Custom API Logs sections of the page.

If you are using DNS aliases, you can use an alias instead of the default base URL when calling a custom API.

For example, you can use

https://<deployment_alias>.<tenant_alias>.<portal_domain>

instead of

https://api.<deployment_id>.<server_name>

Any DNS aliases defined for the deployments in your tenant are listed on the DNS Aliases page of the Cloud Services Portal. See the FQDN column in the list of aliases for the exact value to use when calling your custom API. For more information, see DNS Aliases PageOpens in a new tab.