cross organizational auth
This document is a working draft of a OAuth 2.0 profile to support the EHR-to-EHR use case defined by The Argonaut Project.
This profile of OAuth 2.0 specifies the application programming interface (API) for the organization-to-organization exchange described in the Argonaut Project's use case 5. This profile enables an electronic health record (EHR) system in one organization to access FHIR resources managed by an EHR system in another organization, on a user's behalf.
The profile implements the authorization code method of granting authorization, as specified in the OAuth 2.0 Authorization Framework RFC 6749 and uses JSON Web Tokens RFC 7523 for two purposes:
- Client Authentication
- Authorization Grants
The trust relationship between the EHR authorization servers of the two exchanging organizations allows each to enforce local institutional policy within its own EHR context, while enabling access to FHIR resources in accordance with policy agreed upon between the two organizations. Essentially, access mediation occurs at two points:
-
When the requesting EHR's (EHR-A) authorization server decides whether to grant the end user’s request for a cross-entity query of FHIR resources held by the second organization (EHR-B), and
-
When the EHR-B authorization server decides whether to grant EHR-A access to the requested FHIR resources.
Similarly, the EHR-to-EHR exchange involves two “client” entities – the “client” through which the end-user submits the request, and the EHR-A authorization server, which acts as a “client” in the exchange with EHR-B. The workflow through which the end-user requests a resource, and the process through which such request is mediated within an organization, are outside the scope of this specification. This specification focuses on the application programming interface through which an organization desiring a FHIR resource held by another organization requests and is granted (or denied) access.
The authorization JWT conveys the identity of the authenticated end user, and contains details about the FHIR resource to which EHR A is requesting access. The authentication JWT is used to authenticate the identity of the EHR-A authorization server (as “client” to EHR-B). In advance of this exchange, EHR A will have registered its own identity and end-point URI with EHR B. The digitally signed authentication JWT confirms that the sender is the registered “client.”
While a single authorization JWT could be used for both purposes, this specification calls for the use of separate authentication and authorization JWTs to allow for potential future use cases wherein a third party might generate an authorization JWT that is presented by an EHR that is trusted by the data holder. Treating authentication and authorization as two separate claims enables support for such use cases under one consistent set of processing rules.
This specification does not address inter-organizational agreements or specific policies enforced by the organizations involved in the exchange.
This specification does not address the workflow involved in enabling an end-user to request an external resource, nor the workflow for presenting the retrieved resource to the end-user.
The Argonaut EHR-to-EHR use case states as a pre-condition that the requesting EHR knows the patient identifier used by the data holder to identify the individual whose data are being requested. Therefore, the design described here is silent about how patient matching is accomplished. However, recognizing the challenges associated with patient matching, a developer might choose to implement a "match" step as a separate operation, which could then be called like:
-
EHR-A calls EHR-B's "match" to obtain a match iD (opaque string representing the match).
-
EHR-A passes the match string as a claim in the authorization JWT (rather than including a
Patientresource directly.
The two organizations that operate the EHRs involved in the exchange dictate the rules under which FHIR resources may be requested and accessed. Each EHR’s authorization server controls security-critical operations, including client registration, authentication, JWT validation, authorized scopes, and the structure and format of access requests. The implementation and management of the authorization server is critical to the protection of FHIR resources, and to adherence with any agreements in place between the two organizations sharing data. The use of Transport Layer Security (TLS) to secure links between the two organizations protects against interception of sensitive information, and digital signatures protect against forgery of JWTs. Each organization will need to implement protections against denial-of-service attacks against the exposed interface.
To protect against token forgery and interception, the FHIR resource server must validate the access token, and assure that the resource requested is within the bounds of the access authorized.
The strength of the security mechanisms incorporated in this profile is highly dependent upon encryption keys, as they are used to establish the TLS channel between entities and to digitally sign the JWTs. Effective key management policies and procedures are essential for both organizations. See NIST Special Publication 800-57, Recommendation for Key Management: Part I for guidance in this area.
- HL7 FHIR RESTful API
- FHIR resource conformance specification
- RFC2616, IETF Hypertext Transfer Protocol – HTTP/1.1
- RFC3986, IETF Uniform Resource Identifier (URI): Generic Syntax
- RFC5246, The Transport Layer Security Protocol, V1.2
- RFC6749, The OAuth 2.0 Authorization Framework
- RFC6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage
- RFC6819, OAuth 2.0 Threat Model and Security Considerations
- RFC7517, JSON Web Key
- RFC7521, Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants
- RFC7523, JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants
- [RFC7591)(https://www.rfc-editor.org/rfc/rfc7591.txt), OAuth 2.0 Dynamic Client Registration Protocol
This profile inherits terminology from the standards referenced above.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in RFC2119.
Table 1 below defines some of the terms defined in the standards referenced above and used in this profile specification. The definitions in the table are customized to apply to this specification and are not meant to supersede or modify the terms’ original authoritative definitions in the respective standards.
|Term |Description |
|------|----------|------------|
Access token | A token that EHR-B issues to EHR-A (as client to EHR-B) and which EHR-A then passes to EHR-B's FHIR resource server as proof of access authorization.
Authorization endpoint | EHR-B's authorization server endpoint (URI) to which EHR-A submits authorization requests; the authorization endpoint authenticates EHR-A's identity and approves or denies authorization requests.
Authorization server | A server that implements the OAuth 2.0 authorization endpoint, token endpoint, and optionally other OAuth endpoints, and issues authorization tokens to clients. In this specification, EHR-A's authorization server, having authorized an internal request for an external FHIR resource, then acts as a client to EHR-B's authorization server to present the request on behalf of the end user.
Client | A software entity that requests OAuth access tokens from an authorization server.
FHIR resource | A health-information resource defined using the HL7 FHIR standard.
Token endpoint | The EHR-B authorization server endpoint to which EHR-A submits authorization and authentication JWTs in order to receive access tokens.
- An end-user of the EHR in the requesting organization (EHR-A) initiates a request, the details of which are outside the scope of this specification.
- EHR-A's authorization server prepares and digitally signs each of two JWTs: one describing the access for which authorization is being requested, and the other authenticating EHR-A's own identity (as pre-registered with EHR-B).
- EHR-A posts the two JWTs to EHR-B's API for requesting access to FHIR resources.
- EHR-B's authorization server validates each of the JWTs and mediates the access against organization B's policies. If access is denied, EHR-B returns a denial response.
- If the requested access is allowed, EHR-B's authorization server issues an access token specifying the access authorized (which may be different from that requested).
- EHR-B returns the access token to EHR-A and records the action as a disclosure of PHI.
- EHR-A presents the access token to EHR-B's FHIR resource server.
- EHR-B's FHIR server validates the access token and assures that it authorizes access to the resource being requested. If not, EHR-B returns a denial response.
- EHR-B returns the authorized resource to EHR-A.
In advance of the exchange profiled in this specification, the EHR-A authorization server MUST register with the EHR-B authorization server. If EHR-B chooses to implement dynamic registration, it is RECOMMENDED that the implementation be in accordance with RFC7591.
The EHR-A authorization server MUST have been issued a public and private key pair for use in digitally signing the JWTs. The EHR-A authorization server MUST have registered its public key with EHR-B by either sending the public key directly in the jwks metadata field or by registering a jwks_uri that MUST be reachable by the EHR-B authorization server. It is RECOMMENDED that EHR-A register its key using a jwks_uri if possible as this allows for key rotation more easily. The jwks field or the content available from the jwks_uri of a client MUST contain a public key in JWK Set format.
OAuth 2.0 authorization and resource servers MUST conform to applicable recommendations found in the Security Considerations sections of RFC6749 and RFC6819. EHR-B servers MUST protect all communications to and from their OAuth endpoints using TLS as specified in RFC5246. Minimally, the EHR-B server MUST authenticate itself to the requester (EHR-A). Depending upon the policy enforced by EHR-B, authentication of the EHR-A TLS endpoint is OPTIONAL.
Authorization servers MUST publish a conformance statement as defined in the FHIR resource conformance specification. The conformance statement describes the features implemented in the server, and the rules with which an application needs to conform.
The conformance statement MUST identify the following OAuth 2.0 endpoints:
-
issuer: The fully qualified issuer URI of the server -
authorization_endpoint: The fully qualified URI of the server’s authorization endpoint -
token_endpoint: The fully qualified URI of the server’s token endpoint -
jwks_uri: The fully qualified URI of the server’s public key in JSON Web Key Set (JWKS) format
The authorization JWT contains the details a remote EHR's authorization server will need to know in order to provide data access. These MUST include:
- Patient record being requested (
requested_record, a FHIR Patient resource) - Data required (
requested_scopes, e.g. "patient/*.read") - Requesting user (
requesting_practitioner, a FHIR Practitioner resource) - Level of assurance of the requesting user's identity (
acr, e.g. NIST level 0-4, as defined in NIST SP 800-63-2) - Reason for request (
reason_for_request, treatment? payment? research? ...)
It also contains claims necessary to help ensure the security of the exchange (expiration time, issuer, subject, a token identifier -- see https://tools.ietf.org/html/rfc7523 for details):
| claim | required? | description |
|---|---|---|
| iss | required | Requesting EHR's issuer URI. |
| sub | required | EHR A's id for the user on whose behalf this request is being made. Matches requesting_practitioner.id
|
| aud | required | EHR B authorization server's "token URL" (the URL to which this authentication JWT will be posted) |
| exp | required | Expiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time MUST be no more than five minutes in the future |
| jti | required | A nonce string value that uniquely identifies this authentication JWT |
{
"iss": "https://ehr-a.com",
"sub": "128641521",
"aud": "https://ehr-b.com/authorize",
"acr": "http://nist.gov/id-proofing/level/3",
"jit": "some-nonce-abc",
"exp": 1422568860,
"requested_record": {
"resourceType": "Patient",
"name": {
"text": "Pauline Smith",
},
"address": {
"postalCode": "94118"
}
"gender": "female",
"birthDate": "1970-05-18"
},
"reason_for_request": "treatment",
"requested_scopes": "patient/*.read",
"requesting_practitioner": {
"resourceType": "Practitioner",
"id": "128641521",
"identifier": [{
"system": "https://ehr-a.com",
"value": "123"
},{
"system": "https://nppes.cms.hhs.gov/",
"value": "1770589525"
}],
"name": {
"text": "Juri van Gelder"
},
"practitionerRole": [{
"role": {
"coding": [{
"system": "http://snomed.info/sct",
"code": "36682004",
"display": "Physical therapist"
}]}}]}}
The following claims are required. Note the similarity to claims in the Authorization JWT, except that sub here represents EHR A's client_id -- not the user on whose behalf the request is being made.
| claim | required? | description |
|---|---|---|
| iss | required | Requesting EHR's issuer URI |
| sub | required | The OAuth client_id by which EHR B knows EHR A. This is likely the same as iss
|
| aud | required | EHR B authorization server's "token URL" (the same URL to which this authentication JWT will be posted) |
| exp | required | Expiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time MUST be no more than five minutes in the future |
| jti | required | A nonce string value that uniquely identifies this authentication JWT |