Health Relationship Trust Profile for Fast Healthcare Interoperability Resources (FHIR) OAuth 2.0 Scopes

This document profiles the OAuth 2.0 web 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.

In this specification, scope values are a composite string describing the type of permission, the type of resource, and the type of access to that resource being requested. These scopes are plain strings made by combining the permission type, followed by a single forward slash "/" character, followed by the resource type, followed by a single period character ".", followed by the access type. The asterisk character "*" is reserved as a special value to stand in for any valid value within a category. The entire scope definition is: scope := permission/resource.access permission, resource, access := any string (without space, period, slash, or asterisk) | asterisk Strings within each category MUST NOT include the space " ", period ".", forward slash "/", or asterisk "*" character. Implementation of these scope strings is a matter of choice for the OAuth system. The authorization server and protected resource MAY decide to pre-compute all viable combinations within the system as simple strings as shown in , or they MAY decide to parse the values within the strings at run time. Protected resources MUST define and document which scopes are required for access to the resource, listing all appropriate scope component combinations including wildcards. Authorization servers SHOULD define and document default scope values that will be used if an authorization request does not specify a requested set of scopes.

The permission type component of a scope definition indicates whether the access being requested is for a single patient record or a bulk set of patient records. This specification defines two possible values. The scope is for a single patient's record, either for the current user or someone else that they have been given access to. The scope is for a bulk set of records or for aggregate data not representing a single patient, based on what is available to the current user. Extensions to this specification MAY define additional permission types using the registry defined in . The patient permission type SHOULD be used only with user-delegated access client types as defined in . The user permission type SHOULD be used only with bulk-access client types as defined in . This specification does not define a wildcard (asterisk, "*") general permission type definition.

The resource type indicates the kind of FHIR resource and consequently the kind of information available at it. Any FHIR resource MAY be used, and in particular this specification defines scopes for resources based on FHIR resource type designation for the Patient compartment as found on http://www.hl7.org/fhir/compartmentdefinition-patient.html. This document specifically lists the following common resources from FHIR version STU3. Full normative definitions for each type can be found at http://www.hl7.org/fhir/stu3/compartmentdefinition-patient.html. Demographic information about the patient, http://www.hl7.org/fhir/stu3/patient.html Information about requests for medications for patients, http://www.hl7.org/fhir/stu3/medicationrequest.html Information about supply of medications to a patient, http://www.hl7.org/fhir/stu3/medicationdispense.html Information about medications consumption or other administration, http://www.hl7.org/fhir/stu3/medicationadministration.html Information about the believed state of a medication, http://www.hl7.org/fhir/stu3/medicationstatement.html Information about observations performed by a healthcare provider, http://www.hl7.org/fhir/stu3/observation.html Information about scheduled appointments, http://www.hl7.org/fhir/stu3/appointment.html Information about allergies and drug intolerance, http://www.hl7.org/fhir/stu3/allergyintolerance.html Information about a patient's condition, http://www.hl7.org/fhir/stu3/condition.html Information about a patient's immunizations, http://www.hl7.org/fhir/stu3/immunization.html Information about a patient's care plan, http://www.hl7.org/fhir/stu3/careplan.html Wildcard representing all available resources under the given context. A protected resource MUST document which version of FHIR applies to the resources it offers.

The access type defines the kinds of actions that can be taken on a particular resource. This specification defines the following access types. Allows information to be read from the resource in a way that does not directly modify the resource. These interactions MAY include read, vread, history, search, and capabilities as defined at https://www.hl7.org/fhir/http.html. Allows information to be written to the resource. These interactions MAY include update, patch, delete, create, and batch/transaction as defined at https://www.hl7.org/fhir/http.html. Wildcard representing all possible actions under the given context. These interactions include those defined by the read and write scopes as well as any additional interactions supported by the resource. Extensions to this specification MAY define additional specific resource types using the registry defined in .

In addition to the scopes listed above, a client MAY request and an authorization server MAY issue tokens with the following scopes indicating that the token has been authorized by the AS for accessing information of a particular confidentiality level. Normal confidentiality Restricted confidentiality Very Restricted confidentiality An absence of a confidentiality scope makes no indication of the confidentiality of information therein. A client MAY request access to and an authorization server MAY issue tokens allowing access to data with particular sensitivities. Substance abuse Psychiatry Genetic disease HIV/AIDS Sickle cell anemia Social services Sexual assault, abuse, or domestic violence Sexuality and reproductive health Sexually transmitted disease All demographic information Date of birth Gender and sexual orientation Living arrangement Marital status Race Religion Business information Employer Location Sensitive service provider Adolescent Celebrity Diagnosis Drug information Employee Additional sensitivity scopes MAY be defined by using codes any of the FHIR Information Sensitivity Policy labels at http://hl7.org/fhir/v3/InformationSensitivityPolicy/vs.html. This specification makes no assumptions regarding the ability of resource servers to tag and filter data. A resource server that is capable of filtering information MUST advertise this capability through the use of these scopes. Resource servers SHOULD use this access information to filter out data being returned to a client, if possible. If an access token does not contain a given confidentiality or sensitivity marker, the resource server SHOULD assume that the client does not have access to that information and SHOULD apply appropriate filters to the data, where possible.

A special scope is used to indicate that access is requested when the resource owner is unavailable. This scope is in addition to any of the resource-marked identifications above. The resource is intended to be accessed when the resource owner is unavailable. The means by which the authorization server determines which clients are allowed access to the btg scope is outside the scope of this document. If the resource server receives a token that includes the btg scope, the resource server MUST log such access in an auditable format available to the resource owner.

In many OAuth transactions, the client does not need to indicate to the authorization server the protected resource that it is trying to access, as that information is discernible from the context of the scopes and the resource owner present during authorization. For example, a patient authorizing access to their own record would not need to specify which record is theirs since the resource server would presumably be able to find the record based on the identity of the resource owner. In other transactions, the resource owner will need to specify to the authorization server and resource server which protected resource is to be accessed. For example, a user with access to not only their own patient record but also that of their children would need to specify which record is to be accessed by the client. If the client knows the protected resource that it is trying to gain access to, it can indicate this protected resource to the authorization server during the request to the authorization endpoint (for the authorization code and implicit flow) or the token endpoint (for the client credentials flow) using the OPTIONAL aud (audience) parameter. A URI string representing the protected resource which this authorization request is directed toward. This URI MUST be a patient's record, consisting of many resources or a specific FHIR resource for a given patient. If the client does not provide an aud parameter in its request, the authorization server MUST perform one of these three actions: Select a default resource based on the resource owner's identity, such as selecting the resource representing the resource owner themselves. This is anticipated to be the default behavior in most cases. Return an invalid_request error response, indicating it was unable to determine which resource the client is requesting. Allow the resource owner to interactively select or specify an appropriate resource on the authorization page. The authorization server SHOULD either select a default resource or give the resource owner an opportunity to specify the resource if none is selected, reserving the error response for cases in which neither of these are possible. If a specific resource is selected, the authorization server MUST return an aud parameter in the token response to the client containing the audience identifier value. For example, when using the authorization code grant type the response would be as follows.

This specification creates two registries for the values in the two of the three different components of the resource access scope.

This specification establishes the HEART Permission Type Registry. Permission types are registered by Specification Required after a two-week review period on the openid-specs-heart@openid.net mailing list, on the advice of one or more Designated Experts. Criteria that should be applied by the Designated Experts includes determining whether the proposed registration duplicates existing functionality, whether it is likely to be of general applicability or whether it is useful only for a single application, and whether the registration description is clear. Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register HEART Permission Type: example"). Within the review period, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. IANA must only accept registry updates from the Designated Expert(s) and should direct all requests for registration to the review mailing list.

A string representation of the permission being registered, to be used in scope construction. Brief description of the permission (e.g., "Example description"). For Standards Track RFCs, state "IESG". For other documents, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Reference to the document(s) that specify the token endpoint authorization method, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

The HEART Permission Type Registry contains the following definitions of scope components for permission types. Scope Value: patient Description: Access to a single patient record Change Controller: OpenID Foundation (http://openid.net/) Specification document(s):: [[ this document ]] Scope Value: user Description: Access to all records accessible to the current user Change Controller: OpenID Foundation (http://openid.net/) Specification document(s):: [[ this document ]]

This specification establishes the HEART Access Type Registry. Access types are registered by Specification Required after a two-week review period on the openid-specs-heart@openid.net mailing list, on the advice of one or more Designated Experts. Criteria that should be applied by the Designated Experts includes determining whether the proposed registration duplicates existing functionality, whether it is likely to be of general applicability or whether it is useful only for a single application, and whether the registration description is clear. Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register HEART Permission Type: example"). Within the review period, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. IANA must only accept registry updates from the Designated Expert(s) and should direct all requests for registration to the review mailing list.

A string representation of the access being registered, to be used in scope construction. Brief description of the access (e.g., "Example description"). For Standards Track RFCs, state "IESG". For other documents, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Reference to the document(s) that specify the token endpoint authorization method, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

The HEART Access Type Registry contains the definitions of scope components for access types. Scope Value: read Description: Read access Change Controller: OpenID Foundation (http://openid.net/) Specification document(s):: [[ this document ]] Scope Value: write Description: Write access Change Controller: OpenID Foundation (http://openid.net/) Specification document(s):: [[ this document ]] Scope Value: * Description: All access Change Controller: OpenID Foundation (http://openid.net/) Specification document(s):: [[ this document ]]

This specification adds the following values to the OAuth Parameters Registry established by . Name: aud Parameter usage location: authorization request, token request Change Controller: IESG Document: [[ this document ]]

Access tokens MAY have multiple scopes of potentially different types associated with them. Each additional scope is additive to the capabilities of the token. An authorization token containing multiple scopes MUST be treated as appropriate for all combinations of scopes in the token. For example, if an access token contains patient/Observation.*, patient/MedicationOrder.read, and ETH, then the ETH scope SHOULD be applied by the RS to both the patient/Observation.* and patient/MedicationOrder.read record types. Use cases requiring more fine grained access for combinations SHOULD use multiple tokens with only the appropriate rights associated with them.

Resource servers should register or advertise scopes as a statement of capabilities, not as an indication of the absence or presence of particular kinds of data. This is especially pertinent with regard to the confidentiality and sensitivity scopes. Namely, if a resource server is associated with the sens/PSY scope, it is indicating that it has the capability to filter out psychiatry information, not that it currently holds any psychiatry information. Likewise, if a resource server is not associated with the sens/PSY scope, it is indicating that it does not have the ability to process or filter out psychiatry information, not that it contains no information that is psychiatric in nature.

OpenID Connect Core 1.0 Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Health Relationship Trust Profile for OAuth 2.0

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, Nancy Lush, Debbie Bucci, Eve Maler, Luis Maas, Thomas Sullivan

The resource access scopes in this specification are composed from individual components, but scopes in OAuth are treated as string by many parts of the system. Clients, authorization servers, and protected resources should not be expected to compose these strings from parts, merely be able to understand the rights associated with a given string. Consequently, we are providing here a table of pre-computed values for all possible scope string combinations defined form the components in this document, along with their meaning. Read access to a single patient's demographic information. Read and write access to a single patient's demographic information. Full access to a single patient's demographic information. Read access to a single patient's requests for medications. Read and write access to a single patient's requests for medications. Full access to a single patient's requests for medications. Read access to supply of medications to a single patient. Read and write access to supply of medications to a single patient. Full access to supply of medications to a single patient. Read access to a single patient's medications consumption or other administration. Read and write access to a single patient's medications consumption or other administration. Full access to a single patient's medications consumption or other administration. Read access to the believed state of a medication for a single patient. Read and write access to the believed state of a medication for a single patient. Full access to the believed state of a medication for a single patient. Read access to a single patient's observations performed by a healthcare provider. Read and write access to a single patient's observations performed by a healthcare provider. Full access to a single patient's observations performed by a healthcare provider. Read access to a single patient's scheduled appointments. Read and write access to a single patient's scheduled appointments. Full access to a single patient's scheduled appointments. Read access to a single patient's complete records. Read and write access to a single patient's complete records. Full access to a single patient's complete records. Read access to all authorized demographic information. Read and write access to all authorized demographic information. Full access to all authorized demographic information. Read access to all authorized requests for medications. Read and write access to all authorized requests for medications. Full access to all authorized requests for medications. Read access to all authorized supply of medications. Read and write access to all authorized supply of medications. Full access to all authorized supply of medications. Read access to all authorized medications consumption or other administration. Read and write access all authorized medications consumption or other administration. Full access to all authorized medications consumption or other administration. Read access to all authorized believed states of medication. Read and write access to all authorized believed states of medication. Full access to all authorized believed states of medication. Read access to all authorized observations performed by a healthcare provider. Read and write access to all authorized observations performed by a healthcare provider. Full access to all authorized observations performed by a healthcare provider. Read access to all authorized scheduled appointments. Read and write access to all authorized scheduled appointments. Full access to all authorized scheduled appointments. Read access to all authorized complete records. Read and write access to all authorized complete records. Full access to all authorized complete records.

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

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.

-2017-05-25 Changed purpose of use examples from roles to actions -2017-05-15 Added note on purpose of use Cleaned up IANA copy-paste errors -2017-04-29 Added FHIR resource type references Clarified that FHIR is canonical for resource types Explicitly defined "read" and "write" as mapped to FHIR actions -2017-04-25 Added additional FHIR resource types Strengthened normative requirement for cross-resource scopes to be applied to all resources -2017-04-18 Clarified that the resource types in scopes can be any valid FHIR resource but we're using examples from STU3 Changed "MedicationOrder" to "MedicationRequest" Removed introductory material about OAuth scopes Clarified that "aud" is generally for single-patient uses Added IANA registry templates -2017-04-10 Added additional sensitivity category information from http://hl7.org/fhir/v3/InformationSensitivityPolicy/vs.html -2017-04-03 Added clarifying information regarding sensitivity scopes. -2017-03-20 Added confidentiality and sensitivity scopes -2017-02-27 Added break the glass scope -2015-09-16 Created first semantic scope profile