J. Richer, Ed.
J. Mandel
Harvard Medical School Department of Biomedical Informatics
September 25, 2015

Health Relationship Trust Profile for Fast Healthcare Interoperability Resources (FHIR) OAuth 2.0 Scopes
openid-heart-fhir-oauth2

Abstract

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.


Table of Contents

1. Introduction

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.

1.1. Requirements Notation and Conventions

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.

1.2. Terminology

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

2. Scopes design

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.

2.1. Permission type

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.

patient
The scope is for a single patient's record, either for the current user or someone else that they have been given access to.
user
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 Section 4.

This specification does not define a wildcard (asterisk, "*") general resource type definition.

2.2. Resource type

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.

Patient
Demographic information about the patient.
MedicationOrder
Information about orders for medications.
MedicationDispense
Information about supply of medications to a patient.
MedicationAdministration
Information about medications consumption or other administration.
MedicationStatement
Information about the believed state of a medication.
Observation
Information about observations performed by a healthcare provider.
Appointment
Information about scheduled appointments.
*
Wildcard representing all available resources under the given context.

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.

2.3. Access type

The access type defines the kinds of actions that can be taken on a particular resource. This specification defines the following access types.

read
Allows information to be read from the resource.
write
Allows information to be read from or written to the resource.
*
Wildcard representing all possible actions under the given context.

Extensions to this specification MAY define additional specific resource types using the registry defined in Section 4.

3. Resource selection

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.

aud
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:

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.

4. IANA Considerations

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

5. Normative References

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

Appendix A. Acknowledgements

The OpenID Community would like to thank the following people for their contributions to this specification:

Appendix B. Fully computed scope values

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.

patient/Patient.read
Read access to a single patient's demographic information.
patient/Patient.write
Read and write access to a single patient's demographic information.
patient/Patient.*
Full access to a single patient's demographic information.
patient/MedicationOrder.read
Read access to a single patient's orders for medications.
patient/MedicationOrder.write
Read and write access to a single patient's orders for medications.
patient/MedicationOrder.*
Full access to a single patient's orders for medications.
patient/MedicationDispense.read
Read access to supply of medications to a single patient.
patient/MedicationDispense.write
Read and write access to supply of medications to a single patient.
patient/MedicationDispense.*
Full access to supply of medications to a single patient.
patient/MedicationAdministration.read
Read access to a single patient's medications consumption or other administration.
patient/MedicationAdministration.write
Read and write access to a single patient's medications consumption or other administration.
patient/MedicationAdministration.*
Full access to a single patient's medications consumption or other administration.
patient/MedicationStatement.read
Read access to the believed state of a medication for a single patient.
patient/MedicationStatement.write
Read and write access to the believed state of a medication for a single patient.
patient/MedicationStatement.*
Full access to the believed state of a medication for a single patient.
patient/Observation.read
Read access to a single patient's observations performed by a healthcare provider.
patient/Observation.write
Read and write access to a single patient's observations performed by a healthcare provider.
patient/Observation.*
Full access to a single patient's observations performed by a healthcare provider.
patient/Appointment.read
Read access to a single patient's scheduled appointments.
patient/Appointment.write
Read and write access to a single patient's scheduled appointments.
patient/Appointment.*
Full access to a single patient's scheduled appointments.
patient/*.read
Read access to a single patient's complete records.
patient/*.write
Read and write access to a single patient's complete records.
patient/*.*
Full access to a single patient's complete records.
user/Patient.read
Read access to all authorized demographic information.
user/Patient.write
Read and write access to all authorized demographic information.
user/Patient.*
Full access to all authorized demographic information.
user/MedicationOrder.read
Read access to all authorized orders for medications.
user/MedicationOrder.write
Read and write access to all authorized orders for medications.
user/MedicationOrder.*
Full access to all authorized orders for medications.
user/MedicationDispense.read
Read access to all authorized supply of medications.
user/MedicationDispense.write
Read and write access to all authorized supply of medications.
user/MedicationDispense.*
Full access to all authorized supply of medications.
user/MedicationAdministration.read
Read access to all authorized medications consumption or other administration.
user/MedicationAdministration.write
Read and write access all authorized medications consumption or other administration.
user/MedicationAdministration.*
Full access to all authorized medications consumption or other administration.
user/MedicationStatement.read
Read access to all authorized believed states of medication.
user/MedicationStatement.write
Read and write access to all authorized believed states of medication.
user/MedicationStatement.*
Full access to all authorized believed states of medication.
user/Observation.read
Read access to all authorized observations performed by a healthcare provider.
user/Observation.write
Read and write access to all authorized observations performed by a healthcare provider.
user/Observation.*
Full access to all authorized observations performed by a healthcare provider.
user/Appointment.read
Read access to all authorized scheduled appointments.
user/Appointment.write
Read and write access to all authorized scheduled appointments.
user/Appointment.*
Full access to all authorized scheduled appointments.
user/*.read
Read access to all authorized complete records.
user/*.write
Read and write access to all authorized complete records.
user/*.*
Full access to all authorized complete records.

Appendix C. Notices

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.

Appendix D. Document History

-2015-09-16

Authors' Addresses

Justin Richer (editor) EMail: openid@justin.richer.org
Josh Mandel Harvard Medical School Department of Biomedical Informatics EMail: Joshua.Mandel@childrens.harvard.edu