J. Richer, Ed. J. Mandel Harvard Medical School Department of Biomedical Informatics July 8, 2018 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Notation and Conventions . . . . . . . . . . 2 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 2. Resource Access Scopes . . . . . . . . . . . . . . . . . . . 3 2.1. Permission type . . . . . . . . . . . . . . . . . . . . . 3 2.2. Resource type . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Access type . . . . . . . . . . . . . . . . . . . . . . . 5 3. Confidentiality and Sensitivity . . . . . . . . . . . . . . . 5 4. Break the glass . . . . . . . . . . . . . . . . . . . . . . . 7 5. Resource selection . . . . . . . . . . . . . . . . . . . . . 7 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6.1. HEART Permission Type Registry . . . . . . . . . . . . . 9 6.1.1. Registration Template . . . . . . . . . . . . . . . . 10 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 6.2. HEART Access Type Registry . . . . . . . . . . . . . . . 11 6.2.1. Registration Template . . . . . . . . . . . . . . . . 11 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 12 6.3. Additions to the OAuth Parameters Registry . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 Richer & Mandel Expires January 9, 2019 [Page 1] HEART FHIR OAuth 2.0 July 2018 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13 9. Normative References . . . . . . . . . . . . . . . . . . . . 13 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 Appendix B. Fully computed scope values . . . . . . . . . . . . 15 Appendix C. Purpose of Use . . . . . . . . . . . . . . . . . . . 18 Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . 18 Appendix E. Document History . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 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 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]. Richer & Mandel Expires January 9, 2019 [Page 2] HEART FHIR OAuth 2.0 July 2018 2. Resource Access Scopes 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. 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. Richer & Mandel Expires January 9, 2019 [Page 3] HEART FHIR OAuth 2.0 July 2018 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. 2.2. Resource type 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". Patient Demographic information about the patient, http://www.hl7.org/fhir/stu3/patient.html MedicationRequest Information about requests for medications for patients, http://www.hl7.org/fhir/stu3/medicationrequest.html MedicationDispense Information about supply of medications to a patient, http://www.hl7.org/fhir/stu3/medicationdispense.html MedicationAdministration Information about medications consumption or other administration, http://www.hl7.org/fhir/stu3/ medicationadministration.html MedicationStatement Information about the believed state of a medication, http://www.hl7.org/fhir/stu3/medicationstatement.html Observation Information about observations performed by a healthcare provider, http://www.hl7.org/fhir/stu3/observation.html Appointment Information about scheduled appointments, http://www.hl7.org/fhir/stu3/appointment.html AllergyIntolerance Information about allergies and drug intolerance, http://www.hl7.org/fhir/stu3/allergyintolerance.html Richer & Mandel Expires January 9, 2019 [Page 4] HEART FHIR OAuth 2.0 July 2018 Condition Information about a patient's condition, http://www.hl7.org/fhir/stu3/condition.html Immunization Information about a patient's immunizations, http://www.hl7.org/fhir/stu3/immunization.html CarePlan 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. 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 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". write 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 Section 6. 3. Confidentiality and Sensitivity 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. conf/N Normal confidentiality Richer & Mandel Expires January 9, 2019 [Page 5] HEART FHIR OAuth 2.0 July 2018 conf/R Restricted confidentiality conf/V 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. sens/ETH Substance abuse sens/PSY Psychiatry sens/GDIS Genetic disease sens/HIV HIV/AIDS sens/SCA Sickle cell anemia sens/SOC Social services sens/SDV Sexual assault, abuse, or domestic violence sens/SEX Sexuality and reproductive health sens/STD Sexually transmitted disease sens/DEMO All demographic information sens/DOB Date of birth sens/GENDER Gender and sexual orientation sens/LIVARG Living arrangement sens/MARST Marital status sens/RACE Race sens/REL Religion sens/B Business information sens/EMPL Employer sens/LOCIS Location Richer & Mandel Expires January 9, 2019 [Page 6] HEART FHIR OAuth 2.0 July 2018 sens/SSP Sensitive service provider sens/ADOL Adolescent sens/CEL Celebrity sens/DIAG Diagnosis sens/DRGIS Drug information sens/EMP 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. 4. Break the glass 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. btg 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. 5. 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 Richer & Mandel Expires January 9, 2019 [Page 7] HEART FHIR OAuth 2.0 July 2018 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) or "rec" (records) parameters. aud A URI string representing the resource server where the client will access records. rec A URI string representing the specific patient record being accessed by the client. If the client does not provide a "rec" parameter in its request, the authorization server MUST perform one of these three actions: o 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. The authorization server SHOULD inform the user which record is being selected on an interactive authorization screen. o Return an "invalid_request" error response, indicating it was unable to determine which resource the client is requesting. o 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. Richer & Mandel Expires January 9, 2019 [Page 8] HEART FHIR OAuth 2.0 July 2018 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/", "rec": "https://resource.example.net/patient/123141/" } 6. IANA Considerations This specification creates two registries for the values in the two of the three different components of the resource access scope. 6.1. HEART Permission Type Registry This specification establishes the HEART Permission Type Registry. Permission types are registered by Specification Required [RFC5226] 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 Richer & Mandel Expires January 9, 2019 [Page 9] HEART FHIR OAuth 2.0 July 2018 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. 6.1.1. Registration Template Permission Type A string representation of the permission being registered, to be used in scope construction. Description: Brief description of the permission (e.g., "Example description"). Change controller: 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. Specification document(s): 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. 6.1.2. Initial Registry Contents The HEART Permission Type Registry contains the following definitions of scope components for permission types. o Scope Value: patient o Description: Access to a single patient record o Change Controller: OpenID Foundation (http://openid.net/) o Specification document(s):: [[ this document ]] o Scope Value: user o Description: Access to all records accessible to the current user o Change Controller: OpenID Foundation (http://openid.net/) o Specification document(s):: [[ this document ]] Richer & Mandel Expires January 9, 2019 [Page 10] HEART FHIR OAuth 2.0 July 2018 6.2. HEART Access Type Registry This specification establishes the HEART Access Type Registry. Access types are registered by Specification Required [RFC5226] 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. 6.2.1. Registration Template Access Type A string representation of the access being registered, to be used in scope construction. Description: Brief description of the access (e.g., "Example description"). Change controller: 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. Specification document(s): 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. Richer & Mandel Expires January 9, 2019 [Page 11] HEART FHIR OAuth 2.0 July 2018 6.2.2. Initial Registry Contents The HEART Access Type Registry contains the definitions of scope components for access types. o Scope Value: read o Description: Read access o Change Controller: OpenID Foundation (http://openid.net/) o Specification document(s):: [[ this document ]] o Scope Value: write o Description: Write access o Change Controller: OpenID Foundation (http://openid.net/) o Specification document(s):: [[ this document ]] o Scope Value: * o Description: All access o Change Controller: OpenID Foundation (http://openid.net/) o Specification document(s):: [[ this document ]] 6.3. Additions to the OAuth Parameters Registry This specification adds the following values to the OAuth Parameters Registry established by [RFC6749]. o Name: aud o Parameter usage location: authorization request, token request o Change Controller: IESG o Document: [[ this document ]] 7. Security Considerations 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 Richer & Mandel Expires January 9, 2019 [Page 12] HEART FHIR OAuth 2.0 July 2018 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. 8. Privacy Considerations 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 (Section 3) 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. 9. Normative References [HEART.OAuth2] Richer, J., Ed., "Health Relationship Trust Profile for OAuth 2.0", February 2016, . [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, . Richer & Mandel Expires January 9, 2019 [Page 13] HEART FHIR OAuth 2.0 July 2018 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", RFC 5226, DOI 10.17487/RFC5226, May 2008, . [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., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, . [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "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., Ed., "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., Ed., 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, . Richer & Mandel Expires January 9, 2019 [Page 14] HEART FHIR OAuth 2.0 July 2018 [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: Sarah Squire, Nancy Lush, Debbie Bucci, Eve Maler, Luis Maas, Thomas Sullivan Appendix B. Fully computed scope values 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. 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/MedicationRequest.read Read access to a single patient's requests for medications. patient/MedicationRequest.write Read and write access to a single patient's requests for medications. patient/MedicationRequest.* Full access to a single patient's requests for medications. Richer & Mandel Expires January 9, 2019 [Page 15] HEART FHIR OAuth 2.0 July 2018 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. Richer & Mandel Expires January 9, 2019 [Page 16] HEART FHIR OAuth 2.0 July 2018 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/MedicationRequest.read Read access to all authorized requests for medications. user/MedicationRequest.write Read and write access to all authorized requests for medications. user/MedicationRequest.* Full access to all authorized requests 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. Richer & Mandel Expires January 9, 2019 [Page 17] HEART FHIR OAuth 2.0 July 2018 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. Purpose of Use 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. Appendix D. Notices 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 Richer & Mandel Expires January 9, 2019 [Page 18] HEART FHIR OAuth 2.0 July 2018 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 E. Document History -2018-02-19 o Changed aud parameter to point to server not record o Added rec parameter to point to specific record -2017-05-25 o Changed purpose of use examples from roles to actions -2017-05-15 o Added note on purpose of use o Cleaned up IANA copy-paste errors -2017-04-29 Richer & Mandel Expires January 9, 2019 [Page 19] HEART FHIR OAuth 2.0 July 2018 o Added FHIR resource type references o Clarified that FHIR is canonical for resource types o Explicitly defined "read" and "write" as mapped to FHIR actions -2017-04-25 o Added additional FHIR resource types o Strengthened normative requirement for cross-resource scopes to be applied to all resources -2017-04-18 o Clarified that the resource types in scopes can be any valid FHIR resource but we're using examples from STU3 o Changed "MedicationOrder" to "MedicationRequest" o Removed introductory material about OAuth scopes o Clarified that "aud" is generally for single-patient uses o Added IANA registry templates -2017-04-10 o Added additional sensitivity category information from http://hl7.org/fhir/v3/InformationSensitivityPolicy/vs.html -2017-04-03 o Added clarifying information regarding sensitivity scopes. -2017-03-20 o Added confidentiality and sensitivity scopes -2017-02-27 o Added break the glass scope -2015-09-16 o Created first semantic scope profile Richer & Mandel Expires January 9, 2019 [Page 20] HEART FHIR OAuth 2.0 July 2018 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 Richer & Mandel Expires January 9, 2019 [Page 21]