SMART on FHIR apps for Information exchange (Apache config.)

I reached out to Gary Monger yesterday and asked him how he configured Apache for his SMART on FHIR demo?
See https://learning.intersystems.com/mod/page/view.php?id=2948.
Gary's response was for me to post my question on the Developer Community forum - so that other people can benefit from the answer.

This is what I asked Gary:

I'm after turning a local Health Share instance on my laptop into a SMART on FHIR server.

The *recording about doing all of this is excellent, however, I could do with some instructions on how you configured the Apache web server before running the Cache scripts.
*https://learning.intersystems.com/mod/page/view.php?id=2948

Therefore, before I put lots of effort into trying to figure out how to configure the web services before running the COS scripts - could you please give me any hints or tips before I attempt the install.

I'm running this version of HS:

Cache for Windows (x86-64) 2017.2.1 (Build 801U) Wed Dec 6 2017 09:07:51 EST [HealthShare Modules:Core:16.0.7241 + Linkage Engine:16.0.7241 + Patient Index:16.0.7241 + Provider Directory:15.0.7241 + Clinical Viewer:16.0.7241 + Active Analytics:16.0.7241]

I have already run the HS demo script:

http://localhost:57774/csp/docbook/DocBook.UI.Page.cls?KEY=HESUP_app_dem...

ZN "HSLIB"
do ##class(HS.Util.Installer).InstallDemo()

Plus the script that sets up the FHIR production:

zn "HSLIB"
do ##class(HS.Util.Installer).InstallFHIRServer("FHIRSERVER")

However, because of the unknowns as far as configuring the SSL stuff in Apache - I've held off running the rest of the COS code that you ran to install the rest of the software.

I have a Oracle Virtual Box VM environment that I can run openssl commands in - and my plan is to run these openssl commands to create the certs.
I've run these openssl commands in the past - and I'm hoping the openssl commands are similar to what you ran to configure your laptop before doing the recording.

openssl genrsa -out key.pem​
openssl req -new -key key.pem -out csr.pem
openssl x509 -req -days 9999 -in csr.pem -signkey key.pem -out cert.pem

I've also been told by that the server name in the certificate needs to match the server name - otherwise it won't work!

If you wouldn't mind sending me a copy of your stand alone csp app source code that you demonstrated in your recording - then that would be great as well.

Can you also tell me if Cache can be configured to support SMART backend-services?
See http://docs.smarthealthit.org/authorization/backend-services/.

Many Thanks,
-- Paul.

  • 0
  • 0
  • 319
  • 3
  • 1

Answers

There are many ways to setup apache, and what works for your situation may vary.  My used a single instance of HealthShare, and two SMART applications that were hosted locally and served via CSP applications defined on my HealthShare instance.  I was running on Windows.

 

I used binaries from ApacheHaus,

Download here - https://www.apachehaus.com/cgi-bin/download.plx .

Unzip and read the readme. 

Download the c++ runtime https://www.microsoft.com/en-us/download/details.aspx?id=49984.

Install, restart

Test apache installation http://localhost

 

Generate certificates.  I did this from HealthShare, but you can do it with openSSL, or other tools.

Configure the httpd.conf – change the server root, load the CSP modules, define the csp alias, create location entries, and create directory entries.  I’ll attach the conf file I used.

Configure the httpd-ahssl.conf – load webserver cert and key, and CA cert.  I’ll attached the file I used.

Configure CSP.ini to connect to HealthShare instance, need to make sure superserver port is correct, and username and password for the CSPService.  I just pasted in the encoded string from CSP.ini from the private webserver configuration

 

Run apache as a service. From bin directory in Apache:  httpd.exe -k install [-n “ServiceName”]

 I recommend starting without SSL, so comment out the #include of httpd-ahssl.conf in the httpd.conf file. Test, then put the SSL back in and test.

 

For the SMART apps:

I setup /csp applications one for each application.  You may want to do something different depending on your situation and the applications you are using.

Test that the web server routes to the apps.

 

You do need to have the common name in the cert match the host name.

My demo used SMART applications that I downloaded from SMARTHealthIT.org.  I created csp application definitions to launch the SMART apps I had downloaded.

I guess Cache could fill a few different roles in back end services.  I'll get back to you on that.

 

I dont see a way to attach a file, so will paste in text from the conf files

#

This is the main Apache HTTP server configuration file. It contains the

configuration directives that give the server its instructions.

See <URL:http://httpd.apache.org/docs/2.4/> for detailed information.

Define SRVROOT "E:/Apache24"
ServerRoot "${SRVROOT}"

#

Listen: Allows you to bind Apache to specific IP addresses and/or

ports, instead of the default. See also the

directive.

#

Change this to Listen on specific IP addresses as shown below to

prevent Apache from glomming onto all bound IP addresses.

#

Listen 12.34.56.78:80

Listen 80

#

Dynamic Shared Object (DSO) Support

#

To be able to use the functionality of a module which was built as a DSO you

have to place corresponding `LoadModule' lines at this location so the

directives contained in it are actually available before they are used.

Statically compiled modules (those listed by `httpd -l') do not need

to be loaded here.

#

Example:

LoadModule foo_module modules/mod_foo.so

#
LoadModule actions_module modules/mod_actions.so
LoadModule alias_module modules/mod_alias.so
LoadModule allowmethods_module modules/mod_allowmethods.so
LoadModule asis_module modules/mod_asis.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authz_core_module modules/mod_authz_core.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule cgi_module modules/mod_cgi.so
LoadModule dir_module modules/mod_dir.so
LoadModule env_module modules/mod_env.so
LoadModule include_module modules/mod_include.so
LoadModule info_module modules/mod_info.so
LoadModule isapi_module modules/mod_isapi.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule mime_module modules/mod_mime.so
LoadModule negotiation_module modules/mod_negotiation.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule status_module modules/mod_status.so

'Main' server configuration

#

ServerAdmin: Your address, where problems with the server should be

e-mailed. This address appears on some server-generated pages, such

as error documents. e.g. admin@your-domain.com

#
ServerAdmin admin@example.com

#

ServerName gives the name and port that the server uses to identify itself.

This can often be determined automatically, but we recommend you specify

it explicitly to prevent problems during startup.

#

If your host doesn't have a registered DNS name, enter its IP address here.

#
ServerName localhost:80

Deny access to the entirety of your server's filesystem. You must

explicitly permit access to web content directories in other

blocks below.

#

AllowOverride none
Require all granted

#

Note that from this point forward you must specifically allow

particular features to be enabled - so if something's not working as

you might expect, make sure that you have specifically enabled it

below.

#

#

DocumentRoot "${SRVROOT}/htdocs"


Options Indexes FollowSymLinks
AllowOverride None
Require all granted

UseCanonicalName Off

#

DirectoryIndex: sets the file that Apache will serve if a directory

is requested.

#

DirectoryIndex index.html

#

The following lines prevent .htaccess and .htpasswd files from being

viewed by Web clients.

#

Require all denied

#

ErrorLog: The location of the error log file.

If you do not specify an ErrorLog directive within a

container, error messages relating to that virtual host will be

logged here. If you do define an error logfile for a

container, that host's errors will be logged there and not here.

#
ErrorLog "logs/error.log"

#

LogLevel: Control the number of messages logged to the error_log.

Possible values include: debug, info, notice, warn, error, crit,

alert, emerg.

#
LogLevel warn


#
# The following directives define some format nicknames for use with
# a CustomLog directive (see below).
#
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common

<IfModule logio_module>
  # You need to enable mod_logio.c to use %I and %O
  LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
</IfModule>

#
# The location and format of the access logfile (Common Logfile Format).
# If you do not define any access logfiles within a <VirtualHost>
# container, they will be logged here.  Contrariwise, if you *do*
# define per-<VirtualHost> access logfiles, transactions will be
# logged therein and *not* in this file.
#
CustomLog "logs/access.log" common

#
# If you prefer a logfile with access, agent, and referer information
# (Combined Logfile Format) you can use the following directive.
#
#CustomLog "logs/access.log" combined


AllowOverride None
Options None
Require all granted


#
# TypesConfig points to the file containing the list of mappings from
# filename extension to MIME-type.
#
TypesConfig conf/mime.types

#
# AddType allows you to add to or override the MIME configuration
# file specified in TypesConfig for specific file types.
#
#AddType application/x-gzip .tgz
#
# AddEncoding allows you to have certain browsers uncompress
# information on the fly. Note: Not all browsers support this.
#
#AddEncoding x-compress .Z
#AddEncoding x-gzip .gz .tgz
#
# If the AddEncoding directives above are commented-out, then you
# probably should define those extensions to indicate media types:
#
AddType application/x-compress .Z
AddType application/x-gzip .gz .tgz

Supplemental configuration

#

The configuration files in the conf/extra/ directory can be

included to add extra features or to modify the default configuration of

the server, or you may simply copy their contents here and change as

necessary.

Server-pool management (MPM specific)

Include conf/extra/httpd-mpm.conf

Multi-language error messages

Include conf/extra/httpd-multilang-errordoc.conf

Fancy directory listings

Include conf/extra/httpd-autoindex.conf

Language settings

Include conf/extra/httpd-languages.conf

User home directories

Include conf/extra/httpd-userdir.conf

Real-time info on requests and configuration

Include conf/extra/httpd-info.conf

Virtual hosts

Include conf/extra/httpd-vhosts.conf

Local access to the Apache HTTP Server Manual

Include conf/extra/httpd-manual.conf

Distributed authoring and versioning (WebDAV)

Include conf/extra/httpd-dav.conf

Various default settings

Include conf/extra/httpd-default.conf

Configure mod_proxy_html to understand HTML4/XHTML1


Include conf/extra/httpd-proxy-html.conf

Secure (SSL/TLS) connections

Note: The following must must be present to support

starting without SSL on platforms with no /dev/random equivalent

but a statically compiled-in mod_ssl.

#

Include conf/extra/httpd-ssl.conf

Include conf/extra/httpd-ahssl.conf
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin


ProtocolsHonorOrder On
Protocols h2 h2c http/1.1

------------------------------------------------------

#
LoadModule csp_module_sa "E:/InterSystems/CSPGateway/CSPa24.dll"
LoadModule cspsys_module_sa "E:/Intersystems/CSPGateway/CSPa24Sys.dll"

LoadModule cspsys_module_sa "E:/InterSystems/HSGS/CSP/bin/CSPa24Sys.dll"

ServerTokens Prod

Alias /csp/ "E:/InterSystems/HSGS/CSP/"

SetHandler csp-handler-sa


SetHandler csp-handler-sa


CSP On
SetHandler csp-handler-sa


CSP On
SetHandler csp-handler-sa


CSPFileTypes csp cls zen cxw
AllowOverride None
Options MultiViews FollowSymLinks ExecCGI
Require all granted

Require all denied

#

SSL Demo Configuration for Apache Haus Distribution

FileName: conf/extras/mod_ahssl.conf

#

This is the Apache server configuration file providing SNI support.

It contains the configuration directives to instruct the server how to

serve pages over an https connection. For detailed information about these

directives see <URL:http://httpd.apache.org/docs/2.4/mod/mod_ssl.html>

Do NOT simply read the instructions in here without understanding

what they do. They're here only as hints or reminders. If you are unsure

consult the online docs. You have been warned.

#

Required modules: mod_log_config, mod_setenvif, mod_ssl,

socache_shmcb_module (for default value of SSLSessionCache)

Listen 443 https

#

SSL Global Context

#

All SSL configuration in this context applies both to

the main server and all SSL-enabled virtual hosts.

#

SSL Protocols:

List the protocols that the client is permitted to negotiate.

See the mod_ssl documentation for a complete list.

SSLProtocol -all +TLSv1 +TLSv1.1 +TLSv1.2

SSL Cipher Suite:

List the ciphers that the client is permitted to negotiate.

See the mod_ssl documentation for a complete list.

SSLCipherSuite ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:!RC4:!LOW:!MD5:!aNULL:!eNULL:!3DES:!EXP:!PSK:!SRP:!DSS

SSL Honer Cipher Suite Order:

Forces the order of allowed cipher suites to the order above.

See the mod_ssl documentation for a complete list.

SSLHonorCipherOrder On

Pass Phrase Dialog:

Configure the pass phrase gathering process.

The filtering dialog program (`builtin' is a internal

terminal dialog) has to provide the pass phrase on stdout.

SSLPassPhraseDialog builtin

Inter-Process Session Cache:

Configure the SSL Session Cache: First the mechanism

to use and second the expiring timeout (in seconds).

SSLSessionCache "dbm:${SRVROOT}/logs/ssl_scache"

SSLSessionCache "shmcb:${SRVROOT}/logs/ssl_scache(512000)"
SSLSessionCacheTimeout 300

#

Some MIME-types for downloading Certificates and CRLs

#
AddType application/x-x509-ca-cert .crt
AddType application/x-pkcs7-crl .crl

SSL Engine Options:

Set various options for the SSL engine.

o FakeBasicAuth:

Translate the client X.509 into a Basic Authorisation. This means that

the standard Auth/DBMAuth methods can be used for access control. The

user name is the `one line' version of the client's X.509 certificate.

Note that no password is obtained from the user. Every entry in the user

file needs this password: `xxj31ZMTZzkVA'.

o ExportCertData:

This exports two additional environment variables: SSL_CLIENT_CERT and

SSL_SERVER_CERT. These contain the PEM-encoded certificates of the

server (always existing) and the client (only existing when client

authentication is used). This can be used to import the certificates

into CGI scripts.

o StdEnvVars:

This exports the standard SSL/TLS related `SSL_*' environment variables.

Per default this exportation is switched off for performance reasons,

because the extraction step is an expensive operation and is usually

useless for serving static content. So one usually enables the

exportation for CGI and SSI requests only.

o StrictRequire:

This denies access when "SSLRequireSSL" or "SSLRequire" applied even

under a "Satisfy any" situation, i.e. when it applies access is denied

and no other module can change it.

o OptRenegotiate:

This enables optimized SSL connection renegotiation handling when SSL

directives are used in per-directory context.

SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire


SSLOptions +StdEnvVars


SSLOptions +StdEnvVars

SSL Protocol Adjustments:

The safe and default but still SSL/TLS standard compliant shutdown

approach is that mod_ssl sends the close notify alert but doesn't wait for

the close notify alert from client. When you need a different shutdown

approach you can use one of the following variables:

o ssl-unclean-shutdown:

This forces an unclean shutdown when the connection is closed, i.e. no

SSL close notify alert is sent or allowed to be received. This violates

the SSL/TLS standard but is needed for some brain-dead browsers. Use

this when you receive I/O errors because of the standard approach where

mod_ssl sends the close notify alert.

o ssl-accurate-shutdown:

This forces an accurate shutdown when the connection is closed, i.e. a

SSL close notify alert is send and mod_ssl waits for the close notify

alert of the client. This is 100% SSL/TLS standard compliant, but in

practice often causes hanging connections with brain-dead browsers. Use

this only for browsers where you know that their SSL implementation

works correctly.

Notice: Most problems of broken clients are also related to the HTTP

keep-alive facility, so you usually additionally want to disable

keep-alive for those clients, too. Use variable "nokeepalive" for this.

Similarly, one has to force some clients to use HTTP/1.0 to workaround

their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and

"force-response-1.0" for this.

BrowserMatch "MSIE [2-5]" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

Per-Server Logging:

The home of a custom SSL log file. Use this when you want a

compact non-error SSL logfile on a virtual host basis.

CustomLog "${SRVROOT}/logs/ssl_request.log" \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" env=HTTPS

#

SSL Virtual Host Context

#


SSLEngine on
ServerName localhost:443
#SSLCertificateFile "${SRVROOT}/conf/ssl/server.crt"
#SSLCertificateKeyFile "${SRVROOT}/conf/ssl/server.key"
SSLCertificateFile "E:/certs/USVMDEMO-GS-Web.cer"
SSLCertificateKeyFile "E:/certs/USVMDEMO-GS-Web.key"
SSLCACertificatePath "E:/certs"
SSLCACertificateFile "E:/certs/ISCDemoCA.cer"
DocumentRoot "${SRVROOT}/htdocs"

DocumentRoot access handled globally in httpd.conf

CustomLog "${SRVROOT}/logs/ssl_request.log" \
      "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
<Directory "${SRVROOT}/htdocs">
    Options Indexes Includes FollowSymLinks
    AllowOverride AuthConfig Limit FileInfo
Require all granted
</Directory>

SSLEngine on

ServerName localhost:443

SSLCertificateFile "${SRVROOT}/conf/ssl/server.crt"

SSLCertificateKeyFile "${SRVROOT}/conf/ssl/server.key"

DocumentRoot "${SRVROOT}/htdocs"

DocumentRoot access handled globally in httpd.conf

CustomLog "${SRVROOT}/logs/ssl_request.log" \

"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Options Indexes Includes FollowSymLinks

AllowOverride AuthConfig Limit FileInfo

Require all granted

SSLEngine on

ServerName serverone.tld:443

SSLCertificateFile "${SRVROOT}/conf/ssl/serverone.crt"

SSLCertificateKeyFile "${SRVROOT}/conf/ssl/serverone.key"

DocumentRoot "${SRVROOT}/htdocs"

CustomLog "${SRVROOT}/logs/ssl_request.log" \

"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Options Indexes Includes FollowSymLinks

AllowOverride AuthConfig Limit FileInfo

Require all granted

SSLEngine on

ServerName servertwo.tld:443

SSLCertificateFile "${SRVROOT}/conf/ssl/servertwo.crt"

SSLCertificateKeyFile "${SRVROOT}/conf/ssl/servertwo.key"

DocumentRoot "${SRVROOT}/htdocs"

CustomLog "${SRVROOT}/logs/ssl_request.log" \

"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Options Indexes Includes FollowSymLinks

AllowOverride AuthConfig Limit FileInfo

Require all granted

End SNI Demonstration Config