|J. Richer, Ed.|
|Harvard Medical School Department of Biomedical Informatics|
|September 25, 2015|
Health Relationship Trust Profile for Fast Healthcare Interoperability Resources (FHIR) OAuth 2.0 Scopes
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 scope specifications accommodate a wide range of implementations with varying security and usability considerations, across different types of software clients. To achieve this flexibility, the standard makes many security controls optional. OAuth implementations using only the minimum mandatory security measures require minimal effort on the part of developers and users, but they also fail to prevent known attacks and are unsuitable for protecting sensitive data. 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 [RFC2119].
All uses of JSON Web Signature (JWS) [RFC7517] and JSON Web Encryption (JWE) [RFC7518] 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 [RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [RFC7519], and the terms defined by OpenID Connect Core 1.0 [OpenID.Core].
In OAuth, scopes define individual pieces of authority that can be requested by clients, granted by resource owners, and enforced by resource servers. Specific scope values will be highly dependent on the specific types of resources being protected in a given interface. OpenID Connect [OpenID.Core], for example, defines scope values to enable access to different attributes of user profiles.
Scopes can be used to indicate access to different kinds of things in an API. Common examples include:
While all of these are valid means for defining scopes, not all of them work for different kinds of APIs.
In this specification, the 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 4.
This specification does not define a wildcard (asterisk, "*") general resource type definition.
The resource type indicates the kind of FHIR resource and consequently the kind of information available at it. This specification defines the following possible values.
Extensions to this specification MAY define additional specific resource types using the registry defined in Section 4. The name of the resource type SHOULD match the name of the associated FHIR resource.
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 4.
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.
For interactive OAuth flows such as the authorization code and implicit flows, the authorization server can present a selection screen to the user on the authorization screen, allowing them to select from a set of available options. Alternatively, 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.
This specification creates three registries for the values in the three different components of the scope.
|[OpenID.Core]||Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", November 2014.|
|[RFC2119]||Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.|
|[RFC2246]||Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, DOI 10.17487/RFC2246, January 1999.|
|[RFC3986]||Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.|
|[RFC5246]||Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008.|
|[RFC5322]||Resnick, P., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008.|
|[RFC5646]||Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009.|
|[RFC5785]||Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010.|
|[RFC6125]||Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011.|
|[RFC6749]||Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012.|
|[RFC6750]||Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012.|
|[RFC6819]||Lodderstedt, T., McGloin, M. and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013.|
|[RFC7033]||Jones, P., Salgueiro, G., Jones, M. and J. Smarr, "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 2013.|
|[RFC7517]||Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015.|
|[RFC7518]||Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015.|
|[RFC7519]||Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015.|
The OpenID Community would like to thank the following people for their contributions to this specification:
The 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, 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.
Copyright (c) 2015 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.