Note: You must have a preexisting account (username and password) to access Oracle Health Millennium Platform and permission to use the REST API. To request access to the REST API, contact your Oracle Health Millennium Platform 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:

This guide provides the following information:

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:

  1. Log in to code Console.
  2. 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:

  1. Register a new application with an application type of System or an application privacy of Confidential, and complete the registration process.
  2. 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.

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 Well-Known SMART Configuration 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"
    }

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:

  1. Discover the authorization and token endpoint URLs.
  2. Construct an authorization grant request URL.
  3. Call a browser with the authorization grant request URL.
  4. Receive the OAuth callback.
  5. Exchange the received grant for a token.
  6. Close the browser.
  7. Handle any exceptions encountered.
  8. Use refresh tokens.

A formal technical specification for this process may be found in the FHIR Service Authorization Specification.

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:

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:

Examples of scopes include:

A resource context prefixes each FHIR scope in SMART. This value represents one of three possible use cases:

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:

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:

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:

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:

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:

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 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

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-7d99214f0ec7
Response: 
    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:

The following additional elements may be returned:

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.

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-aa05244faf3b
Response: 
    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:

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:

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.

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:

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:

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

Contextless Flow

Figure 1: SMART Application Contextless Flow Diagram

In Figure 1, the following workflow is described:

  1. 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.
  2. The SMART application performs discovery by requesting the FHIR server’s conformance statement.
  3. The FHIR server returns the conformance statement, which provides the needed endpoints for Steps 4 and 8.
  4. 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.
  5. The authorization server interacts with the resource owner to verify identity or other information required by the authorization server.
  6. The end user provides any information needed by the authorization server to proceed.
  7. An authorization grant is sent through the OAuth 2.0 framework back to the SMART application.
  8. The SMART application requests an access token using the authorization code.
  9. The authorization server returns the access token.
  10. The SMART application uses the access token to request a FHIR resource.
  11. 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:

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:

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

EHR Launch Flow

Figure 2: EHR Launch Flow Diagram

In Figure 2, the following workflow is described:

  1. The end user selects to open a SMART application from within an EHR application.
  2. 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.
  3. The SMART application performs discovery by requesting the FHIR server’s conformance statement.
  4. The FHIR server returns the conformance statement, which provides the needed endpoints for Steps 5 and 9.
  5. 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.
  6. The authorization server interacts with the resource owner to verify identity or other information required by the authorization server.
  7. The end user provides any information needed by the authorization server to proceed.
  8. An authorization grant is sent through the OAuth 2.0 framework back to the SMART application.
  9. The SMART application requests an access token using the authorization code.
  10. The authorization server returns the access token.
  11. The SMART application uses the access token to request a FHIR resource.
  12. 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:

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:

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

SMART Application Launch Flow

Figure 3: SMART Launch Flow Diagram

In Figure 3, the following workflow is described:

  1. The end user selects an option in a SMART application to retrieve context from the EHR application.
  2. 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.
  3. The FHIR server returns the conformance statement, which provides the needed endpoints for Steps 4 and 8.
  4. 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.
  5. 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.
  6. The user confirms or establishes the necessary context for the authorization server.
  7. An authorization grant is sent through the OAuth 2.0 framework back to the SMART application.
  8. The SMART application requests an access token using the authorization code.
  9. The authorization server returns the access token.
  10. The SMART application uses the access token to request a FHIR resource.
  11. 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

Client Credentials Flow

Figure 4: Client Credentials Flow Diagram

In Figure 4, the following workflow is described:

  1. 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.
  2. The FHIR server returns the conformance statement, which provides the needed endpoint for Step 3.
  3. The SMART application requests an access token using its credentials.
  4. The authorization server returns the access token.
  5. The SMART application uses the access token to request a FHIR resource.
  6. 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

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 following contexts are defined:

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:

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:

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:

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:

Exception Conditions

During the processes of obtaining access tokens and using access tokens, exceptions can occur.

The following conditions can cause exceptions:

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:

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

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:

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:

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:

  1. Retrieve the OpenID Provider configuration information per the OpenID Provider Configuration Request section of OpenID Connect Discovery.
  2. Extract the URI of the JSON Web Key Set (jwks_uri).
  3. 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:

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:

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:

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:

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:

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

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.

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:

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:

Note: For other browsers, use the Certificate Policy and look up the OID for the policy.

Pay attention to the following information:

Examples

Using Mozilla Firefox to view your TLS certificate may result in a similar Organization Validated certificate as in the following example: Organization Validated Certificate Type

Using the Qualsys SSL Labs online resource to check your TLS certificate may result in the following example: Example Image

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

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.

  1. The client performs an Access Token Request using an established authorization code that was established with an online_access scope.
  2. 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.
  3. Before the invalidation time specified by active_ttl, the client application performs a Refresh Request as usual but includes a active_at parameter that specifies how many seconds in the past the client application last detected active user presence.
  4. 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 well-known SMART configuration 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][code console]. This Oracle Health client identifier is also known as a system account ID in some Cerner Central tooling.

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.

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

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