| J. Richer, Ed. | |
| J. Mandel | |
| Harvard Medical School Department of Biomedical Informatics | |
| May 25, 2017 |
Health Relationship Trust Profile for Fast Healthcare Interoperability Resources (FHIR) OAuth 2.0 Scopes
openid-heart-fhir-oauth2
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 OAuth 2.0 protocol framework defines a mechanism to allow a resource owner to delegate access to a protected resource for a client application, optionally limited by a set of scopes.
This specification profiles the OAuth 2.0 protocol scopes 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 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 Appendix B, 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.
Extensions to this specification MAY define additional permission types using the registry defined in Section 6.
The patient permission type SHOULD be used only with user-delegated access client types as defined in [HEART.OAuth2]. The user permission type SHOULD be used only with bulk-access client types as defined in [HEART.OAuth2]. 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.
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.
Extensions to this specification MAY define additional specific resource types using the registry defined in Section 6.
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.
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.
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 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.
If the client does not provide an aud parameter in its request, the authorization server MUST perform one of these three actions:
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.
HTTP/1.1 200 OK
Date: Tue, 16 Dec 2014 03:00:14 GMT
Access-Control-Allow-Origin: *
Content-Type: application/json;charset=ISO-8859-1
Connection: close
{
"access_token": "eyJhbGciOiJSUzI1NiJ9.ew0KICAgImV4cCI6IDE0MTg3MDIzODgsDQogICAiYXpwIjo
gIjU1ZjlmNTU5LTI0OTYtNDlkNC1iNmMzLTM1MWE1ODZiNzQ4NCIsDQogICAiaXNzIjo
gImh0dHBzOi8vaWRwLXAuZXhhbXBsZS5jb20vIiwNCiAgICJqdGkiOiAiMjQwMmY4N2M
tYjZjZS00NWM0LTk1YjAtN2EzZjI5MDQ5OTdmIiwNCiAgICJpYXQiOiAxNDE4Njk4Nzg
4LA0KICAgImtpZCI6ICJyc2ExIg0KfQ.iB6Ix8Xeg-L-nMStgE1X75w7zgXabzw7znWU
ECOsXpHfnYYqb-CET9Ah5IQyXIDZ20qEyN98UydgsTpiO1YJDDcZV4f4DgY0ZdG3yBW3
XqwUQwbgF7Gwza9Z4AdhjHjzQx-lChXAyfL1xz0SBDkVbJdDjtXbvaSIyfF7ueWF3M1C
M70-GXuRY4iucKbuytz9e7eW4Egkk4Aagl3iTk9-l5V-tvL6dYu8IlR93GKsaKE8bng0
EZ04xcnq8s4V5Yykuc_NARBJENiKTJM8w3wh7xWP2gvMp39Y0XnuCOLyIx-J1ttX83xm
pXDaLyyY-4HT9XHT9V73fKF8rLWJu9grrA",
"scope": "patient/*.* sens/ETH sens/PSY btg",
"token_type": "Bearer",
"aud": "https://resource.example.net/patient/123141/"
}
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.
The HEART Permission Type Registry contains the following definitions of scope components for permission types.
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.
The HEART Access Type Registry contains the definitions of scope components for access types.
This specification adds the following values to the OAuth Parameters Registry established by [RFC6749].
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.
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.
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 Section 4. 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
-2017-05-15
-2017-04-29
-2017-04-25
-2017-04-18
-2017-04-10
-2017-04-03
-2017-03-20
-2017-02-27
-2015-09-16