SMART on FHIR

Reference Guide

Includes:

  Administration Guide

Foundation 22.1
 SMART on FHIR

Documentation Notice
Information in this document is subject to change without notice. The software described in this
document is furnished only under a separate license agreement and may only be used or copied
according to the terms of such agreement. It is against the law to copy the software except as
specifically allowed in the license agreement. This document or accompanying materials may
contain certain information which is confidential information of Hyland Software, Inc. and its
affiliates, and which may be subject to the confidentiality provisions agreed to by you.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the
rights under copyright law, no part of this document may be reproduced, stored in or introduced into
a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying,
recording, or otherwise), or for any purpose, without the express written permission of Hyland
Software, Inc. or one of its affiliates.
Hyland, HxP, OnBase, Alfresco, Nuxeo, and product names are registered and/or unregistered
trademarks of Hyland Software, Inc. and its affiliates in the United States and other countries. All
other trademarks, service marks, trade names and products of other companies are the property of
their respective owners.
© 2022 Hyland Software, Inc. and its affiliates.
The information in this document may contain technology as defined by the Export Administration
Regulations (EAR) and could be subject to the Export Control Laws of the U.S. Government including
for the EAR and trade and economic sanctions maintained by the Office of Foreign Assets Control as
well as the export controls laws of your entity’s local jurisdiction. Transfer of such technology by any
means to a foreign person, whether in the United States or abroad, could require export licensing or
other approval from the U.S. Government and the export authority of your entity’s jurisdiction. You are
responsible for ensuring that you have any required approvals prior to export.
Document Name
SMART on FHIR
Department/Group
Documentation
Revision Number
Foundation 22.1

© 2022 Hyland Software, Inc. and its affiliates i

 SMART on FHIR
Contents

Documentation Notice
Contents
Overview
Introduction..................................................................................................................................................1
Licensing........................................................................................................................................................ 1
Simplified Licensing...........................................................................................................................1
Legacy Licensing............................................................................................................................... 1

Administration Guide

Configuration
Overview....................................................................................................................................................... 3
Hyland IdP Configuration........................................................................................................................ 3
OnBase Configuration...............................................................................................................................3
Creating a SMART on FHIR Application............................................................................................3
Configuring Hyland IdP Settings....................................................................................................... 6
Configuring EHR Authorization Settings.......................................................................................... 9
Deleting a SMART on FHIR Application..........................................................................................13
Application Server Configuration.......................................................................................................13
SMARTonFHIRApplicationID Configuration................................................................................... 14
  accessTokenValidation Configuration........................................................................................... 14

© 2022 Hyland Software, Inc. and its affiliates ii

 Overview

Introduction
The Substitutable Medical Applications, Reusable Technologies (SMART) App Launch Framework
connects third-party applications to Electronic Health Record (EHR) data, which allows apps to
launch from inside or outside the user interface of an EHR system. This framework supports apps
for use by clinicians, patients, and others through a patient portal, or any FHIR system where a user
can give permissions to launch an app.
Essentially, FHIR defines the structure of where data would live and how it should look. EHRs are
responsible for filling that structure with actual patient data. Finally, SMART defines how third-party
apps launch within an EHR, how to determine which EHR user is interacting with the app, and what
patient's data is being accessed.

Note: This also allows Hyperdrive Web clients the ability to launch the Healthcare Web Viewer, FOS,
SAS and Deficiency Pop for Epic using this integration.
To integrate SMART on FHIR with OnBase, the following must be in place:
• Third-party app (EHR or Epic)
• Application Server
• Hyland IdP
• EHR Auth server

Note: Initially, only OnBase Epic Integration clients can use SMART on FHIR. Also, the SMART on
FHIR module is limited to only the EHR App Launch.

Licensing
Beginning in OnBase Foundation EP5, new customers must use simplified licensing to access
SMART on FHIR functionality. Existing customers upgrading from a version of OnBase prior to
OnBase Foundation EP5 can continue to use legacy licensing to access this functionality.
If you are a new customer as of OnBase Foundation EP5 or greater, see Simplified Licensing on page
1.
If you are upgrading from a version of OnBase prior to OnBase Foundation EP5, see Legacy Licensing
on page 1.

Simplified Licensing
In addition to an enterprise base package license for standard OnBase functionality, the OnBase
Integration for Epic add-on license is required to access standard SMART on FHIR functionality.

Legacy Licensing
The
  Epic Integration license is required to use SMART on FHIR.

© 2022 Hyland Software, Inc. and its affiliates 1

Guide
Administration
SMART on FHIR

Administration Guide

Foundation 22.1
 Configuration

Overview
To integrate SMART on FHIR with OnBase, you must configure the following:
• Hyland IdP, both a Provider and Client (see Hyland IdP Configuration on page 3)
• OnBase Configuration for the SMART on FHIR application (see OnBase Configuration on page
3)
• OnBase Application Server configuration (see Application Server Configuration on page 13)

Hyland IdP Configuration

Before you can use SMART on FHIR with OnBase, you must have a Hyland Identity Provider (IdP)
configured for both a Provider and a Client. The Provider configuration provides support for
OIDC-Exchange grants, and the Client configuration adds a new client to support SMART on FHIR
launches. See the Hyland Identity and Access Management module reference guide for more
information.

Note: Before you save the Hyland IdP configuration, be sure to write down the Client Secret. Once
you save the configuration, the Client Secret field is encoded. You will need the unencoded Client
Secret when configuring SMART on FHIR applications with OnBase.

OnBase Configuration
Configuration for the integration of SMART on FHIR with OnBase is performed in the OnBase
Configuration module. The following sections contain information on the various features and
settings of SMART on FHIR:
• Creating a SMART on FHIR Application on page 3
• Configuring Hyland IdP Settings on page 6
• Configuring EHR Authorization Settings on page 9

Creating a SMART on FHIR Application

OnBase configuration allows administrators the ability to build a group of settings that are referred
to as an Application. This group of settings can then be loaded into the OnBase Application Server to
define behaviors when utilizing the SMART on FHIR functionality. This allows for the following:
• Multiple EHRs can launch OnBase applications

© 2022 Hyland Software, Inc. and its affiliates 3

 SMART on FHIR
Configuration

• One EHR can utilize multiple sets of configurations. For example, integrated viewing applications
may request different permissions than integrated scanning applications, so you may want to
configure each solution to use a different application.
To create a new SMART on FHIR application:
1. In the OnBase Configuration module, select Medical | FHIR | SMART on FHIR. The SMART on
FHIR Applications dialog box is displayed.

© 2022 Hyland Software, Inc. and its affiliates 4

 SMART on FHIR
Configuration

2. Enter the name of the SMART on FHIR application to be created in the field provided, and click
Create. The name of the new SMART on FHIR instance is displayed.

3. Click the Settings button. The Settings dialog box for the application you created is displayed.

4. The Settings dialog box contains settings used by the application server that are then used when
an OnBase scanning or viewing app interacts with the SMART on FHIR workflow. The following
settings are available for configuration:
• Application Name. You can either rename the application, or keep it the same.

© 2022 Hyland Software, Inc. and its affiliates 5

 SMART on FHIR
Configuration

• Application Unique ID. This is a unique ID that is automatically generated when setting up
the application server. This ID is used when configuring the SMART on FHIR application ID in
the OnBase Application Server web.config file.
• Username Claim. This is the name of the claim that is used to specify the name of the claim
that contains the end user ID that will be used to map to an OnBase username. This will be
the same value that was configured in the Hyland IdP's Username field.

• Availability. Select to either Enable or Disable the application. This allows you to disable an
Application configuration that should not be used. The default value is Enabled.
5. Click Save.

Configuring Hyland IdP Settings

You must have established a Client in the Hyland IdP administration to support the SMART on FHIR
applications. The settings established here provides communication information between SMART

© 2022 Hyland Software, Inc. and its affiliates 6

 SMART on FHIR
Configuration

on FHIR and the Hyland IdP. Please see the Hyland Identity and Access Management module
reference guide for more information.
To configure the Hyland IdP for your application:
1. Select the application you want to configure from the SMART on FHIR Applications dialog box.

© 2022 Hyland Software, Inc. and its affiliates 7

 SMART on FHIR
Configuration

2. Click Hyland IdP. The Hyland IdP Settings dialog box for the application you selected is
displayed.

3. In the Authority URL field, enter the name of the server for the Hyland IdP instance you created.
For example: https://example.com/identityprovider. This is a required field.
4. In the Client ID field, enter the GUID specified in the Hyland IdP when configuring a new client,
This configuration for the client should be associated with the SMART on FHIR launch. This is a
required field.

Note: See the Hyland Identity and Access Management Service module reference guide for
details on creating the client.
5. In the Client Secret field, enter the plain text secret (password) that is configured for the client
during Hyland IdP configuration.

Note: Be sure to use the Client Secret value that was written down prior to saving the Hyland IdP
configuration. The Client Secret is encoded once the configuration is saved. The encoded value
will not work for application configuration. See your system administrator for more information if
necessary.

© 2022 Hyland Software, Inc. and its affiliates 8

 SMART on FHIR
Configuration

6. Select the Scopes tab to add a list of scopes required by the Hyland IdP to execute the Token
exchange and Addendum exchange grants. Add a scope by typing the name of the scope in the
field provide, and then click Add. The openid scope is required.

Note: Administrators should limit the scopes that are requested during the SMART on FHIR app
launch to avoid granting the client unnecessary access to resources.
7. Select the Endpoints tab to add endpoint connections between SMART on FHIR and the Hyland
IdP. Adding endpoint configuration can reduce network traffic required per app launch. If no
endpoints are configured, the launch process will default to requesting the Discovery Document
using the IdP's well-known endpoint ("/.well-known/openid-configuration"). The Discovery
Document is then used to locate the Token and JWKS endpoints. If both Token and JWKS
endpoints are specified, then the process will not attempt to load the Discovery Document,
regardless of whether a Discovery Document endpoint is explicitly configured or not. This can
improve performance.

Note: Only one of each endpoint type is allowed.

Do the following to add endpoints:
• From the Type drop-down list, select an endpoint type. Options include:
• Discovery Document. This is a URL to the IdP's Discovery document. For example:
https://example.com/identityprovider/.well-known/openid-configuration.
• Jwks. This is a URL to the IdP's JSON Web Key set. For example: https://example.com/
identityprovider/.well-known/openid-configuration/jwks.
• Token. This is a URL to the IdP's Token endpoint for use in a Token Exchange. For
example: https://example.com/identityprovider/connect/token.
• In the URL field, enter a server location for the endpoint.
• Click Add. The endpoint is added to the Endpoints tab.
8. Click Save.

Configuring EHR Authorization Settings

The SMART on FHIR application is launched by the EHR. The EHR will call a launch URL specified
in the EHR configuration. EHR will then send a launch token and the FHIR server's endpoint URL. In

© 2022 Hyland Software, Inc. and its affiliates 9

 SMART on FHIR
Configuration

order for this to happen, EHR must be authorized with your application, so it can provide the proper
access tokens to integrate with OnBase.
To configure the EHR authorization settings:
1. Select the application you want to configure from the SMART on FHIR Applications dialog box.

© 2022 Hyland Software, Inc. and its affiliates 10

 SMART on FHIR
Configuration

2. Click EHR Authorization. The EHR Authorization Settings dialog box for the application you
selected is displayed.

3. In the Client ID field, enter the GUID provided by the EHR Authorization server for the client that
should be associated with the SMART on FHIR launch. This is a required field.
4. In the Client Secret field, enter the plain text secret (password) that is configured for the client
specified in the Client ID field.
5. In the Redirect URL field, enter a properly formatted URL that will be used by the EHR
Authorization to return a redirect response (HTTP 302) to the SMART on FHIR client Logic when
a successful authentication occurs. It is recommended that you populate this field with the
URL of the OnBase Application Server (or load balancer) associated with the SMART on FHIR
application. Optionally, you can append "/redirect" to the base URL to improve clarity when
troubleshooting. For example: https://myserver/appserver/redirect.
6. Select the Approved Launch Issuers tab to create a list of URLs to be accepted as issuers
(iss=<url>) of a SMART on FHIR launch. This is often the base URL to the EHR Authorization
server. For example: https://myEhrAuthzServer. Type the URL in the field provided, and then click
Add.
7. Select the Approved Token Issuers tab to create a list of URLs to be accepted as issuers of
OpenID tokens. This is often the base URL to the EHR Authorization server. For example: https://
myEhrAuthzServer. Type the URL in the field provided, and then click Add.

© 2022 Hyland Software, Inc. and its affiliates 11

 SMART on FHIR
Configuration

8. Select the Scopes tab to add a list of scopes required by the EHR Authorization server to execute
the launch code exchange and Token grants. You may need to consult with the EHR vendor to
define this list. Add a scope by typing the name of the scope in the field provide, and then click
Add.

Note: Administrators should limit the scopes that are requested during the SMART on FHIR app
launch to avoid granting the client unnecessary access to resources.
9. Select the Endpoints tab to add endpoint connections between SMART on FHIR and the EHR
Authorization server. Endpoint settings are optional.

Note: Only one type of each endpoint type is allowed.

If needed, do the following to add endpoints:
• From the Type drop-down list, select an endpoint type. Options include:
• Authorize. This is the URL to the EHR FHIR server's configured Authorization server
Authorize endpoint. For example: https://example.com/ehrauthz/connect/authorize.
• Capability Statement. This is the URL to the EHR FHIR server's Capability Statement.
This document is used to determine the Authorize and Token endpoints for the FHIR
server that issued the SMART on FHIR launch. The FHIR server is usually paired with
an Authorization server whose Authorize endpoint is specialized to support a SMRT on
FHIR launch code exchange for an OAuth2 Authorization code. For example: https://
example.com/fhir/R4/metadata.
• Discovery Document. This is the URL to the EHR Authorization server's Discovery
document. Examples include: https://example.com/ehrauthz/.well-known/openid-
configuration or https://example.com/ehrauthz/.well-known/smart-configuration.
• Jwks. This is the URL to the EHR Authorization server's JSON Web Key set. For example:
https://example.com/ehrauthz/.well-known/openid-configuration/jwks.
• Token. This is the URL to the EHR FHIR server's configured Authorization server Token
endpoint. For example: https://example.com/ehrauthz/connect/token.
• In the URL field, enter a server location for the endpoint.
• Click Add. The endpoint is added to the Endpoints tab.
Note the following when adding endpoints:
• If the Capability Statement endpoint is not specified, the SMART on FHIR standard
Capability Statement location of [launch-issuer]/metadata will be used to determine the
Authorize and Token endpoints.
• If the Discovery Document endpoint is not specified, the OpenID Connect standard
Discovery document location of [token-issuer]/.well-known/openid-configuration
will be used to determine the EHR Authorization server's JWKS endpoint.
• If the Jwks endpoint is specified, the SMART on FHIR service will not require an outbound
HTTP request to retrieve the Hyland IdP's Discovery document. This endpoint should only be
used if troubleshooting or optimizing for performance. If that endpoint will not change, set it
here to eliminate the extra "hop."
• If Authorize and Token endpoints are specified, the SMART on FHIR service will not require
an outbound HTTP request to retrieve the EHR FHIR server's Capability Statement. If those
endpoints will not change, set them here to eliminate the extra "hop."
10. Click Save.

© 2022 Hyland Software, Inc. and its affiliates 12

 SMART on FHIR
Configuration

Deleting a SMART on FHIR Application

If you created a SMART on FHIR application that is no longer needed, you can delete it.
To delete an application:
1. In the OnBase Configuration module, select Medical | FHIR | SMART on FHIR. The SMART on
FHIR Applications dialog box is displayed.

2. Select the application you want to remove.

3. Click Delete. A confirmation box is displayed.
4. Click Yes. The application is removed from the system.

Application Server Configuration

The OnBase Application Server must be configured in order to load the SMART on FHIR package. The
configurations provide information to the system, which are necessary in order to manage an app
launch.
The Application Server configurations that must be set include:
• SMARTonFHIRApplicationId
• accessTokenValidation

© 2022 Hyland Software, Inc. and its affiliates 13

 SMART on FHIR
Configuration

SMARTonFHIRApplicationID Configuration
You must set this configuration to specify which SMART on FHIR application configuration the
Application Server should use when performing SMART on FHIR authentication. This setting can be
found in the Application Server's web.config file, in the <configuration>|<appsettings> section.
<configuration>
<appSettings>
<add key="SMARTonFHIRApplicationId" value="[GUID]" />
</configuration>
The value for the GUID can be found in the Application Unique ID field in the Application Server
Settings. See step 3 in Creating a SMART on FHIR Application on page 3 to locate the application
ID.

accessTokenValidation Configuration
This configuration is used to validate Hyland IdP access tokens. This setting can be found in the
Application Server's web.config file, in the <configuration> |<Hyland Authentication>
section.

<configuration>
<Hyland.Authentication>
<access TokenValidation idp="https://[idp-base-url]"
audience="https://[idp-base-url]/resources" nameClaimType="username"
apiName="" apiSecret="" />
<configuration>

The specific values for the configuration can be found in the Hyland IdP Client settings for SMART on
FHIR.
 

© 2022 Hyland Software, Inc. and its affiliates 14