Note: You must have a preexisting account (username and password) to access Oracle Soarian Clinicals and permission to use the REST API. To request access to the REST API, contact your Oracle Health administrator.
Authorization
The Oracle Health implementation of the HL7 FHIR standard is protected using the SMART App Launch Framework and SMART Backend Services: Authorization Guide. Oracle Health EHR APIs are also protected with SMART authorization, enabling the development of applications that are secured through a single authorization mechanism. SMART defines profiles of the OAuth 2.0 framework for obtaining authorization to act on behalf of users and nonperson system actors. Review and understand the OAuth 2.0 framework before implementing the authorization workflow.
The following IETF publications are recommended for review:
- The OAuth 2.0 Authorization Framework
- OAuth 2.0 Threat Model and Security Considerations
- OAuth 2.0 Security Best Current Practice
- The OAuth 2.0 Authorization Framework: Bearer Token Usage
- OAuth 2.0 for Native Apps
This guide provides the following information:
- A technical overview for securely obtaining authorization on behalf of a user or a system, using Oracle Health authorization server.
- Guidance for providing an optimal authorization user experience across a broad range of platforms.
- Guidance for ensuring broad compatibility across a diverse range of deployment scenarios.
- Answers to frequently asked questions.
Features of the Authorization Model
The use of an authorization protocol offers additional security for users and enterprises by abstracting the credentials used to authenticate to the EHR away from client applications. Under this model, restrictions can be applied to what actions a client application can perform on behalf of the user. These restrictions are not possible in traditional models where the application has direct access to the user’s credentials.
Furthermore, by abstracting authentication away from client applications, the risk of compromising credentials is decreased, and organizations have more flexibility to offer differing forms of authentication, such as Microsoft Windows Hello or Apple Touch ID.
The token model employed by the OAuth 2.0 framework provides a useful means in a distributed-service ecosystem to enforce frequent validation that access has not otherwise been revoked or expired.
A formal technical specification for authorization may be found in the FHIR Service Authorization Specification.
Differentiating SMART and FHIR
The HL7 FHIR standard defines an API to access information in an EHR system.
SMART defines an API for applications to obtain authorization access to FHIR or other Oracle Health API resources and exchange context information with client applications.
Oracle Health implements the following versions of SMART:
Registering an Application
To use any protected resources, your client application must first be registered. A free CernerCare account is required to register applications.
Complete the following steps to register a new application:
- Log in to code Console.
- Register a new application with your intended application type and application privacy, and complete the registration process.
If you are an Oracle Health customer developing an application, see the Making Self-Developed SMART Apps Available in Your Domain topic in the Ignite APIs Community.
Once registered, a client ID is provided for use with the Oracle Health authorization server. Oracle Health customers may then enable client applications to access their protected resources.
Registering a System Account
If an application has its own server responsible for making API requests, you can register your application as a confidential client. Check the respective FHIR implementation documentation to determine availability. Confidential client applications are issued customer secrets, which are managed through Cerner Central system accounts. This system account is automatically generated and available in Cerner Central after you register your application in code Console.
Complete the following steps to obtain and manage a system account in code Console:
- Register a new application with an application type of System or an application privacy of Confidential, and complete the registration process.
- On the application details page, select the link to manage your system account details, such as the customer secret or setting up JWKS for bulk applications.
When you complete the registration, a new system account is issued to the same CernerCare account used to log in and register the application. A confirmation email is sent to the address associated with the CernerCare account.
Remember to protect the secret received through this process. Do not post this secret or email it in an insecure method. Do not include this secret or the credentials requests for the authorization server in online forums. If you do compromise the secret, you can rotate the credentials using Cerner Central system accounts.
Requesting Authorization on Behalf of a User
To access our APIs on behalf of a user, your client application must make an authorization request through a user agent on the user’s device.
This process involves the following steps:
- Discover the authorization and token endpoint URLs.
- Construct an authorization grant request URL.
- Call a browser with the authorization grant request URL.
- Receive the OAuth callback.
- Exchange the received grant for a token.
- Close the browser.
- Handle any exceptions encountered.
- Use refresh tokens.
A formal technical specification for this process may be found in the FHIR Service Authorization Specification.
Discovering Authorization URLs
Each EHR’s instance of our FHIR APIs advertises the URLs of its respective authorization server (for each persona) in its Well-Known SMART Configuration document. See the Conformance - SMART App Launch 2.2.0 page on the HL7 FHIR website for more information.
To retrieve the Well-Known SMART Configuration document, perform a GET
request against the resource located at the relative path of /.well-known/smart-configuration
from the FHIR base URL. See Get authorization endpoints and launch capabilities for examples of this request.
The most notable fields are the authorization_endpoint
and the token_endpoint
, which are used in various examples throughout the remainder of this document.
These URLs must be discovered (rather than hard-coded into your client application) because they can and may change on occasion.
The following text is a partial and non-normative example of a document containing this information:
{ "authorization_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/personas/provider/authorize", "token_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token", "revocation_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token/revoke", "management_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/personas/provider/my-authorizations", "introspection_endpoint": "https://authorization.cerner.com/tokeninfo" }
Constructing the Authorization Request URL
An authorization request uses the format of an x-www-form-urlencoded
query string, appended to the authorization endpoint’s URL as discovered from the previous sections. The base specification for the structure of this request is defined in section 4.1, Authorization Code Grant of RFC 6749.
At minimum, include the following parameters in the authorization request:
scope
: The requested scopes for services to access.state
: A value used to prevent certain classes of malicious attacks.aud
: The parameter designating the target audience server URL.redirect_uri
: Optionally, a redirect URI of the application.launch
: Optionally, a launch code when a supporting application opens from external sources.
Note: Applications that use SMART Backend Services directly request a token. The below information about OAuth scopes still applies to those requests.
Scopes
During the authorization process, client applications identify a collection of API entitlements that the application requires to operate. In OAuth 2.0, the client application conveys this information to the authorization server in the form of scope
.
The OAuth 2.0 Authorization Framework defines the scope of a request as follows:
The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. The strings are defined by the authorization server.
For workflows that use an authorization code, an authenticated user may be prompted for permission to authorize your application. This workflow can present the user with the list of scopes being requested, which are framed as human-meaningful permissions. As such, it is good practice to request only the minimum set of scopes used by your application.
Scopes for FHIR services
The SMART specification defines the structure of scopes for FHIR services. This structure varies between versions of SMART.
See one of the following resources based on which version of SMART your application uses:
- SMART App Launch: Scopes and Launch Context (v1.0.0: STU 1)
- SMART Backend Services: Authorization Guide (v1.0.1: STU1)
Examples of scopes include:
user/Observation.read
: Read all values from the Observation resource that the user has access to.patient/MedicationOrder.read
: Read medications for a specific patient.user/Appointment.write
: Create appointments.
A resource context prefixes each FHIR scope in SMART. This value represents one of three possible use cases:
user
: Access to the resource is only constrained by the access of the user.patient
: Access to the resource is constrained within context of a single patient.system
: Used in system-based authorization workflows, as described in Requesting Authorization on Behalf of a System.
Applications must explicitly request each scope it requires to operate, as we do not support Wildcard scopes. See the linked document for a more detailed discussion of the challenges that they pose.
In addition to FHIR resource scopes, the SMART authorization framework defines the following scopes that further govern the behavior of authorization:
openid
: Provides access to the principal of the authenticated user per the OpenID Connect specification.fhirUser
: Provides an OpenID Connect token that contains the URL of the authenticated user’s FHIR resource. This scope was formerly known asprofile
, but that name has since been retired.online_access
: Allows an application to obtain tokens through a refresh process while the authenticated user remains online.offline_access
: Allows an application to obtain tokens on behalf of the authenticated user through a refresh process, even after they are no longer online. The user, an administrator, or your application must explicitly revoke the token. An offline access refresh token is revoked automatically if its access is unused for more than three months.
See the FAQs for other scope limitations.
Identity Scopes
Certain classes of applications may need to identify the user for whom it is acting on behalf of.
Such requirements can include but are not limited to the following examples:
- Audit or log activity using the user identifier or person’s name.
- Display the user’s name in the application or in out-of-band (email) communications with the user.
- Perform identity matching to other non-EHR resources managed by the application.
- Authenticate the user in subsequent visits to provide an enriched experience, such as retaining user preferences or protecting access to other non-EHR-managed information (for example, user-created information).
The openid
scope requests that the Oracle Health authorization server supplies an OpenID Connect identity token as part of the authorization workflow.
See Authorization Server OpenID Connect Support for more information on using the OpenID token.
The fhirUser
scope also requests that the OpenID Connect token includes a fhirUser
claim, as defined by the SMART authorization framework. This URL identifies the specific FHIR resource URL of the authenticated user. This resource may be a Patient, Practitioner, or Person resource, depending on the type of user who is authenticated.
Duration Scopes
The default duration of access received through the authorization grant workflow is a single token that is valid for 570 seconds (approximately 10 minutes). For applications that need access to services for longer durations, Oracle Health FHIR APIs platform supports the concept of refresh tokens.
With the online_access
scope, your application can continue to obtain access tokens on behalf of the user until one of the following actions occurs:
- The user explicitly logs out using their respective session authority.
- The user’s session expires or is administratively terminated.
- The given organization terminates your application’s access.
With the offline_access
scope, your application can continue to obtain access tokens in perpetuity on behalf of the user until one of the following actions occurs:
- The user or administrator explicitly terminates the original authorization grant.
- The user’s access to the resources from the original authorization grant is terminated.
- Your application’s access goes unused for more than three months.
- The given organization terminates your application’s access.
Supported Scopes
Wildcard Scopes are currently not supported. See the linked document for a more detailed discussion of the challenges that they pose. An application is currently required to specifically request each scope that it needs to run.
Other combinations of scopes may be limited. See the FAQs for known limitations.
State
When performing an authorization grant request, Oracle Health recommends that your client application establish a transient, single-use state
value for each request. If your application receives an authorization response that does not include a value known to the current user’s device, it should reject the response. This mechanism is to protect your application against cross-site request forgery attacks.
For more information on these types of exploits, see RFC 6819 - OAuth 2.0 Threat Model and Security Considerations.
Audience
When performing an authorization grant request, your client application must send the base URL of the resource server for which you are sending access tokens to. This information is conveyed through the aud
query parameter in the grant request. Our authorization server uses this parameter to protect your application against a form of exploit where an untrusted resource server advertises a legitimate authorization server in its conformance document. Without this feature, your application could inadvertently send a valid, authorized access token to the untrusted party.
The authorization server automatically rejects authorization grant requests that do not contain the audience parameter.
The following fragment is from a x-www-form-urlencoded
grant request query string where the audience is provided:
&aud=https%3A%2F%2Ffhir-ehr-code.cerner.com%2Fdstu2%2Fec2458f2-1e24-41c8-b71b-0e701af7583d%2F
Redirect URI
When performing an authorization grant request, the application may provide a redirect_uri
. This URI should match the redirect URI provided during the registration phase of the SMART application.
If your application has multiple redirect URIs registered, you must include a redirect_uri
with your authorization grant request.
The redirect_uri
must be an absolute URI. For more information, see the Redirection Endpoint section of RFC 6749.
The following fragment is from a x-www-form-urlencoded
grant request query string where the redirect_uri
is provided:
&redirect_uri=https%3A%2F%2Fapp%2Fafter-auth
Launch
Some Oracle Health products support the launch feature of the SMART authorization framework.
This feature provides the following capabilities for your application:
- Oracle Health products can go to the URL of your application in the user’s context. When requested by the user, the FHIR base URL is passed to your application, thus avoiding the need for the user to specify which organization or FHIR endpoints the application should interact with.
- Your client application can request contextual information such as the identifiers of the patient record, the encounter being viewed, or the current user.
Examples
See the following examples of authorization requests using SMART Application Launch 1.0.0 - STU1:
client id: bb318a62-fa61-49ae-b692-7d99214f0ec7 scopes: patient/Observation.read patient/MedicationHistory.read launch audience: https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/ state: a4c16a46-2c46-482c-8d66-4cc4a2990bda launch: a17aba51-1395-48d3-b3a9-73f2baf784da https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/personas/patient/authorize?client_id=bb318a62-fa61-49ae-b692-7d99214f0ec7&response_type=code&redirect_uri=&scope=patient%2FObservation.read%20patient%2FMedicationHistory.read%20launch&launch=a17aba51-1395-48d3-b3a9-73f2baf784da&aud=https%3A%2F%2Ffhir-ehr-code.cerner.com%2Fdstu2%2Fec2458f2-1e24-41c8-b71b-0e701af7583d%2F&state=a4c16a46-2c46-482c-8d66-4cc4a2990bda
client id: bb318a62-fa61-49ae-b692-7d99214f0ec7 scopes: user/Observation.read user/MedicationHistory.read audience: https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/ state: a4c16a46-2c46-482c-8d66-4cc4a2990bda https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/personas/patient/authorize?client_id=bb318a62-fa61-49ae-b692-7d99214f0ec7&response_type=code&redirect_uri=&scope=user%2FObservation.read%20user%2FMedicationHistory.read%20&launch=&aud=https%3A%2F%2Ffhir-ehr-code.cerner.com%2Fdstu2%2Fec2458f2-1e24-41c8-b71b-0e701af7583d%2F&state=a4c16a46-2c46-482c-8d66-4cc4a2990bda
Calling an Appropriate User Agent
Once an authorization code grant request URL has been generated, you need an appropriate user agent to call the authorization request. In all scenarios, this web page interacts with the user agent to determine the identity of the user. This process may involve further redirects to other identity providers (web applications designed to authenticate users), interaction with browser JavaScript APIs, or direct interactions with the user to obtain their approval during the authorization process.
This particular part of the process has various complexities. The recommendations offered in this section are designed to ensure that the following expectations are met:
- The user is offered a single sign-on and single log-out experience.
- The authentication and authorization workflows do not affect browser history navigation.
- The use of browser frames and web views do not interfere with the authentication and authorization workflows. Clickjacking defenses, browser plug-ins, and access to local storage or certificates used in authentication may be interfered with.
The sections below discuss how to call the proper user agent for specific platforms.
Client Applications Delivered Through the Browser
For applications delivered through the https
scheme in a browser, Oracle Health recommends calling the authorization workflow in a separate window for desktop browsers or a separate tab for mobile browsers. The use of a separate window or tab ensures that any navigation that occurs while servicing the authentication or authorization workflows is maintained separately from your initial tab. The user can then properly navigate backwards in their browser history once the authorization workflow has been completed. On desktop and mobile device platforms that offer split-screen browsing, this methodology creates a clean delineation between your application’s workflow and the authorization workflow.
Due to the nature of built-in pop-up blocking functionality, your application may need to open the window based on a user interaction (for example, select or touch). In certain venues, alternatives may be possible to avoid this requirement; further guidance is outside the scope of this guide.
Web-based applications must not attempt to perform the authorization workflow in an iframe. Doing so may have unexpected results caused by clickjacking protection mechanisms, anti-phishing protection mechanisms, browser third-party cookie policy, and so on.
When opening an additional browser window, Oracle Health recommends including the location “chrome” of the browser such that TLS/EVSSL indicators are included for display to the user. These visual cues are an important part of security for some authentication systems.
Your authorization response is in the form of a redirect orchestrated in the subwindow to your registered redirect URI. Once your server has processed the response, JavaScript can be used to notify the main window that the workflow is complete. In turn, the main window can close the subwindow.
Example Javascript for Opening the Authorization Workflow
The JavaScript below demonstrates how an application could open the authorization workflow as a dialog box on desktop platforms. In addition to desktop platforms, this method automatically functions on mobile device platforms by creating an additional tab or split-screen browsing window.
var width = 780, height = 550, left = (screen.width - width) / 2, top = (screen.height - height) / 2, uniqueWindowId = "authorization-" + yourAppClientId params, location; if (top > 20) { top = top - 20; } params = 'width=' + width + ', height=' + height; params += ', top=' + top + ', left=' + left; params += 'titlebar=no, location=yes'; location = build_oauth_request_url(); loginWindow = window.open(location, uniqueWindowId, params);
The JavaScript snippets below demonstrate how your application can notify the main window of the completion of the workflow.
The following script allows your main window to listen to postMessage calls from subwindows:
window.addEventListener("message", function (e) { var oauthMessage = e.data; loginWindow.close(); processOAuthMessage(oauthMessage); }, false);
The web page serves the following script at your callback URI:
window.opener.postMessage(oauthMessage, 'https://example.com/');
The contents of the oauthMessage
could be the entirety of the query string or the result of any server-side processing handled by your server as a result of the GET request to the callback URI.
Other User Experience Considerations
- Use the same window name in the request to
window.open()
to avoid scenarios where a user accidentally opens multiple authorization windows for your application simultaneously. - Include visual cues to indicate that your application is waiting on the authorization process. For example, a translucent curtain or dialog box with a progress indicator, with text that indicates that you are waiting on user interaction in another window.
- Provide a link or button to cancel the authorization process and close the subwindow.
- Have the Script served at your callback URI check for a main window, and if not present, notify the user. Including a link whose target opens in a new window allows the user to proceed with their original workflow if the user closes the original window that initiated the authorization workflow.
Native Client Applications
Recently, OS platforms have been forced to lock down certain behaviors in their browsers that were traditionally used to facilitate OAuth2-based authorization workflows. Specifically, browsers now interrupt any attempt to direct a user to a native application due to abuse from advertisers of mobile apps. As a result, OS platforms now offer in-app browsers useful for orchestrating authorization workflows that are free of such impediments. These in-app browsers also improve the user experience of OAuth2-based workflows by preventing remnant browser tabs and smoothing the transition between browser and application. No OS app-switching occurs.
Refresh tokens for native applications are handled the same way as web-based applications. See the Using Refresh Tokens section below for more information.
See the IETF Best Current Practices (BCP) OAuth 2.0 for Native Apps for more information on best practices for OAuth2-based workflows for native applications.
Note: For the implicit grant authorization flow, the Oracle Health authorization server does not implement PKCE, which is noted in section 8.2 of the native applications BCP.
The sections below discuss specific special cases not covered by the OAuth native application BCP guide.
Microsoft Windows-Based Applications
Oracle Health currently supports only explicit internet hosts or explicit URI activation schemes for redirection URIs. Developers of traditional Microsoft Windows applications should complete the Microsoft Learn steps for Registering an Application to a URI scheme for their application.
The following example is a sample registry file for a hypothetical scheme registration of sample.application://
:
Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\sample.application] @="URL:Sample Authorization App" "URL Protocol"="" "UseOriginalUrlEncoding"="1" [HKEY_CLASSES_ROOT\sample.application\DefaultIcon] @="sample.exe,1" [HKEY_CLASSES_ROOT\sample.application\shell] [HKEY_CLASSES_ROOT\sample.application\shell\open] [HKEY_CLASSES_ROOT\sample.application\shell\open\command] @="c:\\sample.exe \"%1\""
For the above registration, the client application is registered with a redirection URI whose scheme begins with sample.application://
(for example, sample.application://callback
). Upon redirection to this scheme, the Microsoft Windows operating system calls the registered application with the OAuth 2.0 response URI passed as the first argument. The client application can then parse the URI and, in turn, determine which instance of the application initiated the request through examination of the state parameter.
Additional registry settings may be required as browser vendors implement mitigations for scheme flooding vulnerabilities. See the following Fingerprint article for more information: Exploiting custom protocol handlers for cross-browser tracking in Tor, Safari, Chrome and Firefox.
For example, in recent versions of Microsoft Edge, the relevant registry settings are AutoLaunchProtocolsComponentEnabled
, AutoLaunchProtocolsFromOrigins
, and DoNotSilentlyBlockProtocolsFromOrigins
. Without these settings, the browser may log error messages to the console such as Not allowed to launch <your application scheme> because a user gesture is required
. See Microsoft Edge - Policies for more information.
Processing the Authorization Grant Response
The authorization grant response comes in the form of an x-www-form-urlencoded query
string, appended to your redirection URI. The base specification for the structure of this response is defined in the Authorization Code Grant section of The OAuth 2.0 Authorization Framework.
See the following example:
https://example.com/callback?code=0c8b259b-d716-4712-ad6a-1d22d92523fa&state=a4c16a46-2c46-482c-8d66-4cc4a2990bda
A successful response has a code parameter, and a state
parameter is also present if your application included state in the initial request.
First, validate that the state
parameter matches a request that the current device or user agent initiated.
Next, exchange the code for a token per the Access Token Request section of The OAuth 2.0 Authorization Framework.
Note: If the redirect_uri
parameter was not provided during the authorization request, the redirect_uri
must be omitted in the token request. Otherwise, if the redirect_uri
parameter was provided in the authorization request as described in the Authorization Code Grant section of The OAuth 2.0 Authorization Framework, the parameter must also be present in the token request and their values must be identical.
See the following example requests and responses:
Request:POST /tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token HTTP/1.1 Host: authorization.cerner.com Accept: application/json Content-Type: application/x-www-form-urlencoded Content-Length: 161 Connection: close grant_type=authorization_code&code=0c8b259b-d716-4712-ad6a-1d22d92523fa&redirect_uri=&client_id=bb318a62-fa61-49ae-b692-7d99214f0ec7Response:
HTTP/1.1 200 OK Access-Control-Allow-Origin: * Access-Control-Allow-Methods: OPTIONS, POST Access-Control-Allow-Headers: Content-Type, Authorization Cache-Control: no-store Pragma: no-cache Content-Type: application/json Content-Length: 1462 Date: Tue, 01 Nov 2016 19:20:25 GMT { "access_token": "eyJraWQiOiIyMDIwLTA3LTI4VDE3OjM2OjA5LjAwNC5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3J0YWwiLCJ1cm46Y29tOmNlcm5lcjphdXRob3JpemF0aW9uOmNsYWltcyI6eyJ2ZXIiOiIxLjAiLCJ0bnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJhenMiOiJ1c2VyXC9PYnNlcnZhdGlvbi5yZWFkIn0sImF6cCI6ImZoaXItbG9jYWwiLCJpc3MiOiJodHRwczpcL1wvYXV0aG9yaXphdGlvbi5jZXJuZXIuY29tXC8iLCJleHAiOjE1OTYwNTYwNjEsImlhdCI6MTU5NjA1NTQ2MSwianRpIjoiYmMwMzIwYTMtN2E3Yi00MmVkLTgzZDAtMWMxMTVlMjBkMDQzIiwidXJuOmNlcm5lcjphdXRob3JpemF0aW9uOmNsYWltczp2ZXJzaW9uOjEiOnsidmVyIjoiMS4wIiwicHJvZmlsZXMiOnsic21hcnQtdjEiOnsiYXpzIjoidXNlclwvT2JzZXJ2YXRpb24ucmVhZCJ9fSwiY2xpZW50Ijp7Im5hbWUiOiJGSElSIExvY2FsIFRlc3QgQ2xpZW50IiwiaWQiOiJmaGlyLWxvY2FsIn0sInVzZXIiOnsicHJpbmNpcGFsIjoicG9ydGFsIiwicGVyc29uYSI6InByb3ZpZGVyIiwiaWRzcCI6ImVjMjQ1OGYyLTFlMjQtNDFjOC1iNzFiLTBlNzAxYWY3NTgzZCIsInNlc3Npb25JZCI6IjFiYmEyOGQ0LTUwM2YtNDgyNi04OTE3LTJhOTIzMzczZjE2YyIsInByaW5jaXBhbFR5cGUiOiJ1c2VybmFtZSIsInByaW5jaXBhbFVyaSI6Imh0dHBzOlwvXC9taWxsZW5uaWEuY2VybmVyLmNvbVwvaW5zdGFuY2VcL2VjMjQ1OGYyLTFlMjQtNDFjOC1iNzFiLTBlNzAxYWY3NTgzZFwvcHJpbmNpcGFsXC8wMDAwLjAwMDAuMDBDMi42REI1IiwiaWRzcFVyaSI6Imh0dHBzOlwvXC9taWxsZW5uaWEuY2VybmVyLmNvbVwvYWNjb3VudHNcL2MxOTQxLmNlcm5fYWJjbi5jZXJuZXJhc3AuY29tXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL2xvZ2luIn0sInRlbmFudCI6ImVjMjQ1OGYyLTFlMjQtNDFjOC1iNzFiLTBlNzAxYWY3NTgzZCJ9fQ.AruMhr4eaG3QHb794wzavhcD8NQAnao5sZWAe4cFbX4-oSd3pUwomoZ-zR8stSKhnaodS0l5bKGkd72goX0PNQ", "scope": "user/Observation.read", "token_type": "Bearer", "expires_in": 570 }
Evaluate the following elements of the response:
access_token
: This element is the secret content to send to a FHIR service to prove authorization for acting on behalf of a user.scope
: This element is the space-delimited list of scopes that were authorized for use. This list may differ from the list of scopes included in the initial request. In some circumstances, the server may redact scopes, and in others, users may have the capacity to redact scopes.expires_in
: This element is the number of seconds before the token expires. If access is required for longer than the expiration of the token, consider requestingonline_access
oroffline_access
, as needed.
The following additional elements may be returned:
patient
: The FHIR ID of a Patient resource in context of the current launch.encounter
: The FHIR ID of an Encounter resource in context of the current launch.refresh_token
: A token that can be exchanged at the token endpoint for new access tokens.id_token
: An OpenID Connect identity token that can be used as authentication to your application.
Closing the Grant Interaction
Once the authorization grant response is received, the separate window or user agent for facilitating the grant interaction should be automatically closed, where possible. An example for web-based applications is included in the JavaScript example mentioned above. If this step is unsuccessful or not possible, content is provided by the authorization server to inform the user if the additional window can be safely closed. The authorization server itself does not attempt to self-close the window, as this generally results in a prompt from the browser asking for permission.
Exception Handling
Both the authorization grant response and access token response can result in error messages.
The following example is an error message response from the grant workflow:
https://example.com/callback?state=f09dcfff-95ff-4e86-a689-05c8dd9719a2&error=access_denied&error_uri=https%3A%2F%2Fauthorization.cerner.com%2Ferrors%2Furn%253Acerner%253Aerror%253Aauthorization-server%253Aoauth2%253Agrant%253Adenied-by-server%2Finstances%2F42925fc9-7a7e-4cb0-95e4-4d3f178f68b7%3Fpersona%3Dprovider%26client%3Ddevjs%26tenant%3Dec2458f2-1e24-41c8-b71b-0e701af7583d
The following example is an error message response from an access token request:
{ "error": "invalid_grant", "error_uri": "https://authorization.cerner.com/errors/urn%3Acerner%3Aerror%3Aauthorization-server%3Aoauth2%3Atoken%3Acode-invalid-or-expired/instances/6359728c-c966-4929-bbf6-2388d353d89e?client=devjs&tenant=ec2458f2-1e24-41c8-b71b-0e701af7583d" }
In either circumstance, the Oracle Health authorization server communicates the error_uri
parameter, which represents a URI containing additional information useful for users, client application developers, and support personnel, with support contact information for the associated organization. In addition to your application’s support instructions displayed to the user, a More Information link or button that is hyperlinked to the value of the URI should be presented to the user. Your application can also display a Retry or Start Over mechanism so that the user can retry the operation once the problem is corrected.
Using Refresh Tokens
If your application is designed to interact with a user over periods of time longer than what a single access token allows, you must use refresh tokens. A refresh token is an additional secret value returned as part of the initial access token response that can be used to obtain additional access tokens. Two forms of access exist; each is requested as a special scope in the authorization grant request.
online_access
: Grants a refresh token that can be used during a user’s authenticated session. These refresh tokens are valid until the user explicitly logs out, an administrator terminates the session, or other risk mechanisms, such as timeouts, require a user to be reauthenticated.offline_access
: Grants a refresh token that can be used until a user or administrator revokes it, or until the token is revoked automatically because access is unused for more than three months.
As access tokens are valid for periods that are less than ten minutes, Oracle Health recommends retrieving and caching new tokens before the previous token expires. Doing so out-of-band of a user’s interaction reduces the perception of application latency. Refresh attempts at intervals lower than one minute may result in throttling. Using tokens that are near the precipice of expiry is not recommended because latency could result in token rejection.
Access Token Request and Response
See the following examples of the request-response mechanism defined in the Refreshing an Access Token section of The OAuth 2.0 Authorization Framework.
Request:POST /tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token HTTP/1.1 Host: authorization.cerner.com Accept: application/json Content-Type: application/x-www-form-urlencoded Content-Length: 75 Connection: close grant_type=refresh_token&refresh_token=b30911a8-9278-45aa-bbd9-aa05244faf3bResponse:
HTTP/1.1 200 OK Access-Control-Allow-Origin: * Access-Control-Allow-Methods: OPTIONS, POST Access-Control-Allow-Headers: Content-Type, Authorization Cache-Control: no-store Pragma: no-cache Content-Type: application/json Content-Length: 1514 Date: Tue, 01 Nov 2016 20:48:32 GMT { "access_token": "eyJraWQiOiIyMDIwLTA3LTI4VDE3OjM2OjA5LjAwNC5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3J0YWwiLCJ1cm46Y29tOmNlcm5lcjphdXRob3JpemF0aW9uOmNsYWltcyI6eyJ2ZXIiOiIxLjAiLCJ0bnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJhenMiOiJvbmxpbmVfYWNjZXNzIHVzZXJcL09ic2VydmF0aW9uLnJlYWQifSwiYXpwIjoiZmhpci1sb2NhbCIsImlzcyI6Imh0dHBzOlwvXC9hdXRob3JpemF0aW9uLmNlcm5lci5jb21cLyIsImV4cCI6MTU5NjA1NjIyOCwiaWF0IjoxNTk2MDU1NjI4LCJqdGkiOiI4YzdjNDBlMy00NDA0LTQ4MmMtYjY2MC0xOTFhNWQ1M2ViNjAiLCJ1cm46Y2VybmVyOmF1dGhvcml6YXRpb246Y2xhaW1zOnZlcnNpb246MSI6eyJ2ZXIiOiIxLjAiLCJwcm9maWxlcyI6eyJzbWFydC12MSI6eyJhenMiOiJvbmxpbmVfYWNjZXNzIHVzZXJcL09ic2VydmF0aW9uLnJlYWQifX0sImNsaWVudCI6eyJuYW1lIjoiRkhJUiBMb2NhbCBUZXN0IENsaWVudCIsImlkIjoiZmhpci1sb2NhbCJ9LCJ1c2VyIjp7InByaW5jaXBhbCI6InBvcnRhbCIsInBlcnNvbmEiOiJwcm92aWRlciIsImlkc3AiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJzZXNzaW9uSWQiOiIxYmJhMjhkNC01MDNmLTQ4MjYtODkxNy0yYTkyMzM3M2YxNmMiLCJwcmluY2lwYWxUeXBlIjoidXNlcm5hbWUiLCJwcmluY2lwYWxVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2luc3RhbmNlXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL3ByaW5jaXBhbFwvMDAwMC4wMDAwLjAwQzIuNkRCNSIsImlkc3BVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2FjY291bnRzXC9jMTk0MS5jZXJuX2FiY24uY2VybmVyYXNwLmNvbVwvZWMyNDU4ZjItMWUyNC00MWM4LWI3MWItMGU3MDFhZjc1ODNkXC9sb2dpbiJ9LCJ0ZW5hbnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QifX0.e0fhw5QGS_Nf2GQw5zdPOr79j-NQkk5pWQKuvXgo_jMW3Nwqi47KKrMF2eUkAtf9-_hyHEU_R6Ri8Je5FRfjoA", "scope": "user/Observation.read online_access", "token_type": "Bearer", "expires_in": 570 }
Note: The token response from a refresh does not contain a new refresh token. The refresh token from the initial grant response must be retained.
Considerations for Handling online_access
When retrieving an access token using an online_access
refresh, the most likely cause of failures is that the user’s session has been terminated.
The following steps are recommended for the user experience:
- Indicate that the user may have logged out, or that the server otherwise requires that they log in again.
- If your application was called through a launch, and the persona being serviced is a provider, direct the user to open the application again.
- Offer the user the opportunity to log in again (start the authorization grant workflow again) as appropriate.
- Offer a More Information link or button hyperlinked to the
error_uri
value.
Considerations for Handling offline_access
The Oracle Health authorization server can be used as an authentication mechanism by using the openid
scope. In this scenario, an offline access refresh token can be stored in your application’s service tier and associated with the user’s OpenID Connect principal and issuer. Upon subsequent access, the client application calls an authorization request containing the openid
scope to solely perform authentication. This authentication allows your service tier to identify the user and any refresh tokens your application currently possesses for the user.
Note: The Oracle Health authorization server currently does not support the stand-alone OpenID workflow for patient application use cases.
When retrieving an access token using an offline_access
refresh, the most likely cause of failures is that access has been suspended or revoked.
The following steps are recommended for the user experience:
- Indicate that the application’s access may have been suspended or revoked.
- Offer a More Information link or button hyperlinked to the
error_uri
value. - Offer the ability for the user to rerequest authorization for your client application.
Note: The authorization server does not explicitly indicate whether a token was revoked or suspended. As a result, additional recommendations are provided below to improve the overall interaction with the user.
The error_uri
used in the link or button should open a separate browser window. This function is recommended because the user has no callback or redirect mechanism to get back into the application once they perform an action. The error_uri
only provides an opportunity for the user to reapprove the application if it was temporarily suspended.
Also, your application should provide a dialog box to prompt the user for an action that coincides with their choice or action in the separate window. This dialog box should include options to retry the token refresh, request an entirely new authorization grant, and stop using the application (and log out, if necessary).
Note that the automatic suspension of a token can occur when the TLS or DNS information has changed since the original authorization. For example, if your application’s TLS certificate has expired, then your application’s refresh token is suspended. See the Application Registration Prerequisites for Developers section for additional information about TLS and DNS requirements.
Using Authorization
To use our API resources, include an Authorization header with your bearer token in the HTTP request per The OAuth 2.0 Authorization Framework: Bearer Token Usage.
See the following example request header:
Authorization: Bearer eyJraWQiOiIyMDIwLTA3LTI4VDE3OjM2OjA5LjAwNC5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3J0YWwiLCJ1cm46Y29tOmNlcm5lcjphdXRob3JpemF0aW9uOmNsYWltcyI6eyJ2ZXIiOiIxLjAiLCJ0bnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJhenMiOiJvbmxpbmVfYWNjZXNzIHVzZXJcL09ic2VydmF0aW9uLnJlYWQifSwiYXpwIjoiZmhpci1sb2NhbCIsImlzcyI6Imh0dHBzOlwvXC9hdXRob3JpemF0aW9uLmNlcm5lci5jb21cLyIsImV4cCI6MTU5NjA1NjIyOCwiaWF0IjoxNTk2MDU1NjI4LCJqdGkiOiI4YzdjNDBlMy00NDA0LTQ4MmMtYjY2MC0xOTFhNWQ1M2ViNjAiLCJ1cm46Y2VybmVyOmF1dGhvcml6YXRpb246Y2xhaW1zOnZlcnNpb246MSI6eyJ2ZXIiOiIxLjAiLCJwcm9maWxlcyI6eyJzbWFydC12MSI6eyJhenMiOiJvbmxpbmVfYWNjZXNzIHVzZXJcL09ic2VydmF0aW9uLnJlYWQifX0sImNsaWVudCI6eyJuYW1lIjoiRkhJUiBMb2NhbCBUZXN0IENsaWVudCIsImlkIjoiZmhpci1sb2NhbCJ9LCJ1c2VyIjp7InByaW5jaXBhbCI6InBvcnRhbCIsInBlcnNvbmEiOiJwcm92aWRlciIsImlkc3AiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJzZXNzaW9uSWQiOiIxYmJhMjhkNC01MDNmLTQ4MjYtODkxNy0yYTkyMzM3M2YxNmMiLCJwcmluY2lwYWxUeXBlIjoidXNlcm5hbWUiLCJwcmluY2lwYWxVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2luc3RhbmNlXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL3ByaW5jaXBhbFwvMDAwMC4wMDAwLjAwQzIuNkRCNSIsImlkc3BVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2FjY291bnRzXC9jMTk0MS5jZXJuX2FiY24uY2VybmVyYXNwLmNvbVwvZWMyNDU4ZjItMWUyNC00MWM4LWI3MWItMGU3MDFhZjc1ODNkXC9sb2dpbiJ9LCJ0ZW5hbnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QifX0.e0fhw5QGS_Nf2GQw5zdPOr79j-NQkk5pWQKuvXgo_jMW3Nwqi47KKrMF2eUkAtf9-_hyHEU_R6Ri8Je5FRfjoA
If the access token is invalid, the FHIR resource returns a WWW-Authenticate
header in the response with additional details per The OAuth 2.0 Authorization Framework: Bearer Token Usage.
User Experience
The next sections provide user experience recommendations to incorporate in your application’s design.
Handling the Authorization Request Window Being Closed
When presenting an authorization request to the user, the user might close the window. This scenario could occur if the user does not accept the terms or if the content is not displayed.
In this scenario, your application detects if the window closes and allows the user to try again or to cancel, explaining any consequences.
Providing a Link to Manage Authorized Applications
If your application is interactive and uses online_access
or offline_access
, it presents an option to the user to manage their current authorizations. Generally, such options are presented with a menu from a status bar.
See the Discovery section under the FHIR Service Authorization Specification v1.0 for information on how to discover the management endpoint for a user.
Requesting Authorization on Behalf of a System
Certain types of applications and automated processes do not act on behalf of users. This use case is used by a covered entity itself or another entity covered under a business associate agreement.
Some Oracle Health APIs support this model, allowing a client application to directly authenticate for access using a system account issued through Cerner Central System Account Management.
See the Registering a System Account section for more information on how to register these applications.
Note: This access model is only supported on resources where explicitly indicated in their respective API resource documentation.
Basic Authentication
A customer performs this request using the customer credentials flow of OAuth2 to request an access token, using the Basic authentication scheme as described in RFC 2617 - HTTP Authentication: Basic and Digest Access Authentication. The credentials used to perform this request are based on the system account.
Create the access token using the system account’s ID and secret, which are then encoded using the Base64 encoding scheme. The token can then be used as the Basic authorization for an API request.
The following example is an access token using the Basic authentication scheme:
System account id / Client id: bb318a62-fa61-49ae-b692-7d99214f0ec7 Secret: secret Base64 encode "clientid:secret": "bb318a62-fa61-49ae-b692-7d99214f0ec7:secret" => YmIzMThhNjItZmE2MS00OWFlLWI2OTItN2Q5OTIxNGYwZWM3OnNlY3JldA== Use this value in Authorization header: Authorization: Basic YmIzMThhNjItZmE2MS00OWFlLWI2OTItN2Q5OTIxNGYwZWM3OnNlY3JldA==
The following non-normative example is a request made using the system account credentials:
POST /tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token HTTP/1.1 Host: authorization.cerner.com Authorization: Basic YmIzMThhNjItZmE2MS00OWFlLWI2OTItN2Q5OTIxNGYwZWM3OnNlY3JldA== Accept: application/json Content-Type: application/x-www-form-urlencoded Content-Length: 61 Connection: close grant_type=client_credentials&scope=system%2FObservation.read%20system%2FPatient.read
The following example demonstrates how the token may be requested through cURL:
export SYSTEM_ACCOUNT_CLIENT_ID="bb318a62-fa61-49ae-b692-7d99214f0ec7" export SYSTEM_ACCOUNT_CLIENT_SECRET="secret" curl -X POST 'https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token' \ -H 'Accept: application/json' \ -H "Authorization: Basic $(echo -n $SYSTEM_ACCOUNT_CLIENT_ID:$SYSTEM_ACCOUNT_CLIENT_SECRET | base64)" \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'cache-control: no-cache' \ -d 'grant_type=client_credentials&scope=system%2FObservation.read%20system%2FPatient.read'
JWT Authentication
Alternatively, client applications may authenticate themselves using signed JSON Web Tokens (JWTs), which is the appropriate mode of authentication for Bulk Data Access.
See Bulk Data Access and SMART App Launch: Backend Services on the HL7 FHIR website for more information.
Note that client applications using this type of authentication must also preregister their JSON Web Key Sets (JWKS) using Cerner Central System Account Management. For complete details, see Managing JSON Web Key Sets in System Account Management.
FHIR Service Authorization Specification v1.0
SMART on FHIR is a framework designed to enable the secure integration of applications with electronic health records (EHRs), portals, health information exchanges (HIEs), and other health IT systems through the FHIR standard. This document codifies a formal technical specification based on the open source SMART on FHIR framework. This specification is targeted at both client application developers and developers of EHRs for securely consuming and securely offering FHIR services, respectively.
License
This document is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Introduction
Within the healthcare environment, multiple actors may be involved with an individual’s health record. When an application needs to access data in an EHR through a FHIR service, it may need to interact (directly or indirectly) with one or more of these actors to obtain authorization to perform work.
The SMART on FHIR framework standardizes the mechanisms under which an application obtains authorization to the following types of resources:
- Clinical information.
- Contextual information for the resources currently of interest to an individual accessing the EHR.
- Identity information for the individual currently accessing the EHR.
To orchestrate this interaction, SMART on FHIR defines a set of authorization profiles and extensions for The OAuth 2.0 Authorization Framework.
Terminology
The following terms are used in this specification:
- Application: Synonymous with client or SMART application, a piece computer software designed to use FHIR services to orchestrate an activity for the user.
- Electronic Health Record (EHR): Computer software designed to store and process information about a person’s health information, such as medications, allergies, medical history, and so on. The EHR acts as a resource server by providing FHIR services, is responsible for authenticating end users, and is responsible for providing an authorization server.
- Healthcare Institution: An organization that operates an EHR for use in providing healthcare to a population of users and is responsible for policy decisions regarding the use of the record. The healthcare institution has ultimate ownership of the information in the EHR, but in certain cases may delegate the role of resource ownership to end users.
- Patient: An individual whose personal health information is stored in the EHR. A patient may also be the end user, acting in the capacity of a resource owner.
- EHR Application: A piece of computer software that is directly part of the EHR implementation and tracks the end user’s current context.
Notational Convention
The key words “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” in this document are to be interpreted as described in Key Words for Use in RFCs to Indicate Requirement Levels.
Unless otherwise noted, all the protocol parameter names and values are case-sensitive.
Specification
SMART on FHIR describes the following types of workflows:
- Contextless Flow: Used where a SMART application seeks to acquire authorization to access clinical information and does not require context from the EHR.
- EHR Launch Flow: Used by an EHR application to pass a specific context to a SMART application, which in turn attempts to acquire authorization from the EHR.
- SMART Application Launch Flow: Used by a SMART application to request context and authorization from an EHR to access resources.
Contextless Flow
Figure 1: SMART Application Contextless Flow Diagram
In Figure 1, the following workflow is described:
- The end user begins a workflow in the SMART application that requires access to FHIR resources. The SMART application has either been preconfigured to work with a specific FHIR resource server, or the user has instructed the SMART application as to the location of the FHIR resource server, or the application is accessing a record it had previously accessed.
- The SMART application performs discovery by requesting the FHIR server’s conformance statement.
- The FHIR server returns the conformance statement, which provides the needed endpoints for Steps 4 and 8.
- The SMART application creates an OAuth 2.0 authorization grant request, then directs the end user to the authorization server’s authorization endpoint through a browser with said request. This request contains a request for the appropriate scopes necessary to access the FHIR resource.
- The authorization server interacts with the resource owner to verify identity or other information required by the authorization server.
- The end user provides any information needed by the authorization server to proceed.
- An authorization grant is sent through the OAuth 2.0 framework back to the SMART application.
- The SMART application requests an access token using the authorization code.
- The authorization server returns the access token.
- The SMART application uses the access token to request a FHIR resource.
- The FHIR resource server returns the requested resource.
Usage
The contextless flow constitutes the most basic use of SMART workflows and is used where the FHIR resource needed by the SMART application is already known.
Such scenarios include the following examples:
- The application is provided context through some other means, such as a system-generated hyperlink to the application.
- The resource was previously used by the application, but access has expired and a new request for authorization needs to be generated.
Contextless Flow Authorization Request
SMART applications SHALL use an authorization code grant to request authorization to FHIR resources. A SMART application SHOULD request scopes needed to access the resource (per the Scopes section of this topic) for maximum interoperability. The application MAY omit the redirect URI, as SMART registration requires a default redirect URI.
In addition, SMART applications MUST send the state
parameter, as detailed in the OAuth 2.0 Threat Model and Security Considerations.
SMART applications that are written natively for a platform SHOULD use the operating system’s default browser when performing the authorization request such that the authorization server may comply with any security controls that are imparted upon it.
Such controls may include the following examples:
- Support for single sign-on.
- Support for anti-phishing controls implemented through persistent browser state or browser plug-ins.
- Support for external native applications for sign-on.
- External regulatory requirements that would prohibit user credentials from being entered through an embedded browser in the SMART application.
Such “native” applications MAY support orchestrating the authorization flow in an embedded browser where requested out-of-band by the EHR provider.
Contextless Flow Authorization Response
Authorization servers SHALL return an OAuth 2.0 authorization code grant to exchange authorization with the SMART application. Authorization servers MAY ask the end user for explicit approval to allow the SMART application to complete this workflow.
Contextless Flow Access Token Request
SMART applications SHALL use an access token request as described in the Access Token Request section of The OAuth 2.0 Authorization Framework. The authorization server MAY conditionally require customer authentication, depending on the use case.
Contextless Flow Access Token Response
Authorization servers SHALL use an access token response as described in the Access Token Response section of The OAuth 2.0 Authorization Framework to respond to the SMART application’s request. As part of the token response, authorization servers SHALL support the return of an id_token
where requested and authorized containing a minimal set of identity data, as described in the User Identity section.
Contextless Flow Resource Server Request
To request a FHIR resource, SMART applications SHALL send the bearer token as an authorization header, as defined in the Authorization Request Header Field section of The OAuth 2.0 Authorization Framework: Bearer Token Usage.
EHR Launch Flow
Figure 2: EHR Launch Flow Diagram
In Figure 2, the following workflow is described:
- The end user selects to open a SMART application from within an EHR application.
- The EHR directs the user to a URI endpoint registered for the SMART application containing a reference to the current context information, and the location of the EHR’s FHIR API.
- The SMART application performs discovery by requesting the FHIR server’s conformance statement.
- The FHIR server returns the conformance statement, which provides the needed endpoints for Steps 5 and 9.
- The SMART application creates an OAuth 2.0 authorization grant request, then directs the end user to the authorization server’s authorization endpoint through a browser with said request. This request contains a request for the appropriate scopes necessary to access the FHIR resource.
- The authorization server interacts with the resource owner to verify identity or other information required by the authorization server.
- The end user provides any information needed by the authorization server to proceed.
- An authorization grant is sent through the OAuth 2.0 framework back to the SMART application.
- The SMART application requests an access token using the authorization code.
- The authorization server returns the access token.
- The SMART application uses the access token to request a FHIR resource.
- The FHIR resource server returns the requested resource.
EHR Launch Request
In the EHR application launch flow, the end user opens a SMART application from the EHR. To receive such a launch, the SMART application implements an endpoint at a specific URI that accepts the following query parameters:
iss
: Identifies the EHR’s FHIR endpoint, which the application can use to obtain additional details about the EHR, including its authorization URL.launch
: An opaque identifier for this specific launch and any EHR context associated with it.
Normative example:
https://example.org/launch?iss=https%3A%2F%2Fehr%2FFHIR&launch=ef1e6860-db06-4572-b311-02881d01d03d
The syntax for such launch
codes is defined in Appendix A.3. Launch Code Syntax. The syntax for the iss
value is defined in Appendix A.4. Launch Issuer Syntax.
EHR Launch Flow Authorization Request
Upon receipt of a launch context, a SMART application SHALL initiate an authorization grant request to the EHR’s authorization server as previously described in the Contextless Flow section. The SMART application SHALL include the following extension parameters with the request:
aud
: The value of the issuer parameter received by the SMART application from the EHR launch request.launch
: The value of the launch parameter received by the SMART application from the EHR launch request.
In addition, the SMART application MUST include the scope of launch
as indicated in the Resource Server Request section.
EHR Launch Flow Authorization Response
Authorization servers SHALL return an OAuth 2.0 authorization code grant to exchange authorization with the SMART application. Authorization servers SHOULD reject the request if the authorization code is not associated with the current user. This step prevents cross-site request forgery of SMART application launches.
Upon successful authorization, the authorization server SHALL associate the resulting authorization code with the context information associated with the launch code for retrieval through an access token request.
EHR Launch Flow Access Token Request
SMART applications SHALL use an access token request as described in the Access Token Request section of The OAuth 2.0 Authorization Framework.
EHR Launch Flow Access Token Response
When the SMART application exchanges the authorization code for an access token, the authorization server SHALL return the associated context information as parameters in the token response.
The following custom parameters are defined by this specification:
Parameter | Example value | Meaning |
---|---|---|
patient |
123 |
A string value with a patient ID, indicating that the launch was in the context of FHIR Patient 123. All scopes with a resource context of patient are constrained to Patient 123. |
encounter |
123 |
A string value with an encounter ID, indicating that the launch was in the context of FHIR Encounter 123. |
resource |
MedicationPrescription/123 |
A string value with a relative resource link, describing a specific resource context (in this example, a particular medication prescription). This parameter is a generic mechanism to communicate to an application that a particular resource is of interest at launch time. |
intent |
reconcile-medications |
A string value describing the intent of the application launch. |
Launch Intent
Some SMART applications might offer more than one context or user interface that can be accessed during the EHR launch. An authorization server MAY include the intent parameter to communicate the specific user interface that the SMART application should display.
Launch intent values are not defined by this specification, but most conform to the syntax defined in Appendix A.5. Launch Intent Syntax. Such values and their associated semantics are decided through out-of-band agreement between SMART applications and EHR implementations.
EHR Launch Flow Resource Server Request
SMART applications use the bearer token from the token response as described in the Contextless Flow section to access resources.
SMART Application Launch Flow
Figure 3: SMART Launch Flow Diagram
In Figure 3, the following workflow is described:
- The end user selects an option in a SMART application to retrieve context from the EHR application.
- The SMART application performs discovery by requesting the FHIR server’s conformance statement. The mechanism for how the SMART application is provided the URL for the FHIR server is not defined by this specification.
- The FHIR server returns the conformance statement, which provides the needed endpoints for Steps 4 and 8.
- The SMART application creates an OAuth 2.0 authorization grant request, then directs the end user to the authorization server’s authorization endpoint through a browser with said request. This request contains a request for the appropriate scopes necessary to access the FHIR resource, with scopes to request the specific types of context information.
- The authorization server extrapolates the current context in the EHR for the user. This process may involve direct interaction with the user to confirm such context, or to prompt the user to establish context, or to authenticate the user.
- The user confirms or establishes the necessary context for the authorization server.
- An authorization grant is sent through the OAuth 2.0 framework back to the SMART application.
- The SMART application requests an access token using the authorization code.
- The authorization server returns the access token.
- The SMART application uses the access token to request a FHIR resource.
- The FHIR resource server returns the requested resource.
SMART Application Launch Flow Authorization Request
In the SMART application launch flow, the end user initiates an action in a SMART application that requires access to context in the EHR. The SMART application in some way is supplied the base URL for the FHIR service of the EHR; the details of such provisioning are not defined by this specification. After performing discovery, the SMART application SHALL initiate an authorization grant request to the EHR’s authorization server as described previously in the Contextless Flow section.
The SMART application SHALL include one or more scopes that convey the information that is needed for launch as defined in the Scopes section of this topic.
SMART Application Launch Flow Authorization Response
The authorization server returns a response as described in the Contextless Flow section.
Upon successful authorization, the authorization server SHALL associate the resulting authorization code with the current context information.
SMART Application Launch Flow Access Token Request
SMART applications SHALL use an access token request as described in the Access Token Request section of The OAuth 2.0 Authorization Framework.
SMART Application Launch Flow Access Token Response
The authorization server returns a response as described previously in the Contextless Flow section.
SMART Application Launch Flow Resource Server Request
SMART applications use the bearer token from the token response as described previously in the Contextless Flow section to access resources.
Client Credentials Flow
Figure 4: Client Credentials Flow Diagram
In Figure 4, the following workflow is described:
- The SMART application performs discovery by requesting the FHIR server’s conformance statement. The mechanism for how the SMART application is provided the URL for the FHIR server is not defined by this specification.
- The FHIR server returns the conformance statement, which provides the needed endpoint for Step 3.
- The SMART application requests an access token using its credentials.
- The authorization server returns the access token.
- The SMART application uses the access token to request a FHIR resource.
- The FHIR resource server returns the requested resource.
Client Credentials Flow Access Token Request
SMART applications SHALL use an access token request as described in the Access Token Response section of The OAuth 2.0 Authorization Framework. The application MUST include credentials; it is RECOMMENDED that authorization servers support basic authentication per HTTP Authentication: Basic and Digest Access Authentication, and MAY offer other authentication mechanisms to customers.
Client Credentials Flow Access Token Response
The authorization server returns a response as described previously in the Contextless Flow section.
Client Credentials Flow Resource Server Request
SMART applications use the bearer token from the token response as described previously in the Contextless Flow section.
Scopes
To obtain access to resources, an application must request the set of scopes necessary for it to perform work on behalf of the end user.
The SMART on FHIR framework describes the following distinct collections of scopes:
- Resource access
- Access to identity information
- Requests for launch information
- Longevity modifiers
Resource Access
A request to access a collection of FHIR resources consists of one or more SMART scopes.
Each SMART scope is constructed per the structure defined in Appendix A.1. Resource Scope Syntax and contains the following elements:
- Resource Context: The context in which rights are being requested, described in the Resource Context section.
- Resource Type: A FHIR resource type whose name is constrained by
Name
. - Modification Rights: The rights to read, write, or both to the given type-level or instance-level resources.
Resource Context
The following contexts are defined:
- User: User access allows an application access to any individual resource instance that the authenticated end user is authorized to access.
- Patient: Patient access restricts an application’s access to only the individual resource instances that are associated with the patient who is directly or indirectly in context. Requests for such scopes may only occur with the use of a launch flow.
- System: System access allows an application to access a resource directly, without an authenticated user present. This access can only be used with the client credentials flow, and MUST NOT be combined with other contexts.
Resource Type
The resource type of a resource scope must conform with a valid resource type as defined in the FHIR Resource Index.
Modification Rights
The following modifications rights are defined:
- Read: Corresponds with “read,” “vread,” and “history” for instance-level interactions as defined by the FHIR RESTful API specification. When the resource context is User, type-level interactions of “search” and “history” are also allowed.
- Write: Corresponds with “update” and “delete” for instance-level interactions. When the resource context is User, type-level interactions of “create” and “validate” are also allowed.
- __*:__ Corresponds with both read and write access, as defined above. This modification right is not supported in the Oracle Health implementation.
Examples
The following scopes are normative examples of the resource scopes:
Scope | Authorizes Access to |
---|---|
patient/Observation.read |
Read all observations about the patient in context. |
patient/Observation.write |
Add new observations about the patient, such as new blood pressure readings. |
user/Observation.read |
Read a feed of all new laboratory observations across a patient population. |
user/Appointment.write |
Add new appointments for the user. |
system/Patient.read |
Read all patient records accessible to the given client using its own credentials. |
Scopes for Identity Information
The following scopes are defined for requesting identity information:
openid
: Requests that an OpenID Connectid_token
be returned with the access token.fhirUser
: Requests access to the FHIR resource that represents the user, and that the location of said resource is returned in the OpenID token.
See the User Identity section for more information on how to use the identity information.
Scopes for Launch Information
When servicing a launch request, a SMART application MUST include the scope of launch
in its list of requested scopes.
For SMART applications performing the SMART Application Launch Flow, the following scopes are defined by this specification:
Scope | Requests context |
---|---|
launch/patient |
Requests the EHR to provide context regarding a patient. |
launch/encounter |
Requests the EHR to provide context regarding an encounter. |
An EHR MAY support additional custom launch scopes. When doing so, the scope name must conform to the syntax defined in Appendix A.2. Launch Scope Syntax.
Scopes for Longevity
SMART on FHIR provides a mechanism for a client application to request a longevity for the access that is being requested. Without such modifiers, no assumptions can be made about how long access may be granted. A given authorization server SHOULD generate access tokens that have short lifetimes by default, and provide a refresh token where longer access is explicitly requested.
To request longevity, a SMART application MAY include one of the following scopes:
online_access
: Where authorized, the authorization server SHALL provide a refresh token that may be used to obtain new access tokens as long as the user has an active session with the EHR.offline_access
: Where authorized, the authorization server SHALL provide a refresh token that may be used to obtain new access tokens even when the user is no longer authenticated. This refresh token remains valid until individually revoked at the authorization server or until the SMART application’s relationship with the EHR is terminated.
These scopes MUST NOT be used with the client credentials flow, as they are not applicable to that use case.
Disambiguation of Scopes Between Competing Protocols
If an authorization request is used with a protocol that defines a competing scope, a SMART application or authorization server MAY prepend the following prefix to a scope:
http://smarthealthit.org/FHIR/scopes/
Normative example:
http://smarthealthit.org/FHIR/scopes/user/Observation.read
Applications and authorization servers MUST consider the fully qualified scope names semantically equivalent to the shorthand versions where no conflicts exist with other values. For example, an authorization server MAY return the fully qualified scopes in the authorized access token response in response to the short-hand versions being used.
Note: The openid
and fhirUser
scopes are defined by the OpenID Connect specification, which does not define a prefix.
User Identity
SMART on FHIR allows for identity information about the end user to be obtained through an OpenID Connect Core 1.0 Incorporating Errata Set 1 identity token. SMART applications MAY request such identity information by requesting the scope of openid
during its authorization request. Authorization servers MUST provide an id_token
as part of the access token response if the SMART application is authorized to obtain the information.
OpenID Connect Identifier Permanency
The authorization server MUST include a permanent URL for the issuer (iss
) value of the token. The URL MUST NOT contain path segments that vary over time, such as version information for the FHIR or SMART protocol being used. The value of the subject (sub
) of the id_token
must be a permanent identifier for the end user, whose value is stable. SMART applications MUST treat the combination of issuer and subject as the universally unique identifier for the end user.
Nonrepudiation of OpenID Connect id_tokens
The authorization server SHALL sign the id_token
per the OpenID Connect specification using the RS256 algorithm.
The authorization server SHALL make its public keys available as described in OpenID Connect Discovery 1.0 Incorporating Errata Set 1, incorporating both an OpenID Provider Configuration document and a JSON Web Key document describing the public keys used to sign tokens.
SMART applications MUST validate the token per the token validation section of OpenID Connect Core 1.0 Incorporating Errata Set 1.
fhirUser Resource
In addition to the to requesting access to the user’s OpenID identity, a SMART application MAY request access to the FHIR resource that represents the user through the addition of the fhirUser
scope. The authorization server SHALL fulfill such by including a fhirUser
claim in the id_token
.
An EHR MAY include the URI of the user’s FHIR resource. This resource may be a Patient, Practitioner, RelatedPerson, or Person resource as described by the FHIR Specification. SMART applications that want to retrieve that resource MUST explicitly include the relevant scopes when requesting their access tokens.
Client Authentication
To mitigate the risk of compromised refresh tokens, SMART applications SHOULD leverage client authentication when storing such refresh tokens outside of the client component of their application (for example, storing in a central database, in memory on an application server, and so on). This authentication ensures that if such refresh tokens are compromised, then the tokens do not need to be revoked. If the client’s credentials are stolen in addition to the tokens, a client application needs only to revoke its previous credentials with EHRs.
Registration
A SMART application that uses the Contextless Flow, EHR Launch Flow, or SMART Application Launch Flow MUST supply the following information when registering with an EHR:
- The application’s
launch
URL. - The application’s redirection URI for receiving authorization code grants.
Exception Conditions
During the processes of obtaining access tokens and using access tokens, exceptions can occur.
The following conditions can cause exceptions:
- The SMART application is not registered with the given EHR.
- The SMART application’s access to an EHR is suspended.
- The end user’s access is suspended.
- The end user has terminated the SMART application’s access or has logged off.
- The end user did not have sufficient privileges to access a specific resource.
- Internal errors in the EHR system.
Usually, the EHR system has the most information about the cause of the failure, and is in the best position to offer assistance to the user or individuals who support the SMART application. As such, it is RECOMMENDED that authorization servers and resource servers use the error_uri
parameter as detailed in the following specifications:
- 4.1.2.1 Error Response section of The OAuth 2.0 Authorization Framework
- 5.2 Error Response section of The OAuth 2.0 Authorization Framework
- The WWW-Authenticate Response Header Field section of The OAuth 2.0 Authorization Framework: Bearer Token Usage
SMART applications that receive such information in error responses SHOULD present such links to end users.
It is RECOMMENDED that such links provide actionable instructions for the end user or for individuals who are supporting the SMART application. It is RECOMMENDED for SMART applications to provide a mechanism to retry a specific action after an error to assist users in recovering from transient error conditions.
Security Considerations
- It is RECOMMENDED that EHRs issue access tokens for short durations (for example, ten minutes or less) to minimize the window in which a compromised token could be exercised. Otherwise, an EHR SHOULD provide mechanisms accessible to administrators and end users to revoke tokens in the event of a security incident.
- Authorization servers MUST NOT use the value of the launch code as a mechanism for passing an authenticated state. Doing so opens the possibility to a session injection attack, and could open the possibility of a session fixation attack.
- SMART applications MUST assure that sensitive information (authentication secrets, authorization codes, tokens, PHI) are transmitted ONLY to authenticated servers, over TLS-secured channels.
- Resource servers MUST be TLS-secured.
- All use of TLS MUST incorporate the best current practices for transport layer security described in Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). EHRs and SMART applications SHOULD continue to incorporate updates to current practices and SHOULD document their policies for staying current.
Authorization Server OpenID Connect Support
OpenID Connect describes itself as, “a simple identity layer on top of the OAuth 2.0 protocol.” The specification provides a set of message structures, a messaging protocol, and a security framework to allow a system that has authenticated a user to securely convey said identity to another service provider (relying party). The Oracle Health authorization server implements support for OpenID Connect with the SMART on FHIR profile of OAuth 2. Client applications may use this as a source of single sign-on (SSO) for users when protecting resources outside of the EHR (for example, user-generated data that is stored by the client application).
In addition to SSO, SMART on FHIR also leverages OpenID Connect to convey the location of the authenticated user’s FHIR endpoint, as described by the HL7 FHIR standard.
Requesting OpenID Connect
Per OpenID Connect and SMART on FHIR, a client application requests the scope of openid
to receive an identity token in the access token response.
Identifying the User
Upon retrieving an access token, an identity token is presented in the access token response. These tokens are parsed as JSON Web Tokens per the OpenID Connect specification.
The following values in the identity tokens are important for identifying the user:
- Issuer (
iss
) - Subject (
sub
)
The subject value of the identity assertion corresponds with the user identifier asserted by the authentication system being used, locally unique in context of the issuer. This value may be a user’s username or an opaque identifier (such as a UUID), depending on the tenant’s identity strategy. Both the issuer and subject value combined constitute a globally unique identifier for the authenticated user.
User identifiers remain permanent, except in the following conditions:
- The EHR switches a group of users to use a new authentication system.
- A user’s identifier is changed in the upstream authentication system.
- The organization changes EHR systems.
OpenID Connect and SMART on FHIR do not prescribe mechanisms for addressing the above scenarios. As such, application developers should consider proprietary mechanisms for handling such scenarios if critical user information is managed outside of the EHR.
Validating OpenID Connect Identity Tokens
The client application receiving the identity token must validate that the audience (aud
) claim matches its own client identifier per the ID Token Validation section of OpenID Connect Core.
For applications interoperating only with the Oracle Health authorization server, no explicit signature validation is required when retrieving the access token directly from the token endpoint (as advertised in the FHIR Conformance document).
For applications that interoperate with multiple implementations, or are distributed in nature, identity tokens should be verified (including signature) per the ID Token Validation section of OpenID Connect Core.
Signing keys may be retrieved through the following steps:
- Retrieve the OpenID Provider configuration information per the OpenID Provider Configuration Request section of OpenID Connect Discovery.
- Extract the URI of the JSON Web Key Set (
jwks_uri
). - Examine the ID of the JSON Web Key used to sign the OpenID Connect token, and retrieve it from the JSON Web Key Set.
The following access token response is an example containing an OpenID Connect identity token:
{ "access_token": "eyJraWQiOiIyMDIwLTA4LTE1VDE3OjM2OjE0Ljg1Ni5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3J0YWwiLCJ1cm46Y29tOmNlcm5lcjphdXRob3JpemF0aW9uOmNsYWltcyI6eyJ2ZXIiOiIxLjAiLCJ0bnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJhenMiOiJvcGVuaWQgcHJvZmlsZSB1c2VyXC9QYXRpZW50LnJlYWQifSwiYXpwIjoiZmhpci1sb2NhbCIsImlzcyI6Imh0dHBzOlwvXC9hdXRob3JpemF0aW9uLmNlcm5lci5jb21cLyIsImV4cCI6MTU5NzYyNjgxOCwiaWF0IjoxNTk3NjI2MjE4LCJqdGkiOiIzNGRkZWZiMC0wMzU5LTQwOTctYWJiZS00ZTk2YWFlY2NhNjUiLCJ1cm46Y2VybmVyOmF1dGhvcml6YXRpb246Y2xhaW1zOnZlcnNpb246MSI6eyJ2ZXIiOiIxLjAiLCJwcm9maWxlcyI6eyJzbWFydC12MSI6eyJhenMiOiJvcGVuaWQgcHJvZmlsZSB1c2VyXC9QYXRpZW50LnJlYWQifX0sImNsaWVudCI6eyJuYW1lIjoiRkhJUiBMb2NhbCBUZXN0IENsaWVudCIsImlkIjoiZmhpci1sb2NhbCJ9LCJ1c2VyIjp7InByaW5jaXBhbCI6InBvcnRhbCIsInBlcnNvbmEiOiJwcm92aWRlciIsImlkc3AiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QiLCJzZXNzaW9uSWQiOiIxYjBhZDY3Mi1mZjRmLTRiYzItYTNhNi05ZmUzOWI2N2JiZWIiLCJwcmluY2lwYWxUeXBlIjoidXNlcm5hbWUiLCJwcmluY2lwYWxVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2luc3RhbmNlXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL3ByaW5jaXBhbFwvMDAwMC4wMDAwLjAwQzIuNkRCNSIsImlkc3BVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLmNlcm5lci5jb21cL2FjY291bnRzXC9jMTk0MS5jZXJuX2FiY24uY2VybmVyYXNwLmNvbVwvZWMyNDU4ZjItMWUyNC00MWM4LWI3MWItMGU3MDFhZjc1ODNkXC9sb2dpbiJ9LCJ0ZW5hbnQiOiJlYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2QifX0.-ZfKiTNE2mv28HnussbTu4T3Pq9r_UPo1wYCHu46L6KO9objSEfUJKV4SA8JYoMtBwlH85DoR26Btl5fZ5zK4g", "scope": "openid fhirUser user/Patient.read", "id_token": "eyJraWQiOiIyMDIwLTA4LTE1VDE3OjM2OjE0Ljg1OS5yc2EiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJwb3J0YWwiLCJhdWQiOiJmaGlyLWxvY2FsIiwicHJvZmlsZSI6Imh0dHBzOlwvXC9maGlyLWVoci1jb2RlLmNlcm5lci5jb21cL2RzdHUyXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL1ByYWN0aXRpb25lclwvMTI3NDIwNjkiLCJpc3MiOiJodHRwczpcL1wvYXV0aG9yaXphdGlvbi5jZXJuZXIuY29tXC90ZW5hbnRzXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL29pZGNcL2lkc3BzXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcLyIsIm5hbWUiOiJQb3J0YWwsIFBvcnRhbCIsImV4cCI6MTU5NzYyNjgxOCwiaWF0IjoxNTk3NjI2MjE4LCJmaGlyVXNlciI6Imh0dHBzOlwvXC9maGlyLWVoci1jb2RlLmNlcm5lci5jb21cL2RzdHUyXC9lYzI0NThmMi0xZTI0LTQxYzgtYjcxYi0wZTcwMWFmNzU4M2RcL1ByYWN0aXRpb25lclwvMTI3NDIwNjkifQ.N-5R_9mZ2zmJGTiiwkPhnhOCbjpod9ghjQFuSK4imUNwYI-9po3eyjPB1IcZKkFCEZ0flZRZ8vmEUgj5EyMPA8xdiXPo5C3PQDMbKMw1wm_5nS95XGKNBNBgaQ7Nff69nRF4i4y9IhMO9ndxA7VtNCqP3NnxpeOXLCov-yl7zGlZLKJZ3DTQpBGhWOrWuH16Usk1UuXFp7-6Ih4e6DKkooJyUedEY0_fJ6i36_4xrFZ9D6wlP6F5F3hWbkTbrFEN239jnie8f-tr-mGr0r-KaxQqpG1pa_6UofopK7ngT_Guh46Ib0bUrgTlYDJ5EUDETIjvAwR3kA_2pPgJHfwjaw", "token_type": "Bearer", "expires_in": 570 }
The claims of the identity token in the above example are as follows:
{ "sub": "portal", "aud": "94bbd90d-482a-4a10-b7df-b40edb278da2", "fhirUser": "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Practitioner/12742069", "iss": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/", "name": "Portal, Portal", "exp": 1597626818, "iat": 1597626218, "fhirUser": "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Practitioner/12742069" }
In this example, the user identifier is portal
, the issuer is https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/
, and the recipient client ID is 94bbd90d-482a-4a10-b7df-b40edb278da2
.
The following URL is an example for the location of an OpenID Connect configuration document, derived from the issuer in the above id_token
:
https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/.well-known/openid-configuration
The following example is the content of the configuration document:
{ "response_types_supported": ["code"], "request_parameter_supported": false, "require_request_uri_registration": false, "request_uri_parameter_supported": true, "claims_parameter_supported": false, "jwks_uri": "https://authorization.cerner.com/jwk", "subject_types_supported": ["public"], "id_token_signing_alg_values_supported": ["RS256"], "issuer": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/", "authorization_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/", "token_endpoint": "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/oidc/idsps/ec2458f2-1e24-41c8-b71b-0e701af7583d/" }
In this example, the jwks_uri
is https://authorization.cerner.com/jwk
.
Managing a Session
SMART on FHIR currently does not prescribe mechanisms for managing a session state between applications, or providing a sign-out experience for users.
Guidance for the Use of TLS With Oracle Health FHIR APIs
All HL7 FHIR and HL7 SMART endpoints offered by Oracle Health use the Secure HyperText Transfer Protocol (HTTPS) to ensure the confidentiality and integrity of data transmissions. Oracle Health RECOMMENDS that application developers also use HTTPS for protecting their own application endpoints.
The HTTPS protocol relies on public key infrastructure (PKI) as the means by which client applications can verify the authenticity of each remote service endpoint. This document provides guidance to developers on how to use HTTPS and PKI with Oracle Health services.
Establishing TLS Connections to Oracle Health
The requirements and recommendations below apply to any software connecting to the Oracle Health implementation of HL7 FHIR or HL7 SMART.
Supported Versions of HTTP
Oracle Health currently supports the HTTP 1.1 protocol. Connectivity to certain endpoints using newer versions MAY be technically possible, but are not guaranteed to be available in all service deployments.
TLS Versions and Cipher Suites
Oracle Health ascribes to follow all best current practices (BCPs) published by the IETF.
The following BCPs are included:
- Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
- Deprecating TLS 1.0 and TLS 1.1
As of this writing, these best current practices dictate the use of TLS versions 1.2 and 1.3, with a recommended suite of minimum encryption cipher suites.
Oracle Health RECOMMENDS one of the following actions to developers:
- Use an evergreen TLS implementation that similarly implements best current practices. For example, most operating systems provide implementations that maintain best practices through automated patching. Similarly, browser-based applications benefit from the browser’s built-in TLS implementation, in which most browsers are delivered in an evergreen fashion to end users.
- Maintain patching of the application’s TLS implementation to stay current with best practices.
Certificate Chain Validation Process
Developers writing software that interoperates with the Oracle Health HL7 FHIR and HL7 SMART components should use HTTPS implementations that implement RFC 6125 for certificate validation.
Trusted Certificate Authorities
Oracle Health relies on public PKI systems (specifically, certificate authorities participating in the CA/Browser Forum) as the means by which it identifies its services to customers and third-party applications. Multiple vendors of operating systems, browsers, and other layered software components publish their own vetted list of certificate authorities that participate in the CA/Browser Forum.
Oracle Health REQUIRES developers to choose one or more vetted sources of certificate authorities that participate in the CA/Browser Forum to trust within their application, as Oracle Health does not guarantee it will source certificates from any one specific certificate authority.
Oracle Health RECOMMENDS the use of any of the following programs that provide vetted certificate authority lists:
- Common CCADB
- Microsoft Trusted Root Program
- Chrome Root Program
- Oracle Java Root Certificate Program
- Apple Root Certificate Program
Developer-Operated TLS Endpoints
Most applications integrating with the Oracle Health implementations of HL7 FHIR and HL7 SMART have endpoints that receive communication from browsers or Oracle Health software.
Examples include, but are not limited to:
- Web-based SMART Launch applications that render markup to a user’s browser through an HTTPS endpoint.
- SMART Backend Services applications that publish their JSON Web Key Sets through an HTTPS endpoint.
- CDS Hooks services that receive publications from Oracle Health CDS Hooks infrastructure through an HTTPS endpoint.
Supported Versions of HTTPS
Oracle Health REQUIRES developers to support the HTTPS 1.1 protocol.
TLS Versions and Cipher Suites
Oracle Health RECOMMENDS developers use an evergreen TLS implementation to protect HTTPS endpoints. Developers MUST use an implementation that supports current IETF best practices for TLS to guarantee interoperability with browsers and Oracle Health infrastructure. Cerner RECOMMENDS developers use public testing tools, such as Qualsys SSL Labs to verify proper functioning of their HTTPS implementation.
Trusted Certificate Authorities
To achieve interoperability with customer deployments and Oracle Health infrastructure, Oracle Health RECOMMENDS developers use certificates from public certificate authorities that participate in the CA/Browser Forum and that have been accepted into root certificate programs of the major browser vendors (Google, Apple, Microsoft, Mozilla).
Application Registration Prerequisites for Developers
Audience
This technical specification is targeted at software developers building applications on top of the Oracle Health FHIR APIs platform as part of the [Oracle Health Developer Program][Developer Program].
Overview and Purpose
This technical specification outlines a series of security best practices that, if followed, enable Oracle Health to provide more detailed information about your application to end users. The goal of these best practices is to encourage the use of existing internet security features and standards.
In particular, we want users to:
- Be assured that their data is being securely transmitted using modern transport layer security and encryption protocols
- Understand what legal entity they are sharing their data with
These best practices should be considered as recommended prerequisites that software developers address during the application registration process, before making their applications available for general use. Failure to comply with these prerequisites can result in Oracle Health describing your application as an Unknown Application to users during the OAuth authorization workflow.
Glossary of Terms
- Effective Top-Level Domain (eTLD): The base domain. eTLD values are defined in the Public Suffix List. Examples include .com, .edu, .org, and .co.uk.
- Effective Top-Level Domain Plus 1 (eTLD+1): A domain name that is one level deeper than the effective top-level domain (eTLD). Examples include examplehealth.com, cerner.com, and cerner.co.uk.
- Organization Validated (OV): A certificate issuance process that involves the certificate authority validating the organization (business entity) requesting the certificate.
- Extended Validation (EV): A certificate issuance process that involves the certificate authority performing extended validation of the organization (business entity) requesting the certificate.
- Domain Validated (DV): A certificate issuance process that involves the certificate authority validating that the requester owns the domain. No validation of the business entity is performed.
- Transport Layer Security (TLS): A protocol for providing secure connections over a network.
- DNS TXT Record: A text record in the Domain Name System (DNS). TXT records usually have a format of
name=value
.
Technical Requirements
The technical requirements below are stated using RFC 2119 terminology. These requirements focus on the security best practices that Oracle Health expects application developers to adhere to for Oracle Health to provide the best description of your application to end users.
- Web applications MUST support the HTTPS 1.1 protocol.
- Application SHOULD support TLS. See the Guidance for the Use of TLS With Oracle Health FHIR APIs section for further detailed practices related to TLS.
- Application SHOULD use (only) port 443 for TLS.
- Application SHOULD support and prefer TLS 1.2 or higher.
- Application SHOULD have a valid, nonexpired TLS certificate issued from a trusted authority.
- Application SHOULD use an OV or EV certificate, if possible, instead of a DV certificate.
- Application’s web site SHOULD host a DNS TXT record containing the Oracle Health-issued client identifier for the application (also known as a system account ID in CernerCentral or a client identifier in the OAuth 2.0 specification). This TXT record should be added to the eTLD+1 for the domain hosting the application.
- Application’s name SHOULD align with the name of the website hosting it or the legal entity operating it.
- Mobile or native applications SHOULD (as suggested by RFC-8252) use claimed “https” scheme URI redirection instead of private-use URI scheme redirection.
Adhering to all the above requirements ensures that Oracle Health can convey the most meaningful, descriptive information about your application to end users. Failure to follow recommended (SHOULD) requirements can result in users seeing less information about your application. When Oracle Health is unable to determine information about your application because one or more of the requirements above have not been implemented, Oracle Health displays Unknown when describing your application to users.
If you want to better understand why Oracle Health has these technical requirements, see the Information Displayed to Users section and Application Registration Prerequisites FAQs section below.
Note: Consider the [Oracle Health Developer Program][Developer Program] if you want Oracle Health to perform a deeper security assessment of your application.
Setting Up Your Domain’s DNS TXT Record
To follow the security best practices, add a DNS TXT record to your application’s website containing the Oracle Health-issued client identifier for the application (also known as a system account ID in CernerCentral or a client identifier in the OAuth 2.0 specification). This TXT record should be added to the eTLD+1 for the domain hosting the application.
Consult your ISP’s documentation for the steps to set up a DNS TXT record at your application’s eTLD+1 domain.
The DNS TXT record of your application must match the following key-value format, where xxxxx is the Oracle Health-issued client identifier for your application:
cerner-client-id=xxxxx
See the following example:
cerner-client-id=bxdcd0ff-5der-4c15-b2tf-r28b105aa845
If multiple applications are registered for the same eTLD+1 domain, you can add multiple TXT records that each have the cerner-client-id
for a specific application.
See the following examples:
cerner-client-id=value1
cerner-client-id=value2
...
cerner-client-id=valueN
Steps to Verify That Your Application is Compliant
The steps outlined below show how you can check to see if your application complies with the technical requirements listed above.
Determine Your eTLD+1
The eTLD+1 is the effective top-level domain (TLD) and the part of the domain just before it. For example, given a URL of https://my-project.github.io
, the TLD is io
and the eTLD+1 is github.io
, which is considered a site. This domain is displayed to end users.
To determine eTLD+1, check public domains that are defined in the Public Suffix List.
Querying DNS for Your TXT Record
TXT records are a type of Domain Name System (DNS) record that contains text information for sources outside of your domain. You add these records to your domain settings for further domain ownership verification by Oracle Health.
To follow the security best practices, the DNS TXT record of your application must match the following key-value format, where xxxxx is the Oracle Health-issued client identifier for your application:
cerner-client-id=xxxxx
If multiple applications are registered for the same domain, cerner-client-ids
are stored in the same TXT record in the following format:
cerner-client-id=value1
cerner-client-id=value2
...
cerner-client-id=valueN
You can use the following commands and tools to check the DNS TXT records:
- Using the Microsoft Windows CLI:
nslookup
- For example,
nslookup -type=TXT examplehealth.com
- Using the Mac or Linux terminal:
dig
- For example,
dig examplehealth.com TXT
- Using the following online resources:
Inspecting Your TLS Certificate
TLS certificates are used to protect the end users’ information while in transfer and to authenticate the website’s organization identity to ensure that users are interacting with legitimate website owners.
To follow the security best practices, use TLS implementations that support current IETF best practices for TLS. See the Guidance for the Use of TLS With Oracle Health FHIR APIs section for more details.
Oracle Health RECOMMENDS that you use public testing tools, such as Qualsys SSL Labs, to verify that your HTTPS implementation is functioning properly.
Use one of the following approaches to check TLS certificates for your application:
- OpenSSL Mac or Linux:
- Online resources:
- Web browser (Mozilla Firefox is recommended):
- Open the URL in the browser.
- Select the lock icon in the browser’s address bar.
- Select Connection Secure.
- Select More Information.
- Select View Certificate.
Note: For other browsers, use the Certificate Policy and look up the OID for the policy.
Pay attention to the following information:
- Supported TLS certificates types (usually in a section called Certificate Policies, as is the case if you view the certification in Mozilla Firefox):
- Domain Validated (DV)
- Organization Validated (OV)
- Extended Validation (EV)
- Supported TLS protocols:
- TLS 1.2
- TLS 1.3
- The Certificate Revoked/Not Revoked status
- The Certificate Valid From date
- The Certificate expiration date
- The Certificate issued by one of the public Certificate Authorities
Examples
Using Mozilla Firefox to view your TLS certificate may result in a similar Organization Validated certificate as in the following example:
Using the Qualsys SSL Labs online resource to check your TLS certificate may result in the following example:
Information Displayed to Users
Application and Business Details
The table below explains how following the security practices provide more information to users about your application and the business or organization offering it. The table shows what information Oracle Health displays to end users, where the information is sourced from, and under what conditions the information is used.
Information | Example | Source | Conditions |
---|---|---|---|
Application Name | Example Health App | Oracle Health CODE Portal - Application Registration | Application name is only displayed to users if a legal entity can be associated with the application’s website by using a valid, trusted EV or OV certificate. |
Organization Name | Example Health Corporation | EV or OV TLS Certificate | Organization name is only displayed to users if a legal entity can be associated with the application’s website by using a valid, trusted EV or OV certificate. |
Organization Location | US, MO, Kansas City | EV or OV TLS Certificate | Organization location is only displayed to users if a legal entity can be associated with the application’s website by using a valid, trusted EV or OV certificate. |
Website Domain (eTLD+1) | examplehealth.com | Oracle Health CODE Portal - Application Registration | The eTLD+1 portion of the host domain of the redirect URI is displayed to the end user. |
Labels
The following table explains the labeling that Oracle Health applies to applications in certain conditions:
Label | Conditions |
---|---|
Validated | This label is displayed when an application is formally Validated through the [Developer Program][Developer Program]. |
Unknown App | This label indicates that an application does not employ enough of the security best practices listed in the Technical Requirements section above for Oracle Health to describe the application. |
HL7 SMART App Launch Active User Presence Extension
The HL7 SMART App Launch specification defines the scope of online_access
as enabling an application to obtain refresh tokens that “will be usable for as long as the end-user remains online”. In certain use cases, conflicts between user experience and security can arise when the user’s primary interaction with the EHR is through a SMART on FHIR application. In these scenarios, the EHR may have awareness that an application is continuing to use FHIR resources and refresh tokens, but such activity may not constitute active user presence. Best practices for session management, such as those prescribed by NIST 800-63B, describe requirements for users to be reauthenticated after inactivity. When users are not directly interacting with an application that is part of the EHR, a SMART on FHIR application can communicate active user presence to prevent the user from experiencing unnecessary reauthentication events.
This extension provides a mechanism by which a SMART on FHIR authorization server may declare that a refresh token is subject to inactivity constraints as part of its own token responses. Through this extension, a SMART on FHIR application may correspondingly include a parameter in token refresh requests that conveys how long ago the application last detected active user presence.
Protocol Flow
Figure 1: Abstract Protocol Flow
This specification adds additional parameters to the SMART on FHIR Access Token Response, Refresh Request, and Refresh Response shown in abstract form in Figure 1.
- The client performs an Access Token Request using an established authorization code that was established with an
online_access
scope. - The Token Endpoint responds with an access token and refresh token as usual, but also includes the
active_ttl
parameter. This value signifies the quantity of seconds (time-to-live) remaining before the user is no longer considered active, which automatically invalidates the refresh token without further activity. - Before the invalidation time specified by
active_ttl
, the client application performs a Refresh Request as usual but includes aactive_at
parameter that specifies how many seconds in the past the client application last detected active user presence. - The Token Endpoint responds as usual but includes another
active_ttl
value, again signifying the new quantity of seconds remaining before the refresh token is automatically invalidated without active user presence.
This specification uses time vectors in seconds rather than absolute date and time objects to avoid issues with clock skew between the authorization server and the application.
Notational Conventions
The key words “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “NOT RECOMMENDED,” “MAY,” and “OPTIONAL” in this document are to be interpreted as described in Key Words for Use in RFCs to Indicate Requirement Levels. If these words are used without being spelled in uppercase, then they are to be interpreted with their natural language meanings.
This specification uses the Augmented Backus-Naur Form (ABNF) notation of RFC 5234.
Terminology
Active User Presence: Any event that can be construed as a human interaction with a computing device. These interactions include, but are not limited to mouse, keyboard, scroll, click, tap, and gesture interactions.
Protocol
Authorization Server Declares Active User Presence Requirement
When issuing token responses containing refresh tokens scoped for online_access
, the SMART on FHIR authorization server returns the number of seconds after which the session is considered inactive, active_ttl
, in the following format:
active_ttl = 1*DIGIT
The inclusion of this attribute in a token response from an authorization server signals to the SMART application that the authorization server supports or has implemented this specification, and that it accepts additional parameters to signal user presence as part of the token refresh process.
If no active user presence is detected by an actor participating with the authorization server (the EHR or a SMART on FHIR application) after this number of seconds has passed, the authorization server SHOULD invalidate any refresh tokens associated with the user session.
Application Performs Token Refresh
When an application sends a Refresh Request, it MAY include the active_at
parameter to specify the number of seconds that have passed since active user presence was detected, in the following format:
active_at = 1*DIGIT
If the refresh token is still valid and the active_at
parameter is present, the authorization server calculates the instance of the last activity in the SMART application by subtracting active_at
from the current date and time:
current date/time - active_at = instance of user's last activity in the SMART app
If the instance of the user’s last activity in the SMART application is more recent than the instance of the user’s last activity known to the authorization server, then the authorization server SHALL update its record of the instance of the user’s last activity for the session and use that in its calculation of an updated active_ttl
value to return in the response to the Refresh Request.
Negative active_at
values MUST be rejected, treating the request as if the active_at
parameter were not included.
If the refresh token is invalid, either due to lapse of user activity or other invalidation, the server responds per section 5.2. The application MAY initiate a new authorization grant request, if appropriate. An authorization server MAY allow other means (outside of the scope of this specification) to re-enable the refresh token. As such, applications SHOULD provide a retry option to end users.
FAQs
General FAQs
How can I allow users to use devices that do not provide a browser (user agent) to facilitate the authorization workflow?
Oracle Health currently does not have a mechanism to allow such devices to participate in the authorization ecosystem.
What happens when a user revokes my application’s access to their data?
When a user revokes an application’s access, its refresh tokens immediately become nonfunctional. Access tokens cannot be directly revoked; however, they are only valid for a brief period of a few minutes. As a result, applications generally do not need to check for access token validity using an introspection endpoint. This behavior is discussed in more detail in RFC 7009 OAuth 2.0 Token Revocation: Implementation Note and OpenID Connect Core 1.0: Lifetimes of Access Tokens and Refresh Tokens.
What happens if a refresh token is suspended?
When the authorization server suspends a refresh token, the user can reapprove the application so that a subsequent token refresh succeeds. The application must present the error_uri
link to the user so that they can open the management application to reapprove the token. However, if the user does not open the application, or they deny the reapproval, then the token refresh continues to fail. As an alternative, the application can request an entirely new token through a new authorization grant request.
How can my application revoke a refresh token on behalf of a user?
The location of an RFC 7009 token revocation endpoint is advertised at the relative path of ./.well-known/smart-configuration
from the FHIR base URL.
See Get authorization endpoints and launch capabilities for further details.
How can my application participate in log-out mechanisms provided by the organization’s single sign-on (SSO) ecosystem?
While the Oracle Health authorization server provides OpenID Connect support, it does not currently implement any of OpenID Connect’s various log-out specifications, and the SMART specifications do not currently require them.
As an alternative, you may provide a link to manage authorized applications, which allows the user to log out through their SSO system.
A browser window or tab remains after the completion of the authorization workflow. How should my application handle this?
Depending on how the browser was opened, your application may be unable to close the browser window. If you opened a fresh browser window directly, you can use Microsoft Windows APIs to find and send a close command directly to the window.
Does the Oracle Health authorization server offer an authentication-only workflow (through OpenID Connect) for patients or their authorized representatives?
Oracle Health does not currently offer this capability.
Can I append additional query parameters to my redirection URI when I send my authorization grant request?
Yes, the Oracle Health redirection URI validation allows for additional query parameters, per the OAuth specification.
Note: The Oracle Health implementation uses strict path validation, which includes trailing slashes in your redirection URI.
I am having trouble registering my redirection URI, what advice can you offer?
URIs must conform with RFC 2396 and must be an absolute URI, per that specification. A common issue is attempting to register URIs with schemes containing a net path (“//”) but are missing an authority component. For example, app://
is an invalid URI, but app://callback
is valid.
Can I register multiple redirect URIs?
This functionality is not yet exposed in our developer tooling, but our operations team can register multiple redirect URIs for your application.
Can an application developed by an Oracle Health customer skip the authorization interaction with users?
Yes, we offer the ability for organizations providing their own application to disable the patient-mediated authorization workflow when used in context with their organization. Contact support to request that explicit consent requirements be disabled for your application in your environment. Note that your application should avoid making repeated requests for offline_access, as these requests accumulate in the user’s Manage Authorizations workflow.
How can I embed my SMART application in another application, such as inside a web view or iframe and still orchestrate the authorization workflow?
A general-purpose framework for embedding SMART applications does not currently exist.
What do I do when one or more offline access tokens stored by my application may have been compromised?
Disable or rotate your system account in Cerner Central as soon as possible with Cerner Central System Account Management.
How can I deliver my solution to users using its own Citrix instance with XenApp?
Oracle Health currently does not have guidance on how to deliver native applications running in their own dedicated Citrix container. Such applications generally interact with the authorization server from a browser hosted in the application’s Citrix environment, unless interaction is allowed with the browser on the device where Citrix Receiver is run.
Why am I getting an error message about having too many scopes?
Access tokens are conveyed to resource servers as HTTP headers, and most web servers place an upper limit on the largest allowable HTTP header. The exact value varies between vendors, but is typically in the 4K to 8K range. Because scopes are included in access tokens, using more of them makes the access token larger. If the authorization server detects that it is about to return an access token that would be unusably large, it returns this error message instead. Try reducing the number of scopes in your request to the minimum necessary for your application.
Application Registration Prerequisites FAQs
Are these security requirements required for all Oracle Health FHIR APIs applications?
The security requirements outlined in this document are currently only required for all FHIR applications targeting the patient persona. Though, Oracle Health encourages the use of these best practices for all end user-facing applications.
Does my development environment need to comply with these security requirements?
No. You can have development environments that use private domains (such as localhost), unsecured connections (non-HTTPS), or nonstandard ports (non-443).
However, Oracle Health is unable to automatically assess such environments’ compliance with security best practices. Therefore, Oracle Health recommends that you also have one or more development environments that do comply with this page’s recommendations, allowing you to receive an accurate preview of your patients’ user experience in production.
Why are OV and EV certificates preferred by Oracle Health?
Organization-Validated (OV) and Extended-Validation (EV) certificates ensure that the certificate is being issued to an official business entity (with a name and address). This helps provide transparency to users (patients) about who they are sharing their data with. Oracle Health does not perform validation of the incorporation of your business. By using an OV or EV certificate, Oracle Health trusts that the certificate authority has performed such validation and correspondingly displays your organization’s name in association with the application.
Is either an OV or EV certificate acceptable?
Yes, Oracle Health does not distinguish between OV and EV certificates, so either is acceptable. However, some web browsers might give preferential treatment to EV certificates.
Are self-signed certificates acceptable?
No. Oracle Health does not support the use of self-signed certificates.
What Certificate Authorities (CAs) does Oracle Health trust?
See the Guidance for the Use of TLS With Oracle Health FHIR APIs section for a summary of the CAs that Oracle Health trusts.
How or when does Oracle Health use eTLD+1 values?
In some situations where Oracle Health cannot determine the business entity providing an application, Oracle Health falls back to using the domain name of the application’s primary redirect URI to describe the application. For brevity and consistency, the eTLD+1 value is used in these situations.
Why does Oracle Health only display the eTLD+1 portion of the domain name?
The eTLD+1 portion is displayed to help avoid confusing users (patients).
How do I get an Oracle Health client identifier for my application?
Oracle Health assigns your application a unique client identifier as part of the registration process in code Console. This Oracle Health client identifier is also known as a system account ID in some Cerner Central tooling.
Why is a DNS TXT record recommended?
The DNS TXT record helps prove that the website intends to host your application. Oracle Health does not automatically assume that URLs provided by a developer are associated with the website operator. By publishing a DNS TXT record, Oracle Health can verify that the party that controls the website address intends to associate itself with your registered application.
Where should the DNS TXT record be placed?
The DNS TXT record should be located on the DNS record for the eTLD+1 domain name of your application’s primary redirect URI.
What happens if I do not provide the DNS TXT record?
Oracle Health is unable to determine if the website intends to host your application. Therefore, Oracle Health labels the application as Unknown Application and no information about your application except the domain name (ETLD+1) is displayed to the user. Users can still use your application if they are comfortable with it.
Why does Oracle Health recommend that an application’s name align with the name of the website hosting it or the legal entity operating it?
As mentioned in the overview, the goal of the practices outlined in this document is to enable users (patients) to have a better understanding of who or what they are considering sharing their protected health information (PHI) with. Having a series of seemingly unrelated names (application name, organization name, and website name) makes it more difficult to achieve this goal.
If I modify my application’s TLS certificate or DNS TXT record, how long before the Oracle Health workflow recognizes and displays these changes?
It may take up to 12 hours before the Oracle Health workflow recognizes TLS certificate or DNS TXT record changes.
What should I do if the organization information being displayed for my application seems incorrect?
Use the steps outlined above to check the certificate being returned from the URL of your application’s redirect URI. Your organization may be employing a content delivery network (CDN) that serves up its own certificate for your website. If you determine this to be the case, work with your CDN provider to ensure that the proper certificate is served for your URL.
Additional Resources
- Augmented BNF for Syntax Specifications: ABNF
- code Console
- FHIR Service Authorization Specification
- Creative Commons Attribution 4.0 International (CC BY 4.0)
- FHIR Specification
- HTTP Authentication: Basic and Digest Access Authentication
- Key Words for Use in RFCs to Indicate Requirement Levels
- NIST Special Publication 800-63B Digital Identity Guidelines, Authentication and Lifecycle Management - Table 4-1 AAL Summary of Requirements
- OAuth 2.0 for Native Apps
- OAuth 2.0 Security Best Current Practice
- OAuth 2.0 Threat Model and Security Considerations
- OpenID Connect Core 1.0 Incorporating Errata Set 1
- OpenID Connect Discovery 1.0 Incorporating Errata Set 1
- Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
- Registering an Application to a URI Scheme (Windows API)
- SMART App Launch: Scopes and Launch Context - Scopes for Requesting a Refresh Token
- System Accounts Help
- The OAuth 2.0 Authorization Framework
- The OAuth 2.0 Authorization Framework: Bearer Token Usage
- The OAuth 2.0 Authorization Framework: Refreshing an Access Token
Appendix
This section provides Augmented Backus-Naur Form (ABNF) syntax descriptions for the elements defined in this specification using the notation of Augmented BNF for Syntax Specifications: ABNF, and also uses other syntax definitions defined in Appendix A of the OAuth 2.0 Framework.
A.1. Resource Scope Syntax
scope-name = resource-context "/" resource-type "." modification-rights resource-context = ("user" / "patient") resource-type = (Name) modification-rights = ("read" / "write");
A.2. Launch Scope Syntax
launch-scope = "launch/" *( SP scope-token )
A.3. Launch Code Syntax
launch-code = 1*VSCHAR
A.4. Launch Issuer Syntax
launch-issuer = URI-reference
A.5. Launch Intent Syntax
launch-intent = 1*VSCHAR
Authorization Framework
G15084-01
October 2024
Copyright © 2021, 2024, Oracle and/or its affiliates.
Primary Author: Oracle Corporation