RESTful API Infrastructure & Interoperability Services Supporting Documentation - Last Modified March 10th, 2021 - Meditech
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
RESTful API Infrastructure & Interoperability
Services
Supporting Documentation
Last Modified March 10th, 2021Table of Contents
*Click the sec on tle to jump to the desired page.
Table of Contents 1
Overview 3
Notes 3
Requirements 4
API Server(s) 4
Cache Server 4
Database Server 4
TCP Proxy Service(s) 5
Load Balancer/Proxy 5
SSL Cer ficate(s) 6
Evalua on Task 6
DNS Entries 6
Configura on Diagrams 8
Clinical Decision Support Mechanism (CDSM) for AUC (Vendor such as NDSC) Op mum Configura on 8
Minimum CDSM for AUC Suggested Configura on 9
TCP Proxy Op mum Configura on 10
Minimum TCP Proxy Suggested Configura on 11
Connec vity 12
Outbound Traffic 12
Inbound Traffic (All Clients) 13
Proxy - SSL Termina on 13
Proxy - SSL Bridging 14
Proxy - TCP Proxy 14
Inbound Traffic (Trusted Clients) 15
Load Balancer/Proxy Configura on 16
Header Inser on 16
IPs and Ports 16
Health Check 17
Trusted Proxies 17
Security 17
The Flow 17
Layers 18
Terms 19
Applica on Server/Service 19
API Server/Service 19
ACL 19
MEDITECH 2020 - 1Blacklis ng 19
Client ID 19
Client Secret 19
DoS 20
End to End Encryp on (E2EE) 20
Environment 20
MITM 20
Quota 20
Resource 20
Scope 20
TCP Proxy Service 20
Token 20
Whitelis ng 20
Installa on Valida on Guide 21
Important Note 21
Check DNS 21
Check Services 21
Check Connec vity 22
Change Log 24
MEDITECH 2020 - 2Overview
The RESTful API Infrastructure allows MEDITECH and third party vendor so ware to securely access the MEDITECH EHR
through APIs. Interoperability Services (or IOPS) — which is a component of the RESTful API Infrastructure and installed
on the same machine(s) — adds a set of APIs to meet Meaningful Use Stage 3 (MU3) and Imaging Appropriate Use
Criteria (AUC) requirements.
RESTful API is independent from any other web products or interoperability interfaces MEDITECH offers and requires
dedicated hardware.
Notes
● "Proxy" and "Load Balancer" are used interchangeably throughout this document and always refer to the
appliance or service which will proxy the traffic to the RestAPI Infrastructure server(s).
MEDITECH 2020 - 3Requirements
Although some hardware and so ware requirements are listed below, the full and detailed list can be found here.
API Server(s)
An op mal RESTful API Infrastructure configura on consists of two or more servers running the RESTful API services as
well as Interoperability Services. The cluster helps to ensure be er performance and failover protec on for the
Infrastructure. However, as a minimum configura on, organiza ons can start out with one API server. More servers can
be added based upon usage and performance needs.
Note: IIS is not used in this configura on and should not be installed on these servers. The RESTful API Infrastructure
performs the role of a web server.
Purpose
These servers host the web services which clients connect to.
Support
MEDITECH provides support.
Hardware/So ware
Please review the TECH task outlining your hardware configura on proposal (HCP).
Cache Server
The Redis service, which MEDITECH will install on the Cache Server, reduces latency and increases performance on
requests by reducing the number of hits to the database.
The cache is memory-only, meaning it is never persisted to disk.
It is suggested that the Redis service run on its own server (as seen here). However, site may choose to have MEDITECH
install the Redis service on one of the API servers (as seen here) if addi onal servers cannot be obtained. If combining
the two servers, it is suggested you increase the RAM available to that API server by 4GB, bringing the total to 8GB for
that one API server.
Please review the related security documenta on to secure the Redis installa on. It can be found here: RESTful API &
IOPS Resources - Security.
Purpose
This server caches responses and also acts as a messaging service between API Servers.
Support
MEDITECH provides support.
Hardware/So ware
Please review the TECH task outlining your hardware configura on proposal (HCP).
Database Server
A supported database is required. The RESTful API Infrastructure supports:
● MSSQL
● MySQL
● MariaDB
MEDITECH 2020 - 4Important: MySQL 8.0.4 introduces a backwards incompa bility with the client library. Please use MySQL 8.0.3 if MySQL
is your database of choice. We are working to get the client library updated but do not currently have a meline for
when the changes will be completed and tested.
Important: MariaDB and MySQL versions have varying maximum upload sizes (called "max_allowed_packet" in the
configura on). Please ensure the maximum packet size is increased to at least "32M", which is 32 megabytes. This can be
done by upda ng the appropriate "my.ini" or "my.cnf" file located in the installa on directory and restar ng
MariaDB/MySQL. This issue does not affect installa ons using MSSQL databases.
Purpose
The database stores the configura on and run me details of the RESTful services. It does not store pa ent data nor does
it store any other data that is stored in the MEDITECH database.
Support
Sites should choose the database they are most comfortable with as MEDITECH does not provide support for
maintaining or configuring the database service(s).
TCP Proxy Service(s)
A TCP Proxy Service is connected to by an API Service when processing APIs whose data originates in the MEDITECH
Expanse Pla orm. In the same manner that a cluster of API Servers is recommended to improve performance and fault
tolerance, two or more TCP Proxy Services are also recommended.
Purpose
These services proxy connec ons from the API Server(s) to processes running MEDITECH Expanse so ware.
Support
MEDITECH provides support.
Hardware/So ware
Please review the TECH task outlining your hardware configura on proposal (HCP).
Load Balancer/Proxy
A load balancer or proxy is required to sit in front of the API Server(s).
Purpose
This appliance is important for the stability and security of the system. Some of the reasons are:
● When in one of the two suggested configura ons (more below):
○ It allows the customer to mi gate or prevent SSL vulnerabili es and to configure the SSL parameters
according to their regulatory and corporate requirements
○ It allows the customer to install and maintain their SSL cer ficates in a single loca on instead of across
mul ple servers/services
● Using DNS round-robin for failover does not provide graceful failover to the client - the client so ware needs to
be smart enough to retry the connec on using another IP. Depending on the client technology, this can take
seconds or minutes. Whereas failover with a load balancer or proxy is nearly instantaneous.
● When configured for SSL Termina on, this reduces the CPU load on the RESTful API Infrastructure servers.
Support
Sites are expected to rely on their IT staff or vendor support for configuring and maintaining the load balancer/proxy.
MEDITECH provides guidance but cannot furnish sites with step-by-step instruc ons on how to configure their load
balancer/proxy.
MEDITECH 2020 - 5SSL Certificate(s)
The site must purchase one or more SSL cer ficates from a trusted cer ficate authority to be installed on their proxy or
load balancer. As there will be two hostnames per MRI or HIM database(See DNS Entries below), it is suggested that the
site purchase a wildcard or SAN (Subject Alterna ve Name) cer ficate to keep costs down. Sites may purchase a
cer ficate per hostname.
Self-signed cer ficates may ONLY be used to secure the connec on between the load balancer/proxy and the RESTful
services and only when configured for SSL Bridging.
Evaluation Task
Customers preparing for MU3 or AUC ini a ves should have a Hardware Evalua on Task opened under TECH to provide
a system review and detailed server specifica ons.
If you do not currently have a task open, contact your account manager/HCIS coordinator or technical account manager
(TAM) to request an evalua on. Please allow at least 2 weeks for comple on — upon receipt of your evalua on, an
addi onal 6-8 weeks should be allo ed to procure and set up new hardware.
DNS Entries
A DNS entry is needed for the API and Applica on end-point for each MRI or HIM database (both TEST and LIVE). These
records should all point to VIPs on your Load Balancer - you may use one or mul ple VIPs when configuring your Load
Balancer.
Another DNS entry is needed for the TCP Proxy Service. This record should point to the IPs of all the TCP Proxy servers.
It is suggested that the API services use different VIP(s) from Applica on services. This makes it easier to restrict access
to the Applica ons to only those clients that are on your network. If they shared a VIP, your firewall would need to be
able to do deep packet inspec on and disallow access to the hostnames for the Applica on services when accessed over
the Internet.
Example:
If you have 3 LIVE rings with 1 HIM database each and 3 TEST rings with 1 HIM database each, we would expect the
following DNS entries:
mtrestapis-live01.CUSTOMER-DOMAIN
mtrestapis-live02.CUSTOMER-DOMAIN
mtrestapis-live03.CUSTOMER-DOMAIN
mtrestapis-test01.CUSTOMER-DOMAIN
mtrestapis-test02.CUSTOMER-DOMAIN
mtrestapis-test03.CUSTOMER-DOMAIN
mtrestapps-live01.CUSTOMER-DOMAIN
mtrestapps-live02.CUSTOMER-DOMAIN
mtrestapps-live03.CUSTOMER-DOMAIN
mtrestapps-test01.CUSTOMER-DOMAIN
mtrestapps-test02.CUSTOMER-DOMAIN
mtrestapps-test03.CUSTOMER-DOMAIN
If you are configuring the TCP Proxy Service, a single DNS entry should be configured that will point to all the TCP Proxy
server IPs:
mtres cpproxy.CUSTOMER-DOMAIN
When not exposing the Applica ons to the Internet, only the "mtrestapis-*" entries would resolve on your public DNS.
MEDITECH 2020 - 6Purpose
The entries allow the infrastructure to differen ate requests as it is possible that an iden fier may be reused in one or
more databases. Addi onally, the API and Applica on services run on different ports and within different processes
because the workloads are significantly different
Support
Sites are expected to rely on their IT or vendor support for maintaining their DNS entries.
MEDITECH 2020 - 7Configuration Diagrams
These diagrams show the servers and connec ons. A more detailed list of protocols and ports are listed in the
Connec vity sec on.
Clinical Decision Support Mechanism (CDSM) for AUC (Vendor such as NDSC) Optimum
Configuration
MEDITECH 2020 - 8Minimum CDSM for AUC Suggested Configuration
MEDITECH 2020 - 9TCP Proxy Optimum Configuration
MEDITECH 2020 - 10Minimum TCP Proxy Suggested Configuration
MEDITECH 2020 - 11Connectivity
Outbound Traffic
This is traffic origina ng from the RESTful API server(s).
Protocol Des na on Port Usage
TCP Database Server(s) Database Dependent This is used to communicate with the
database that stores the RESTful API
Infrastructure configura on.
TCP Cache Server Configurable This is used to cache resources,
Default: 6379 removing the need to talk to the
back-end or database in some
circumstances.
TCP TCP Proxy Service(s) Configurable This is used to communicate with the
TCP Proxy Service when handling API
requests that require direct access to the
MEDITECH Expanse database.
HTTP over TCP One of the RESTful API Configurable This is used to communicate with the
Infrastructure Servers Default: 24387 IOPS Monitor service to obtain
environmental se ngs.
Note: this connec on is no longer
needed a er IOPS is updated to v1.5.0
or above.
HTTP over TCP MIS File Library Configurable This is used to obtain clinical data.
Server(s) Default: 24388
HTTP over TCP BKG Job Machines for Configurable This is used to speak with the MEDITECH
Each HCIS Default: 24400 database.
HTTPS over TCP AUC Provider 443 This is used for the Appropriate Use
Criteria for Advanced Diagnos c Imaging
(AUC) MU3 requirement.1
HTTPS over TCP Iden ty Provider 443 The Infrastructure must be able to
communicate with the Iden ty Provider
(e.g., Google) in order to validate
asser ons.
1
Not all customers will use AUC. There are mul ple cer fied decision support products such as NDSC's CareSelect.
MEDITECH 2020 - 12Inbound Traffic (All Clients)
This is traffic des ned for the RESTful API services from clients both on-network and off (i.e., internet traffic). This
includes user desktops and other MEDITECH servers.
There are mul ple possible configura ons for traffic coming into the RESTful API services.
Proxy - SSL Termination
Please use this sec on when configuring your proxy or load balancer for SSL Termina on. It is our sugges on that sites
terminate SSL at their proxy/load balancer for the best performance.
Important: The VIP on the proxy should be accessible from the internet and all networks on site.
Protocol Source Des na on Port Usage
HTTP over TCP Proxy Res ul API Services Configurable This will respond to API
Default: 80 requests that originate from
the proxy. Requests directly to
the server or from an
untrusted proxy will be issued
a redirect to HTTPS.
HTTP over TCP Proxy Res ul Applica on Configurable This will respond to
Services s) Default: 8081 Applica on requests that
originate from the proxy.
Requests directly to the server
or from an untrusted proxy will
be issued a redirect to HTTPS.
HTTPS over TCP Anywhere Proxy Configurable This is the connec on clients
Default: 443 make to access the API and/or
Applica on services proxied by
the load balancer/proxy.
MEDITECH 2020 - 13Proxy - SSL Bridging
This configura on is for organiza ons that do not have a trusted network between the proxy and the RESTful API servers.
Important: The VIP on the proxy should be accessible from the internet and all networks on site.
Protocol Source Des na on Port Usage
HTTPS Proxy Res ul API Services Configurable This will respond to API
Default: 443 requests.
HTTPS Any Client Proxy 443 This is the connec on clients
make to access the API
services proxied by the load
balancer/proxy.
HTTPS Proxy Res ul Applica on Configurable This will respond to
Services server(s) Default: 8888 Applica on requests.
HTTPS Any Client Proxy 443 This is the connec on clients
make to access the Applica on
services proxied by the load
balancer/proxy.
Proxy - TCP Proxy
This configura on is for organiza ons that will be configuring real- me APIs that require direct access to the MEDITECH
Expanse database. This should be configured using DNS (see DNS Entries).
Protocol Source Des na on Port Usage
TCP API Server(s) TCP Proxy Configurable This is used by the API
Service(s) Server(s) to handle API
requests that require direct
access to the MEDITECH
Expanse database.
MEDITECH 2020 - 14Inbound Traffic (Trusted Clients)
These are connec ons from MEDITECH applica ons running on your network. These connec ons MUST NOT be
internet-accessible. They must share the same IP/VIP.
Protocol Source Des na on Port Usage
HTTP over TCP Proxy Res ul API 24431 Serves web pages to the
server(s) MEDITECH pla orms.
Note: this connec on is no
longer needed a er IOPS is
updated to v1.4.0 or above.
HTTP over TCP Trusted Client Proxy 24431 This is the connec on clients
make to access the webpages
proxied by the load
balancer/proxy.
Note: this connec on is no
longer needed a er IOPS is
updated to v1.4.0 or above.
HTTP over TCP RESTful API RESTful API Configurable This is used to communicate
Server(s) Server(s) Default: 24387 with the IOPS Monitor service
to obtain environmental
se ngs.
Note: this connec on is no
longer needed a er IOPS is
updated to v1.5.0 or above.
MEDITECH 2020 - 15Load Balancer/Proxy Configuration
MEDITECH cannot provide step-by-step instruc ons for configuring your load balancer or proxy. This is because every
vendor is different and uses different names to reference the same thing.
There are two suggested configura ons:
1. SSL Termina on - this is when the connec on to the appliance is encrypted with SSL but the connec on from the
appliance to the RESTful services is not encrypted.
2. SSL Bridging - this is when the connec on to the appliance is encrypted with SSL and the connec on from the
appliance to the RESTful services is encrypted, some mes with a different cer ficate and TLS configura on. SSL
Bridging would indicate an End to End Encryp on (E2EE).
SSL Passthrough (where the appliance operates at the TCP level instead of at the SSL level) is not a suggested
configura on as it directly exposes the SSL implementa on included in the RESTful services to the Internet. The danger,
as outlined above, is that MEDITECH will be unable to patch and deliver fixes for SSL vulnerabili es quickly enough.
Header Insertion
In both suggested configura ons, the appliance should be configured to add the "X-Forwarded-For" header to the
request before proxying to the RESTful services. The header should be populated with the original client's IP. This allows
the RESTful services to log the IP of the origin of the request. Without this header, all requests would appear to be from
the appliance's IP.
In an SSL Termina on configura on, an addi onal header is needed. "X-Forwarded-Proto" needs to be added to the
request. It must have the sta c value of "h ps", without the quotes.
These headers allow the RESTful services to handle requests appropriately and helps in securing the connec on.
You can read more about these headers on Mozilla's web-site:
● X-Forwarded-For
● X-Forwarded-Proto
IPs and Ports
A single IP, some mes called a VIP, can be used for all environments. If using the same VIP for both API and Applica on
environments, the load balancer will need to be configured to look at the Host header of the HTTP requests to route API
requests to the API service port and Applica on requests to the Applica on service port. Our sugges on, however, is to
use one VIP for all API environments and one for all Applica on environments.
Please note: all ports listed below may be different in your configura on due to differences in your environment and
network. Please consult your TECH or Applica on specialist to determine if the default ports are being used.
In an SSL Bridging configura on, the appliance should proxy HTTPS/443 -> HTTPS/443 for the API VIP and HTTPS/443 to
HTTPS/8888 for the Applica on VIP.
In an SSL Termina on configura on, the appliance should proxy HTTPS/443 -> HTTP/80 for the API VIP and HTTPS/443 to
HTTP/8081 for the Applica on VIP.
It is not suggested to configure the appliance to proxy HTTP/80 -> HTTP/80. HTTP/80 is never used by a func oning client
and there is no need to allow them to connect on this port. The site may, op onally, configure their appliance to issue a
redirect from HTTP/80 to HTTPS/443. If HTTP/80 is proxied, the services will issue a redirect to HTTPS/443 itself.
When configuring the TCP Proxy Service, the appliance should proxy TCP/6000 -> TCP/6000 for the TCP Proxy Service
server IPs.
MEDITECH 2020 - 16Important: ports used by the services in your installa on may be different than the examples listed above. Please refer to
the TECH task tracking the delivery of the RestAPI Infrastructure.
Health Check
The RESTful services support a standard HTTP health check:
HEAD / HTTP/1.1
If the service is func oning appropriately, it will return a "200 OK".
It is not required to configure a health check but doing so will allow the appliance to detect and react to outages be er.
Trusted Proxies
The RESTful service’s trusted proxies MUST be configured to include the load balancer’s IP or IP range. Failure to do so
will cause incorrect informa on to be recorded in the RESTful service audit logs and devices will be iden fied incorrectly
when evalua ng quotas and lockouts. This, in turn, can lead to the system becoming unusable.
Note: if there are mul ple load balancers and/or proxies used, all of their IPs must be listed in Trusted Proxies.
Security
The RESTful API Infrastructure has mul ple layers of security. This document aims to describe the security model.
The Flow
In order to put the layers into context, it is necessary to describe the flow of a typical applica on.
Authoriza on
1. The applica on redirects the user to our authoriza on endpoint.
2. The authoriza on endpoint does one of two things:
a. Display the available authen ca on realms (if there is more than one), in which case it redirects the user
to the iden ty provider a er a realm is selected.
b. Redirect the user to the only iden ty provider if there is a single realm.
3. The authen ca on completes2 and the user is redirected back to a special endpoint on our service that
processes the authen ca on informa on. This includes a step where the service (not the client) contacts the
provider to validate the informa on, thereby mi ga ng a MITM a ack.
4. The infrastructure evaluates whether or not the applica on and user combina on has access to the requested
scopes. It does this by confirming:
a. All scopes in the request are valid.
b. The user passes the ACLs for all scopes.
c. The applica on passes the ACLS for all scopes.
5. An authoriza on code is generated and the user is redirected back to a registered endpoint belonging to the
applica on.
6. The applica on makes a request to the RESTful API Infrastructure to trade the authoriza on code for an access
token. The connec on is authen cated by the applica on providing its OAuth2 client ID and secret.
7. The applica on can now make requests to APIs on the behalf of the user.
API Invoca on
1. The applica on makes an HTTPS request to the RESTful API Infrastructure and includes the access token.
2. The infrastructure determines if the scopes granted to the token during authoriza on cover the API being
invoked. If not, an error is returned.
3. The infrastructure then determines if there are any quota lockouts — and if there are, returns an error.
2
What happens on the iden ty provider is outside the scope of this document.
MEDITECH 2020 - 174. A second level of authoriza on based on resource ownership is performed using the iden ty informa on ed to
the token.
a. For example, Pa ent A is considered to be the owner of their own pa ent resource. Only the pa ent (or
others specifically granted access such as providers or healthcare proxies) can read the medical record
for that pa ent. This does not mean the pa ent can do everything with their record, but only what a
pa ent is allowed to do — in this example, obtain a copy of it.
5. The invoca on — whether allowed, denied, or failed due to error — is logged in our audit table.
Layers
Firewall
The firewall protects against many threats such as DoS. In some environments, a firewall may be used to restrict access
to the APIs over the internet to a set of well-defined sources.
Load Balancer
The load balancer performs mul ple func ons in this configura on. It returns an error if the request is malformed (i.e.,
not a valid HTTP request) and is used to offload SSL/TLS, allowing organiza ons to manage their cer ficates in a central
loca on (instead of propaga ng cer ficates to mul tudes of servers). It also makes se ng SSL/TLS parameters, such as
minimum protocol version and cipher suites, easier without the need to update or reconfigure the RESTful API
Infrastructure.
One addi onal feature is the ability to scale out the RESTful API Infrastructure to handle more requests or to increase
performance by balancing requests across the nodes in an installa on.
TLS/SSL
All requests to the RESTful API Infrastructure must be over HTTPS and must be protected with a cer ficate from a trusted
authority (not a self-signed cer ficate).
Applica on Registra on
In order for an applica on to be able to obtain a token, they must first be added to the configura on by an administrator.
This generates a client ID and client secret, which is then used by that applica on when obtaining tokens. The ID and
secret do NOT grant access to APIs and are only used during authoriza on. Please consult the Interoperability group to
onboard applica ons.
Important: The client secret should only be transmi ed and stored securely. DO NOT send it via email if at all possible.
User Login
MEDITECH requires the use of an Iden ty Provider (IdP) to authen cate pa ents (or their representa ves) and providers.
The IdP your organiza on deploys must support the OpenID Connect or SAML 2.0 protocol. Alterna vely, support for
using your MEDITECH Pa ent Portal as an IdP has been added - please consult your Interoperability specialist to
determine if you meet the minimum so ware requirements for this op on. Before selec ng an Other Vendor IdP for
your organiza on, please work with MEDITECH so we can confirm its compa bility with RESTful API Infrastructure.
Note: The most immediate use case for the RESTful API Infrastructure and IOPS is to meet MU3 requirements, which will
only use the IdP to authen cate pa ents. Future use cases will include allowing providers to use applica ons to access
data. At that me, an IdP will need to be able to authen cate providers. This may mean a single IdP or mul ple IdPs
depending on your needs.
OAuth2
The OAuth2 standard is used to secure the APIs from unauthorized access.
MEDITECH 2020 - 18Scope ACLs
Scopes have their own set of ACLs which prevent applica ons or users from obtaining a token with those scopes. Some
scopes have a default ACL that denies token genera on (i.e., whitelis ng), while most other scopes have a default ACL
that allows it (i.e., blacklis ng). Which method MEDITECH chooses for a scope depends on the intended usage of the
scope.
The evalua on of whether or not a token may be generated with the requested scopes is done during the Authoriza on
stage a er user authen ca on. This is because ACLs can also be used to deny/allow based on the authen cated user in
addi on to the authen cated applica on.
The Admin Panel can be used to view and configure these ACLs.
Quotas
Quotas allow a site to limit the number of requests made within a period of me. This helps alleviate strain on the
MEDITECH database if an applica on is misbehaving. It also acts as another layer of security by temporarily locking out
an applica on or user from accessing APIs.
Audi ng
All requests to the RESTful API Infrastructure are audited. This enables iden fying what data was accessed by bad actors,
should a breach of a user's or applica on's creden als occur. It could also be used by analy cs tools to report on
suspicious ac vity. We are s ll developing the tools that can be used to review the audit entries.
Terms
Application Server/Service
The RestAPI Infrastructure listens on a second port which allows it to easily serve up integrated applica ons. These are
web applica ons created by MEDITECH's development teams and includes the Admin Panel, which is used to configure
the infrastructure.
API Server/Service
The primary purpose of the RestAPI Infrastructure is to expose APIs to trusted/authen cated clients.
This is also typically used to reference the physical server(s) or VM(s) on which the RestAPI Infrastructure is running.
ACL
Access Control List: A mechanism of defining who and what can access which resources.
Blacklisting
A way of gran ng access where access is allowed, unless an excep on is made. To put it into an analogy: "Anyone may
use the coffee pot except children under 12." This is the opposite of whitelis ng.
Client ID
This is the unique iden fier given to an OAuth Client, otherwise known as an applica on or service. It can be thought of
as the username for an applica on.
Client Secret
This is a secret value given to an OAuth Client. When paired with the Client ID, it allows an applica on to authen cate as
part of the authoriza on flow.
MEDITECH 2020 - 19DoS
Denial of Service: An a ack against a server that leads to clients being unable to connect or receive responses due to
exhaus ng the resources of the server (CPU, IO throughput) or network.
End to End Encryption (E2EE)
Would indicate a secure connec on between both endpoints of the communica on, normally using an asymmetric
encryp on protocol. It is a way to prevent a man in the middle a ack.
Environment
Environments come in two flavors:
1. API - this defines the hostname that links to a specific MRI or HIM database
2. Applica on - this defines the hostname that links an applica on to a specific API environment, thereby allowing
that applica on to query the specific MRI or HIM database
Environments are one-for-one with the DNS entries defined by the site and allow the RestAPI Infrastructure to
differen ate between API traffic (and which MRI/HIM database that API should resolve to) and Applica on traffic (and
which API environment it uses).
MITM
A man-in-the-middle a ack is one where a client's requests are sent to an insecure server that acts as a proxy to the real
server.
Quota
A quota is a way of limi ng the number of requests that can be made within a period of me. Quotas should be based on
real-world applica on workflows.
Resource
A resource is any file or uniquely iden fiable data, such as a pa ent record or an order.
Scope
A scope defines a set of related APIs.
TCP Proxy Service
A TCP Proxy Service is connected to by an API Service when processing API whose data originates in the MEDITECH
Expanse Pla orm. This service is responsible for maintaining a pool of M-AT Magic Console processes and proxying TCP
connec ons.
Token
A token is a string used to provide iden ty without exposing usernames and passwords to applica ons.
Whitelisting
A way of gran ng access where access is denied, unless an excep on is made. To put it into an analogy: "No one may
access the server room except network engineering." This is the opposite of blacklis ng.
MEDITECH 2020 - 20Installation Validation Guide
This valida on guide is meant to assist both the IT staff at site and MEDITECH staff iden fy connec vity and/or
configura on issues.
Important Note
"HOSTNAME" (referenced below) is the DNS record the site has configured to be used with the RESTful API and IOPS
services. This is not the name of a server. Please refer to the configura on task for informa on on the hostnames —
there may be many.
Check DNS
On Network
1. Log on to any device on network.
2. Launch the command prompt.
3. Execute "nslookup HOSTNAME." (See Important Note above.)
4. If an error is reported, internal DNS is not configured properly and must be resolved by site's network engineers.
5. Confirm the HOSTNAME resolves to the VIP on the load balancer. If it does not, DNS is not configured properly
and must be resolved by site's network engineers.
6. Repeat these steps for all hostnames/environments.
Off Site's Network
1. Load this link in your browser: h ps://mxtoolbox.com/DNSLookup.aspx.
2. Enter in the HOSTNAME as you did for step #3 above, and click the orange "DNS Lookup" bu on.
3. If an error is reported, external DNS is not configured properly and must be resolved by site's network engineers.
4. Confirm the IP is NAT'd to the VIP on the load balancer. If the resolved address is incorrect, DNS is not configured
properly and must be resolved by site’s network engineers.
5. Repeat these steps for all hostnames/environments.
Check Services
1. Log on to the API server.
2. In the Start menu, select Control Panel.
3. From the Control Panel window, select Administra ve Tools.
4. Launch the "services" and verify the following services are installed and in a "Running" status. Note: The "(xxx)"
below in each service name is a unique iden fier for the installa on.
a. MEDITECH IOPS Monitor (xxx)
i. Note: this connec on is no longer needed a er IOPS is updated to v1.5.0 or above.
b. MEDITECH IOPS MSF (xxx)
c. MEDITECH Rest API Node Service (xxx)
d. MEDITECH Rest API Redis Service (xxx)
"MEDITECH IOPS Monitor (xxx)" will only be deployed on one of the API servers.
5. Open the browser.
6. Navigate to h p://localhost.
7. If the browser reports "Connec on Reset," "Connec on Aborted," or "Connec on Timed out," then the RESTful
API services are not working correctly.
8. If IOPS services version is < 1.4.0 (ex. 1.3.0):
a. Navigate to h p://localhost:24431.
b. If the browser reports "Connec on Reset," "Connec on Aborted," or "Connec on Timed out," then the
IOPS services are not working correctly.
9. If there are mul ple API servers, repeat steps 1-9 for each one.
10. Log on to the server with the IOPS File-Explorer service installed.
11. In the Start menu, select Control Panel.
12. From the Control Panel window, select Administra ve Tools.
MEDITECH 2020 - 2113. Launch the "services" and verify the "MEDITECH IOPS Explorer" service is installed and in a "Running" status.
Check Connectivity
Many of the steps below use the browser to confirm connec vity. Due to differences in how browsers display the data
returned by the RESTful API Infrastructure, you may not actually see the page indicated in the instruc ons. We suggest
using Chrome or Postman to verify connec vity as both of these display the Infrastructure's error messages instead of
displaying their own.
On Network
RESTful API Services
1. From any device on-network, open the browser.
2. Navigate to h ps://HOSTNAME.
3. If HOSTNAME is for an API environment, you should see this displayed in the page:
{"resource":"v1/resource/error/_version/1/","detail":"Not Found"} or
{"resource":"v1/resource/error/_version/1/","detail":"could not route
request"}
i. If you do not, then connec vity is blocked from that device, and the site will need to review their
firewall and load balancer logs.
ii. IE will not display the response. Instead, it will display a generic error page that the resource was
not found or there was a bad request. You can confirm the content of the response by opening
the developer tools, naviga ng to the Network tab and reviewing the Response body for the
request.
4. If HOSTNAME is for Applica on environments, you should either: be redirected to the
h ps://HOSTNAME/home/ page and shown a list of available applica ons, or, if defined for the specific
environment, defaulted into the applica on defined.
i. If you do not, then connec vity is blocked from that device, and the site will need to review their
firewall and load balancer logs.
AUC Viewer & CCDA Valida on Report (required for v1.3.x and less IOPS installa ons)
1. From any device on-network, open the browser.
2. Navigate to h p://HOSTNAME:24431.
3. If the browser reports anything but a 404, then connec vity is blocked from that device, and the site will
need to review their firewall and load balancer logs.
Mul -Service Framework (MSF) Service
1. From the ISWEB server, open the browser.
2. Navigate to h p://{monitorHost:port} where "monitorHost" is the FQDN of the server and "port" is the
port that the Monitor service is listening on.
a. This is required for v1.4.x and less IOPS installa ons only. For v1.5.x and above skip to step 5.
3. You should see this displayed in the page:
{"connection": "success"}
4. If you do not, then connec vity is blocked from that device, and the site will need to review their firewall
logs.
5. Navigate to h p://{explorerHost:port} where "explorerHost" is the FQDN of the server and "port" is the
port that the File-Explorer service is listening on.
6. You should see this displayed in the page:
{"connection": "success"}
7. If you do not, then connec vity is blocked from that device, and the site will need to review their firewall
logs.
8. Repeat steps 5-7 to all File-Explorer services.
9. Navigate to h p://{pla ormHost:port} where "pla ormHost" is the FQDN of the server and "port" is the
port that the Pla orm service is listening on.
MEDITECH 2020 - 2210. If the browser reports anything but a 403 or 404, then connec vity is blocked from that device, and the
site will need to review their firewall logs.
11. Repeat steps 9-10 to all Pla orm services.
12. Repeat steps 1-11 on all ISWEB servers.
File-Explorer Service (required for v1.4.x and less IOPS installa ons)
1. From the server with File-Explorer Service installed, open the browser.
2. Navigate to h p://{monitorHost:port} where "monitorHost" is the FQDN of the server and "port" is the
port that the Monitor service is listening on.
3. You should see this displayed in the page:
{"connection": "success"}
4. If you do not, then connec vity is blocked from that device, and the site will need to review their firewall
logs.
5. Repeat steps 1-4 on all servers with the File-Explorer service installed.
Off Network
RESTful API Services
1. From any device off-network, open the browser.
2. Navigate to h ps://HOSTNAME.
3. If HOSTNAME is for an API environment, you should see this displayed in the page:
{"resource":"v1/resource/error/_version/1/","detail":"Bad Request"}
i. If you do not, then connec vity is blocked from that device, and the site will need to review their
firewall and load balancer logs.
4. If HOSTNAME is for Applica on environments, you should either: be redirected to the
h ps://HOSTNAME/home/ page and shown a list of available applica ons, or, if defined for the specific
environment, defaulted into the applica on defined.
i. If you do not, then connec vity is blocked from that device, and the site will need to review their
firewall and load balancer logs.
ii. If the Applica ons should only be available on network, you should not be able to connect (the
browser should show "Connec on Timed Out" or "Connec on Refused").
AUC Viewer & CCDA Valida on Report (required for v1.3.x and less IOPS installa ons)
1. From any device off-network, open the browser.
2. Navigate to h p://HOSTNAME:24431.
3. The browser should report that the connec on could not be made, failed, or was rejected. If you get a
response from the server, like a 404, then the applica on has been exposed to the internet. The site
must modify their firewall to disallow access on port 24431 from the Internet.
MEDITECH 2020 - 23Change Log
March 10, 2021
● Updated DNS Entries sec on for TCP Proxy setup to replace men on of load balancer VIP with TCP Proxy IPs.
● Updated various other references to TCP Proxy setup with the updated DNS guidance.
July 10, 2020
● Added link to Security documenta on for Redis configura on.
● Added more informa on to "SSL Bridging" defini on.
May 26, 2020
● Added note on configuring trusted proxies in Load Balancer/Proxy Configura on.
January 10, 2020
● Replace NDSC vendor references with Clinical Decision Support Mechanism (CDSM) for appropriate use criteria
(AUC).
● Updated and added configura on diagrams.
● Added documenta on regarding TCP Proxy Service.
July 9, 2019
● Clarified documenta on by changing "Database" to "Database Server".
May 8, 2019
● Added a note on upda ng max_allowed_packet for older MariaDB/MySQL versions.
January 31, 2019
● Updated Security Layers User Login sec on to indicate support for SAML 2.0 Idp and MEDITECH Pa ent Portal
Idp.
December 10, 2018
● Updated Valida on Guide sec on to indicate change in API server (≥1.5.0) response when naviga ng to the root
URL from a browser.
December 7, 2018
● Updated Database sec on to indicate incompa bility with MySQL 8.0.4 or above.
October 19, 2018
● Updated ports under "Load Balancer/Proxy Configura on" to be in line with connec vity tables earlier in this
document.
August 20, 2018
● Updated connec vity tables for v1.5.0 release of Interoperability Services.
● Removed "PostgreSQL" from documenta on.
MEDITECH 2020 - 24You can also read
