openid@justin.richer.org

OpenID Heart Working Group FHIR is an HTTP-based, resource-oriented RESTful API based on a set of clinical, administrative, financial, and infrastructure resource definitions. The API supports create, read, update, delete, and search operations, as well as a framework for ad-hoc operations. The User-Managed Access (UMA) protocol framework defines a mechanism to allow a resource owner to delegate access to a protected resource for a client application used by a requesting party (identified by a set of claims), optionally limited by a set of scopes. This specification profiles the resource types and claim types to be used with the FHIR protocol to increase baseline security, provide greater interoperability, and structure deployments in a manner specifically applicable to (but not limited to) the healthcare domain.

This document profiles the UMA authorization framework for use in the context of securing Representational State Transfer (RESTful) interfaces using the Fast Health Interoperable Resources (FHIR) protocol. The FHIR OAuth 2.0 profile defined in this document serve to define a baseline set of FHIR OAuth scopes suitable for a wide range of use cases, while maintaining reasonable ease of implementation and functionality.

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 RFC 2119. All uses of JSON Web Signature (JWS) and JSON Web Encryption (JWE) data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.

This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0, the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT), and the terms defined by OpenID Connect Core 1.0.

Resource sets MUST be registered by the resource server at the authorization server before they can be accessed by clients. Resources MUST be structured in such a way that an unauthorized request to the resource (with no access token) can be mapped to an appropriate resource set, resource owner, and authorization server.

Resource sets MUST include a type identifier describing the kind of FHIR resources being protected, based on the FHIR compartment or resource that fits the data being protected. For compartments, this value SHALL be a URL of the form http://www.hl7.org/fhir/compartmentdefinition-<compartmentname>.html, where <compartmentname> is the FHIR compartment type designation as found on http://www.hl7.org/fhir/compartmentdefinition.html. For resources, this value SHALL be a URL in the form http://www.hl7.org/fhir/<resourcename>.html, where <resourcename> is the FHIR resource type designation as found on http://www.hl7.org/fhir/resourcelist.html.

Resource sets MUST specify at least one resource access scope as defined in section 2 of . Additionally, the resource MAY use any of the scopes defined in section 3 regarding confidentiality and sensitivity, or in section 4 regarding emergency (break the glass).

For determining access to healthcare records, it's useful to define a standard set of claims that can be used across domains to represent common access conditions. The following claims are defined as additional claims to be included in a user's OpenID Connect ID token or UserInfo Endpoint response. The claims used for processing MUST be considered in the context of the issuer of these claims. The method by which an authorization server determines which issuers are allowed to make which claims is out of scope of this specification.

To include all members of an organization, such as a hospital, include the org claim. Array of machine-readable URIs representing organizations that the user is a part of. If the value of org is the same as the iss of the ID token, it SHOULD be taken as authoritative.

To reference licenses, accreditations, or other professional credentials held by the current user, include the pro claim. These are generally for things such as specific medical licenses or degrees. Array of machine-readable values representing the professional credential held by the current user. Each pro value consists of a JSON object with the following members: URI representing the authority conveying the professional credential on the user, such as a state or regulatory group String value representing the nature of the processional credential held. The value of the professional credential is dependent on and potentially defined in the context of the authoritative source. An example list of professional values can be found at http://www.hl7.org/fhir/v2/0360/2.7/index.html. The means by which a given organization is trusted to convey a given professional status to an organization is outside the scope of this document. Note that the src claim here is likely to be different from the iss of the ID token, and the means by which an issuer is trusted to assert holding of accreditation from a particular source is outside the scope of this specification.

To reference an individual, an authorization server MAY use the email claim. To determine which server is authoritative for a given email domain at runtime, an authorization server MAY take the target email address and perform a webfinger lookup of the OpenID Connect issuer. The discovered issuer SHOULD be considered canonical for email addresses from that domain.

Those with a need for emergency access can be flagged with the er claim. Boolean indicating, if present and true, that the current user has emergency responder status and SHOULD be given access to records for emergency use without requiring the input of the resource owner by the way of a "break the glass" emergency access policy (see )

While a wide range of policies and policy engines are available to implementors, there are some general recommendations regarding the use of such policies with medical records. An authorization server SHOULD provision a newly registered resource set with a default-deny policy, such that sharing is allowed only when the resource owner explicitly shares it. Authorization servers MUST provide resource owners with the means to set policies based on any of the claims in this document referencing any of the scopes allowed in . Authorization servers MUST provide a means for resource owners to audit which policies are in effect at any protected resources controlled by the resource owner.

Authorization servers SHOULD provide a mechanism to specify a policy to accept certain flags, including but not limited to the er claim provided by trusted identity providers, to gain access to the resource set without direct involvement by the resource owner. This type of policy MUST include access to the btg scope specified in the HEART OAuth FHIR profile.

All claims presented to an authorization server need to be taken in the context of the presenter and issuer of the claim, and therefore trusted only in so much as the issuer is trusted to assert such claims. For example, an end user run identity provider should not be considered the canonical source for medical license information, unless the authorization server accepting the assertions has an external relationship with that identity provider that provides such trust.

Since the initial request for a resource is made in an unauthorized and unauthenticated context, such requests are by definition open to all users. The response of that request includes a pointer to the authorization server to query for an access token and present claims. If it is known out of band that authorization server is owned and controlled by a single user, or visiting the authorization server contains other identifying information, then an unauthenticated and unauthorized client would be able to tell which resource owner is associated with a given resource. In the FHIR API, this means that a client would be able to discern which patient a given record is for without being authorized for that information and without the resource server giving that information explicitly. Other information about the resource owner, such as organizational affiliation or group membership, may be gained from this transaction as well.

Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce

openid@justin.richer.org http://justin.richer.org/

openid@justin.richer.org http://justin.richer.org/

The OpenID Community would like to thank the following people for their contributions to this specification: Sarah Squire, Eve Maler, Luis Maas, Thomas Sullivan, Nancy Lush

Copyright (c) 2017 The OpenID Foundation. The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.

The ability to specify information be made available for a specific purpose of use is key to many different medical information use cases. For example, a patient might determine that some things are available for research, while others are only available for treatment. At this time, these specifications do not define methods for indicating purpose of use beyond the "emergency access" claim defined in and the "break the glass" mechanism defined in . The working group anticipates that expansion of this mechanism in implementations, which could lead to expansions of this protocol going forward.

-2017-05-25 Changed purpose of use examples from roles to actions -2017-05-15 Added note on purpose of use -2017-04-29 Minor wording tweak. -2017-04-18 Changed resource types to point to compartments instead of individual resource types Changed scopes to point to HEART OAuth FHIR scopes in entirety instead of being broken out Removed purpose of use claim (pou) Added a link to an example set of professional credential claims Added security considerations for claim provenance -2017-03-20 Clarified "er" scope Added reference to confidentiality and sensitivity scopes in HEART.OAuth.FHIR Changed "licenses" to "professional credentials" -2017-02-24 Added section on claims Added section on policy development -2017-02-10 Added scope and resource type requirements Created first semantic UMA profile