Authorization


Overview

Cerner’s implementation of the HL7® FHIR® Standard is protected using the SMART® on FHIR® authorization framework. SMART® on FHIR® defines a profile of the OAuth 2 framework for obtaining authorization to act on behalf of users; it is highly recommended that developers review and understand the OAuth 2 framework prior to implementing their authorization workflow. Cerner recommends the following IETF publications for review:

This guide offers:

Benefits of the Authorization Model

The use of an authorization protocol offers additional security for users/enterprises by abstracting the credentials that users use 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; this is not possible in traditional models where the application has direct access to the user’s credentials.

Furthermore, by abstracting authentication away from client applications, there is less risk such credentials will be compromised, and organizations have more flexibility in offering differing forms of authentication (possible examples include the use of Windows Hello technology, Apple TouchID, etc.)

Finally, the token model employed by the OAuth 2 authorization 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 Cerner FHIR® Service Authorization Specification.

Differentiating SMART® and FHIR®

The HL7® FHIR® Standard defines an API to access information within an electronic health record system. The SMART® framework defines an API for applications to obtain an authorized context to access FHIR® resources and exchange context information with client applications.

Registration

In order for your client application to utilize any protected resources, your client application must first register. A Cerner Care account is required to register applications. Obtaining a Cerner Care account is free and requires nothing but an email address.

If registering an application that is using the public app profile and requires access only when the user is online, your client application must first register using our code console.

If registering a confidential client application (required for offline_access and access on behalf of a system), please first request an account via the non-production instance of Cerner Central System Account Registration. Once the request is completed, use the issued system account GUID when registering the application in the code console. Be aware that access on behalf of a system currently has limited availability. Check the respective FHIR® implementation documentation to determine availability.

Once registered, the client identifier will be provided for use with the Cerner Authorization Server. As a registered client, Cerner organizations may then ask for your client application to be enabled, which is necessary in order to gain access to their protected resources.

Requesting Authorization on Behalf of a User

To access Cerner’s FHIR® services on behalf of a user, your client application must make an authorization request through a user agent on the user’s device. This involves the following steps:

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

Discovering Authorization URLs

Each instance of Cerner’s FHIR® services advertise the URL of its respective authorization server within its FHIR® conformance document.

The FHIR® Conformance resource can be retrieved by performing an HTTP GET against the resource located at the relative path of ./metadata from the FHIR® base URL.

Within the structure of this document, three important URLs are advertised in an extension to Conformance.rest.security, identified via the URL of http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris.

The first URL is the location of the authorization endpoint, which is further identified by the sub-extension URL “authorize”.

The second URL of importance is the location of the authorization server’s token endpoint, which is further identified by the sub-extension URL “token”.

The third URL of importance is the location of the authorization server’s user-facing authorization management workflow entry point, which is further identified by the sub-extension URL “manage”. This sub-extension is advertised from user-facing instances of Cerner’s FHIR® server.

The following is non-normative example of a conformance document containing this information:

{
  "resourceType": "Conformance", 
  "rest": [
    {
      "security": {
        "extension": [
          {
            "url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris",
            "extension": [
              {
                "url": "token",
                "valueUri": "https://example.org/token"
              },
              {
                "url": "authorize",
                "valueUri": "https://example.org/authorize"
              },
              {
                "url": "manage",
                "valueUri": "https://example.org/patient/authorizations"
              }
            ]
          }
        ]
      }
    ]
  }
}      

Construct the Authorization Request URL

An authorization request takes the form of an x-www-form-urlencoded query string, appended to the authorization endpoint’s URL (as discovered from the previous section.) The base specification for the structure of this request is defined in section 4.1 “Authorization Code Grant” of RFC6749.

At minimum, the following parameters are included in the authorization request; each are documented in the following sections:

Scopes

During the authorization process, client applications should identify at runtime:

Each of the above pieces of information are presented in the authorization request to the server in the form of “scopes”. Per the OAUTH specification, the scope of a request is “…a list of space-delimited, case-sensitive strings. The strings are defined by the authorization server.” With SMART® on FHIR®, access to FHIR® resources is controlled by scopes with the following format:

scope-name            = resource-context "/" resource-type "." modification-rights
resource-context      = ("user" / "patient" / "system") 
resource-type         = (Name / "*")
modification-rights   = ("read" / "write" / "*" ); 

Examples of scopes include:

The “resource context” represents one of three possible choices:

In certain cases, the authenticated user will be presented a choice to allow your application to utilize the requested scopes on the user’s behalf. As such, your application should request only the minimum scopes needed in order to fulfill its function.

Note: Many combinations of scopes are possible to be requested and approved, but not all may be recognized by then given version of a FHIR® API resource being used. Please refer to the respective FHIR® API resource documentation for a full list of its capabilities.

In addition to FHIR® resource scopes, the SMART® on FHIR® authorization framework also defines these additional scopes that further govern the behavior of authorization:

Further information on the usage of these special scopes are further detailed below.

Identity Scopes: ‘openid’ and ‘profile’

Certain classes of applications may need to identify the user for whom it is acting on behalf of. Such requirements may include (but are not limited to) the following:

The scope ‘openid’ will request that Cerner’s authorization server supply and OpenID Connect identity token as part of the authorization workflow. Further details on utilizing the OpenID token can be found in the OpenID Connect Guide.

The scope ‘profile’ will additionally request that the OpenID Connect token include the claim “profileURL”, as defined by the SMART® on FHIR® 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 whom is authenticated.

NOTE: As of this writing, Cerner’s Ignite implementation does not support authorization for retrieval of Person resources; you may proceed with a design that proactively attempts to retrieve the resource such that your app takes advantage of this capability once made available.

Duration Scopes: ‘online_access’ and ‘offline_access’

The default duration of access received through the authorization grant workflow is a single token that is valid for 570 seconds (~10 minutes). For applications that need access to services for longer durations, Cerner’s Ignite platform supports the concept of “refresh tokens”.

With ‘online_access’, your application can continue to obtain access tokens on behalf of the user until:

With ‘offline_access’, an application can continue to obtain access tokens in perpetuity on behalf of the user until:

Supported Scopes

Wildcard Scopes are currently not supported. An application is currently required to specifically request each scope that it needs to run.

Other combinations of scopes may be limited; please see the FAQ for known limitations.

State

When performing an authorization grant request, it is highly recommended that your client application establish a transient, one-time-use “state” value for each individual request you send. 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” classes of exploits. For more information on these types of exploits, consult the RFC OAuth 2.0 Threat Model and Security Considerations.

Audience

When performing an authorization grant request, it is required your client application send the base URL of the FHIR® resource server for which you will be sending access tokens to. This is conveyed via an additional query parameter in the grant request named “aud”. This parameter it utilized by Cerner’s authorization server 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, a valid, authorized access token could be inadvertently be sent by your application to the untrusted party.

Authorization grant requests that do not contain the audience parameter are automatically rejected by Cerner’s authorization server. The following is a fragment from a x-www-form-urlencoded grant request query string where the audience is provided:

&aud=https%3A%2F%2Ffhir-ehr.sandboxcerner.com%2Fdstu2%2F0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca%2F

Launch

Some Cerner solutions support the “launch” feature of the SMART® on FHIR® authorization framework. This feature provides three benefits to client applications:

Examples

The following are hypothetical examples of authorization requests:

client id:    bb318a62-fa61-49ae-b692-7d99214f0ec7
scopes:       patient/Observation.read patient/MedicationHistory.read launch
audience:     https://fhir-ehr.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/
state:        a4c16a46-2c46-482c-8d66-4cc4a2990bda
launch:       a17aba51-1395-48d3-b3a9-73f2baf784da

https://authorization.sandboxcerner.com/tenants/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/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.sandboxcerner.com%2Fdstu2%2F0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca%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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/
state:        a4c16a46-2c46-482c-8d66-4cc4a2990bda

https://authorization.sandboxcerner.com/tenants/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/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.sandboxcerner.com%2Fdstu2%2F0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca%2F&state=a4c16a46-2c46-482c-8d66-4cc4a2990bda

Invoking an Appropriate User Agent

Once an authorization code grant request URL has been generated, you will need to invoke an appropriate user agent to invoke the authorization request. In all scenarios, this web page will interact with the user agent in order 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 end user to obtain their approval during the authorization process.

This particular part of the process has a number of complexities; the recommendations offered in this section are designed to ensure:

The following sections discuss how to invoke the proper user agent for specific platforms.

(Web) Client Applications Delivered via the Browser

For applications delivered via the “https” scheme within a browser, it is recommended to invoke the authorization workflow within a separate pop-up window (for desktops) or tab (for mobile browsers). The use of a pop-up / separate tab ensures that any navigation that occurs while servicing the authentication or authorization workflows are maintained separately from your initial tab, thus allowing the user to properly navigate backwards in their browser history once the authorization workflow has completed. On desktop platforms and/or mobile 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, it will generally be necessary for your application to trigger the opening of the window based on a user interaction (click or touch). In certain specific 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 within an iframe - doing so may have unexpected results caused by clickjacking protection mechanisms, anti-phishing protection mechanisms, browser third-party cookie policy, etc.

When opening the additional browser window, it is recommended to include the location “chrome” of the browser such that TLS/EVSSL indicators are included for display to the user. Such visual cues are an important part of security for some authentication systems.

Your authorization repsonse comes in the form of a redirect (which is orchestrated within the child window) to your registered redirect URI. Once your server has processed the response, Javascript can be utilized to notify the parent window that the workflow is complete; in turn, the parent window can close the child window.

Example Javascript for Opening the Authorization Workflow

The below Javascript demonstates how an application could open the authorization workflow as a modal on desktop platforms. In addition to desktop platforms, this method automatically will function on mobile platforms by creating an additional tab or split-screen browsing windows.

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 following Javascript snippets demonstrate how your application can notify the parent window of the completion of the workflow.

This first script allows your main window to listen to postMessage calls from child windows:

window.addEventListener("message", function (e) {
	var oauthMessage = e.data;
	loginWindow.close();
	processOAuthMessage(oauthMessage);
}, false);

The second script is served by the webpage 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 could be the result of any server-side processing handled by your server as a result of the HTTP GET to the callback URI.

Other User Experience Considerations

Native Client Applications on Mobile Platforms

In recent years, OS platforms have been forced to lock down certain behaviors within 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 absue 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 on the user experience of OAuth2-based workflows by preventing remnant browser tabs and smoothing the transition between browser and app (no OS app switching occurs.)

For more information on best practices for OAuth2-based workflows for native applications, please refer to the IETF Best Current Practices (BCP) draft “OAuth 2.0 for Native Apps”.

NOTE: Cerner’s Authorization Server does not currently implement PKCE as noted in section 8.2 of the native applications BCP draft.

The next sections discuss specific special cases not covered by the OAuth native application BCP guide.

“Win32” Applications

Cerner currently supports only explicit internet hosts or explicit URI activation schemes for redirection URIs; as such, developers of traditional Windows applications should register a scheme for their application. The following 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 would be registered with a redirection URI of “sample.application://”. Upon redirection to this scheme, the Windows operating system will invoke the registered application with the OAuth2 response URI passed as the first argument. The client application may then parse the URI and in turn determine which open instance of the application (if multiples are allowed) initiated the request via examination of the “state” parameter.

Processing the Authorization Grant Response

The authorization grant response comes in the form of a x-www-form-urlencoded query string, appended to your redirection URI. The base specification for the structure of this response is defined in section 4.1 “Authorization Code Grant” of RFC6749 (the OAuth2 Framework). The following is an example:

https://example.com/callback?code=0c8b259b-d716-4712-ad6a-1d22d92523fa&state=a4c16a46-2c46-482c-8d66-4cc4a2990bda

Within a successful response, a “code” parameter will be present, and a “state” parameter will be present if your application included “state” as part of the initial request.

First, validate that the “state” parameter matches that of a request that was initiated by the current device / user agent. Next, exchange the code for a token per section 4.1 of the RFC6749 (the OAuth2 Framework). The following are example requests / responses:

Request:

POST /tenants/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/protocols/oauth2/profiles/smart-v1/token HTTP/1.1
Host: authorization.sandboxcerner.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&client_id=bb318a62-fa61-49ae-b692-7d99214f0ec7&state=a4c16a46-2c46-482c-8d66-4cc4a2990bda

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": "eyJraWQiOiIyMDE2LTExLTAxVDE1OjExOjQ4LjY1NS5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3dlcmNoYXJ0IiwidXJuOmNvbTpjZXJuZXI6YXV0aG9yaXphdGlvbjpjbGFpbXMiOnsidmVyIjoiMS4wIiwidG50IjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIiwiYXpzIjoidXNlclwvT2JzZXJ2YXRpb24ucmVhZCJ9LCJhenAiOiJkZXZqcyIsImlzcyI6Imh0dHBzOlwvXC9hdXRob3JpemF0aW9uLmRldmNlcm5lci5jb21cLyIsImV4cCI6MTQ3ODAyODYyNSwiaWF0IjoxNDc4MDI4MDI1LCJqdGkiOiI0OTNjMGNlOC03ZDg2LTQ3YjctOGI5ZS00OWFkZGI2MjlhMmQiLCJ1cm46Y2VybmVyOmF1dGhvcml6YXRpb246Y2xhaW1zOnZlcnNpb246MSI6eyJ2ZXIiOiIxLjAiLCJwcm9maWxlcyI6eyJzbWFydC12MSI6eyJhenMiOiJ1c2VyXC9PYnNlcnZhdGlvbi5yZWFkIn19LCJjbGllbnQiOnsibmFtZSI6IkRldkpTIERlbW8gQXBwbGljYXRpb24gKGxlZ2FjeSBjbGllbnQgaWQpIiwiaWQiOiJkZXZqcyJ9LCJ1c2VyIjp7InByaW5jaXBhbCI6InBvd2VyY2hhcnQiLCJwZXJzb25hIjoicHJvdmlkZXIiLCJpZHNwIjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIiwicHJpbmNpcGFsVXJpIjoiaHR0cHM6XC9cL21pbGxlbm5pYS5zYW5kYm94Y2VybmVyLmNvbVwvaW5zdGFuY2VcLzJjNDAwMDU0LTQyZDgtNGU3NC04N2I3LTgwYjViZDVmZGU5ZlwvcHJpbmNpcGFsXC8wMDAwLjAwMDAuMDAwRi4zMjVDIiwiaWRzcFVyaSI6Imh0dHBzOlwvXC9taWxsZW5uaWEuc2FuZGJveGNlcm5lci5jb21cL2FjY291bnRzXC9kZXZlbmcubm9ydGhhbWVyaWNhLmNlcm5lci5uZXRcLzJjNDAwMDU0LTQyZDgtNGU3NC04N2I3LTgwYjViZDVmZGU5ZlwvbG9naW4ifSwidGVuYW50IjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIn19.TE7PpJZWgW_V47mdqk8ihFek6Pf5jrk8dS3n6QIqNk0C0tzndXu5Q0OFEcf8CxzWJlIzsK_UYDj1SHPTySVDNQ",
  "scope": "user/Observation.read",
  "token_type": "Bearer",
  "expires_in": 570
}

Three elements of the response should be evaluated:

The following additional elements may be returned:

Closing the Grant Interaction

Once the authorization grant response has been received, the separate window / user agent for the facilitating the grant interaction should be automatically closed, where possible (an example of this for web-based applications is included earlier in this document.) In the event this step is either not successful or not possible, content is provided by the authorization server to inform the user if it is safe to close the additional window. The authorization server itself will 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 errors. The following is an example error response from the grant workflow:

https://example.com/callback?state=f09dcfff-95ff-4e86-a689-05c8dd9719a2&error=access_denied&error_uri=https%3A%2F%2Fauthorization.sandboxcerner.com%2Ferrors%2Furn%253Acerner%253Aerror%253Aauthorization-server%253Aoauth2%253Agrant%253Adenied-by-server%2Finstances%2F42925fc9-7a7e-4cb0-95e4-4d3f178f68b7%3Fpersona%3Dprovider%26client%3Ddevjs%26tenant%3D0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca

The following is an example error response from an access token request:

{
  "error": "invalid_grant",
  "error_uri": "https://authorization.sandboxcerner.com/errors/urn%3Acerner%3Aerror%3Aauthorization-server%3Aoauth2%3Atoken%3Acode-invalid-or-expired/instances/6359728c-c966-4929-bbf6-2388d353d89e?client=devjs&tenant=0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca"
}

In either circumstance, Cerner’s authorization server communicates the parameter “error_uri”, which represents a URI that contains additional information useful for end users, client app developers, and support personnel, along with support contact information for the associated organization. It is recommended when such errors occur to present a “more information” link or button to the user (hyperlinked to the value of the URI) in addition to other support instructions that your application displays to the user. Furthermore, it may be prudent for your application to display a “retry” or “start over” mechanism such that the user can retry the operation once the problem has been corrected.

Utilizing Refresh Tokens

If your application is designed to interact with a user over periods of time longer than that of a single access token, it will be necessary to utilize “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 are requested as a special scope in the authorization grant request:

As access tokens are valid for periods that are less than ten minutes, it is recommended to retrieve and cache new tokens in advance of the previous token expiring. Doing so out-of-band of a user interaction will reduce the user’s perception of application latency. Refresh attempts at intervals lower than one minute may result in throttling. It is not recommended to utilize tokens that are near the precipice of expiry as latency could result in token rejection.

Access Token Request / Response

The following are examples of the request/response mechanism defined in section 6 “Refreshing an Access Token” of the OAuth2 Framework.

Request:

POST /tenants/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/protocols/oauth2/profiles/smart-v1/token HTTP/1.1
Host: authorization.sandboxcerner.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": "eyJraWQiOiIyMDE2LTExLTAxVDE1OjExOjQ4LjY1NS5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3dlcmNoYXJ0IiwidXJuOmNvbTpjZXJuZXI6YXV0aG9yaXphdGlvbjpjbGFpbXMiOnsidmVyIjoiMS4wIiwidG50IjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIiwiYXpzIjoidXNlclwvT2JzZXJ2YXRpb24ucmVhZCBvbmxpbmVfYWNjZXNzIn0sImF6cCI6ImRldmpzIiwiaXNzIjoiaHR0cHM6XC9cL2F1dGhvcml6YXRpb24uZGV2Y2VybmVyLmNvbVwvIiwiZXhwIjoxNDc4MDMzOTEyLCJpYXQiOjE0NzgwMzMzMTIsImp0aSI6Ijg3MDY4MjYzLTI1NzItNDJmOC1iMDA3LTlmYTgwMzc5OGMxYiIsInVybjpjZXJuZXI6YXV0aG9yaXphdGlvbjpjbGFpbXM6dmVyc2lvbjoxIjp7InZlciI6IjEuMCIsInByb2ZpbGVzIjp7InNtYXJ0LXYxIjp7ImF6cyI6InVzZXJcL09ic2VydmF0aW9uLnJlYWQgb25saW5lX2FjY2VzcyJ9fSwiY2xpZW50Ijp7Im5hbWUiOiJEZXZKUyBEZW1vIEFwcGxpY2F0aW9uIChsZWdhY3kgY2xpZW50IGlkKSIsImlkIjoiZGV2anMifSwidXNlciI6eyJwcmluY2lwYWwiOiJwb3dlcmNoYXJ0IiwicGVyc29uYSI6InByb3ZpZGVyIiwiaWRzcCI6IjJjNDAwMDU0LTQyZDgtNGU3NC04N2I3LTgwYjViZDVmZGU5ZiIsInByaW5jaXBhbFVyaSI6Imh0dHBzOlwvXC9taWxsZW5uaWEuc2FuZGJveGNlcm5lci5jb21cL2luc3RhbmNlXC8yYzQwMDA1NC00MmQ4LTRlNzQtODdiNy04MGI1YmQ1ZmRlOWZcL3ByaW5jaXBhbFwvMDAwMC4wMDAwLjAwMEYuMzI1QyIsImlkc3BVcmkiOiJodHRwczpcL1wvbWlsbGVubmlhLnNhbmRib3hjZXJuZXIuY29tXC9hY2NvdW50c1wvZGV2ZW5nLm5vcnRoYW1lcmljYS5jZXJuZXIubmV0XC8yYzQwMDA1NC00MmQ4LTRlNzQtODdiNy04MGI1YmQ1ZmRlOWZcL2xvZ2luIn0sInRlbmFudCI6IjJjNDAwMDU0LTQyZDgtNGU3NC04N2I3LTgwYjViZDVmZGU5ZiJ9fQ.q8WVBhrznHZDh0dlLkU-2ZO9FEwCAMMozlOT0No3ZPkfbTenPW58ausP31pX1vWwFDq1y6GIGQ-MqMO7nf8q7w",
  "scope": "user/Observation.read online_access",
  "token_type": "Bearer",
  "expires_in": 570
}

NOTE: The token response from a refresh will not contain a new refresh token. The original refresh token from the initial grant response must be retained.

Considerations for Handling ‘offline_access’

To utilize refresh tokens issued with the offline_access scope, Cerner requires your application is present credentials as part of the access token request utilizing the BASIC authentication scheme. The rationale is such that if your solution compromises a large number of refresh tokens that such refresh tokens need not be revoked; only our client credentials need to be rotated to prevent misues of such compromised token values. Client credentials for applications using Cerner’s authorization server as issued via Cerner Central System Account Management.

It is currently not recommended to store offline_access tokens in persistent storage at a user’s device. Cerner’s authorization management workflows do not currently identify individual devices, or provide revocation tools that would allow a user to revoke access to individual devices. If your application will allow the user to obtain data at their client device, you must supply your own mechanism for authenticating and revoking such devices to the user and/or administrators.

Cerner’s authorization server can be used as an authentication mechanism via the use of the “openid” scope. In this scenario, an offline access refresh token could 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 would invoke an authorization reuqest containing the “openid” scope to soley perform authentication to allow your service tier to identify the user and any refresh tokens your application currently possesses for the user.

NOTE: Cerner’s authorization server currently does not support the stand-alone “openid” workflow for patients and/or their authorized representatives, nor does it support “offline_access” for providers at this time.

When retrieving an access token utilizing using an online_access refresh, the most likely cause of failures is that access has been revoked. The following steps are recommended for the user experience:

Considerations for Handling ‘online_access’

When retrieving an access token utilizing 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:

Utilizing Authorization

To utilize access Cerner FHIR® resources utilizing an access token, include a “bearer” authorization header in your HTTP request per RFC 6750 as follows:

Authorization: Bearer eyJraWQiOiIyMDE2LTExLTAxVDE1OjExOjQ4LjY1NS5lYyIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJzdWIiOiJwb3dlcmNoYXJ0IiwidXJuOmNvbTpjZXJuZXI6YXV0aG9yaXphdGlvbjpjbGFpbXMiOnsidmVyIjoiMS4wIiwidG50IjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIiwiYXpzIjoidXNlclwvT2JzZXJ2YXRpb24ucmVhZCJ9LCJhenAiOiJkZXZqcyIsImlzcyI6Imh0dHBzOlwvXC9hdXRob3JpemF0aW9uLmRldmNlcm5lci5jb21cLyIsImV4cCI6MTQ3ODAyODYyNSwiaWF0IjoxNDc4MDI4MDI1LCJqdGkiOiI0OTNjMGNlOC03ZDg2LTQ3YjctOGI5ZS00OWFkZGI2MjlhMmQiLCJ1cm46Y2VybmVyOmF1dGhvcml6YXRpb246Y2xhaW1zOnZlcnNpb246MSI6eyJ2ZXIiOiIxLjAiLCJwcm9maWxlcyI6eyJzbWFydC12MSI6eyJhenMiOiJ1c2VyXC9PYnNlcnZhdGlvbi5yZWFkIn19LCJjbGllbnQiOnsibmFtZSI6IkRldkpTIERlbW8gQXBwbGljYXRpb24gKGxlZ2FjeSBjbGllbnQgaWQpIiwiaWQiOiJkZXZqcyJ9LCJ1c2VyIjp7InByaW5jaXBhbCI6InBvd2VyY2hhcnQiLCJwZXJzb25hIjoicHJvdmlkZXIiLCJpZHNwIjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIiwicHJpbmNpcGFsVXJpIjoiaHR0cHM6XC9cL21pbGxlbm5pYS5zYW5kYm94Y2VybmVyLmNvbVwvaW5zdGFuY2VcLzJjNDAwMDU0LTQyZDgtNGU3NC04N2I3LTgwYjViZDVmZGU5ZlwvcHJpbmNpcGFsXC8wMDAwLjAwMDAuMDAwRi4zMjVDIiwiaWRzcFVyaSI6Imh0dHBzOlwvXC9taWxsZW5uaWEuc2FuZGJveGNlcm5lci5jb21cL2FjY291bnRzXC9kZXZlbmcubm9ydGhhbWVyaWNhLmNlcm5lci5uZXRcLzJjNDAwMDU0LTQyZDgtNGU3NC04N2I3LTgwYjViZDVmZGU5ZlwvbG9naW4ifSwidGVuYW50IjoiMmM0MDAwNTQtNDJkOC00ZTc0LTg3YjctODBiNWJkNWZkZTlmIn19.TE7PpJZWgW_V47mdqk8ihFek6Pf5jrk8dS3n6QIqNk0C0tzndXu5Q0OFEcf8CxzWJlIzsK_UYDj1SHPTySVDNQ

If the access token is invalid, the FHIR® resource will return a “WWW-Authenticate” header in the response with additional details per RFC 6750.

User Experience

The next sections include user experience recommendations your application should consider/incorporate in its design.

Handling the Authorization Request Window Being Closed

When presenting an authorization request to the user, the possibility exists that the user might simply close the window. This could occur as a result of the user choosing not to accept the terms, or could occur due to a failure to display the content.

In this scenario, your application should check and detect if the window has closed, and react accordingly. Offer the ability for the user to try again or to cancel, and explain any consequences of cancelling.

If your application is interactive and utilizes “online_access” or “offline_access”, it should present a link to the end user that allows the user to manage their current authorizations. Generally, such links are presented in conjunction with menu accessible from a status bar.

For information on how to discover the management endpoint for a user, see Discovery in the authorization specification.

Requesting Authorization on Behalf of a System

Certain types of applications and automated processes do not act on behalf of end users. Such access is generally utilized by a covered entity itself, or another entity covered under a business associate agreement.

Some FHIR® APIs support this model, allowing a client application to directly authenticate for access using a system account issued via Cerner Central System Account Management.

A client performs this request utilizing the “client credentials” flow of OAuth2 to request an access token, using the Basic authentication scheme for passing credentials. The following is a non-normative example of such a request:

Request:

POST /tenants/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/protocols/oauth2/profiles/smart-v1/token HTTP/1.1
Host: authorization.sandboxcerner.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

Note: This access model is only supported on resources where explicitly indicated in their respective FHIR® API resource documentation.

Frequently Asked Questions

The next sections discuss questions that application developers may pose that are not covered by the preceding documentation.

Cerner currently does not have a mechanism to allow such devices to participate in the authorization ecosystem. Cerner is tracking the progress of the IETF draft RFC “OAuth 2.0 Device Flow” for further evaluation of such capabilities.

Cerner currently does not have a mechanism that allows client applications to revoke refresh tokens. Cerner is currently tracking the progress of the IETF Proposed Standard RFC “OAuth 2.0 Token Revocation” for further evaluation of such capabilities.

While the Cerner authorization server provides OpenID Connect support, it does not currently implement any of the draft log-out specifications currently proposed by the community. Cerner continues to track on developments in this ecosystem.

As an alternative, you may offer the user a link to “Manage Authorized Applications”, which allows the user to log out via their SSO system.

Depending on how the browser was launched, your application may not have the ability to close the browser window. If you launched a fresh browser window directly, you may be able to use Windows APIs to find and send a close command directly to the window.

Cerner currently does not offer this capability at this time.

Yes, Cerner’s redirection URI validation allows for additional query parameters, per the OAuth specification.

NOTE: Cerner’s implementation uses strict path validation, which includes trailing slashes in your redirection URI.

Cerner does not currently support the registration of multiple redirection URIs; it is under consideration.

Yes, Cerner offers the ability for organizations providing their own app to disable the patient-mediated authorization workflow when used in context with their organization.

NOTE: Cerner currently does not support offline_access support for such applications.

No, Cerner currently does not have this capability. It is currently under consideration.

A general-purpose framework for embedding SMART® on FHIR® applications does not currently exist.

Disable or rotate your system account via Cerner Central as soon as possible via Cerner Central System Account Management.

Cerner does not currently have support for offline_access for providers. It is currently under consideration.

Cerner currently does not have guidance on how to deliver native applications running within their own dedicated Citrix container. Such applications would generally interact with the authorization server from a browser hosted within the application’s Citrix environment, unless other steps are taken to allow for interaction with the browser on the device where Citrix Receiver is run.

References