Skip to content

cross organizational auth

Jump to bottom Edit New page
bakerdb edited this page Oct 1, 2015 · 67 revisions

Cross-Organization Data Access Profile

Status

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.

Summary

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 OAuth 2.0 Authorization Framework, RFC 6749, defines several methods of requesting authorization to access protected resources, all resulting in the issuance of an access token, which is then presented to retrieve the authorized resource. Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants, RFC7521, is an abstract extension to OAuth 2.0 that provides a general framework for the use of assertions (i.e., security tokens) as client credentials and/or authorization grants. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants, RFC7523) profiles the OAuth Assertion Framework (RFC7521) to define an extension grant type that uses a JWT Bearer Token to request an OAuth 2.0 access token as well as for use as client credentials.

This Cross-Organization Data Access Profile implements OAuth 2.0 as described in these specifications to enable a requesting organization to obtain an access code using JSON Web Tokens to:

  1. Authenticate the requesting EHR (EHR-A)
  2. Request an OAuth 2.0 access token from the EHR holding the desired FHIR resource (EHR-B)

As described in RFC7523, an authorization JWT Bearer Token is used to request an access token "when a client wishes to utilize an existing trust relationship, expressed through the semantics of the JWT, without a direct user-approval step at the authorization server." In the Argonaut use case, 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:

  1. When the EHR-A authorization server decides whether to grant an end user’s request for a cross-entity query of FHIR resources held by the EHR-B, and

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

Limitations

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:

  1. EHR-A calls EHR-B's "match" to obtain a match iD (opaque string representing the match).

  2. EHR-A passes the match string as a claim in the authorization JWT (rather than including a Patient resource directly.

Security Considerations

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.

Specification

Underlying Standards

Terminology

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.

Actors and Transactions

seq diagram

edit

Sequence Diagram

seq diagram

edit

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

Details

Requester Registration

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.

Servers

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

Authorization JWT

The authorization JWT contains the details a remote EHR's authorization server will need to know in order to provide access to a FHIR resource. The HTTP parameters for transporting the JWTs from the EHR-A authorization server to the EHR-B authorization server's token endpoint are defined in The OAuth Assertion Framework [RFC7521].

The authorization JWT MUST be digitally signed by the EHR-A authorization server using the private key counterpart to the public key registered with EHR-B. The EHR-B authorization server MUST support the RS256 signature method and MAY use other asymmetric signature methods listed in JSON Web Algorithms (JWA): draft-ietf-jose-json-web-algorithms-14.

The EHR-B authorization server MUST reject authorization JWTs with an invalid digital signature. The algorithm used to validate the signature, and the mechanism for designating the secret used to generate the signature, are outside the scope of this specification.

The authorization JWT MUST contain:

  • 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? ...)

The authorization JWT also contains claims necessary to help ensure the security of the exchange (expiration time, issuer, subject, a token identifier; see RFC7523 for details):

Claim Priority 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 authorization JWT will be posted)
exp REQUIRED Expiration time integer after which this authorization JWT MUST be considered invalid; expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). This time MUST be no more than five minutes in the future.
kid REQUIRED Key id of the encryption key used to digitally sign this token
jti REQUIRED A nonce string value that uniquely identifies this authorization JWT. MUST have at least 128 bits of entropy and MUST NOT be reused in another token. EHR-B MUST check for reuse of jti values and MUST reject all tokens issued with duplicate jti values.
iat OPTIONAL The UTC time the token was created by EHR-A.
Example
{
  "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",
  "iat": 1418698788,
  "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"
        }]}}]}}

Authentication JWT

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 Priority 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
Add a custom footer
Add a custom sidebar
Clone this wiki locally