Skip to content

cross organizational auth

Jump to bottom Edit New page
bakerdb edited this page Oct 2, 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 JSON Web Token (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 and Privacy 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 JWT assertions passed between the two organizations could contain protected health information or other privacy-sensitive information. Preventing unauthorized disclosure of such information requires security protection during transmission and storage, and a conscious effort to minimize the amount of information exchanged. Both organizations (end-users and technology) involved in the exchange should assure that the minimum amount of information necessary is requested and authorized.

The use of Transport Layer Security (TLS) to secure links between the two organizations protects against unauthorized disclosure of sensitive information in transit, and digital signatures protect against forgery of JWTs. Each organization will need to implement protections against denial-of-service attacks against exposed interfaces.

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. Also, authorization servers and resource servers may use a combination of the JWT assertion ID (jti) and issuance and expiration time attributes (iat and exp) to protect against replay attacks.

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 the EHR-B authorization server will need to know in order to provide access to a FHIR resource. The HTTP parameters for transporting the authorization JWT from the EHR-A authorization server to the EHR-B authorization server's token endpoint are defined in The OAuth Assertion Framework RFC7521, with the following specific parameter values and encodings (as shown in the sequence diagram above):

  • The value of the "grant_type" is "urn:ietf:params:oauth:grant-type:jwt-bearer."
  • The value of the "assertion" parameter MUST contain a single signed authorization JWT.

The authorization JWT MUST be digitally signed by the EHR-A authorization server as specified in RFC7515, JSON Web Signature, 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.

Upon receipt, the EHR-B authorization server MUST validate the digital signature and 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 JWT 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 authentication JWT contains the details the EHR-B authorization server will need to know in order to authenticate the identity of the EHR-A authorization server. The HTTP parameters for transporting the authentication JWT from the EHR-A authorization server to the EHR-B authorization server's token endpoint are defined in The OAuth Assertion Framework RFC7521, with the following specific parameter values and encodings (as shown in the sequence diagram above):

  • The value of the client_assertion_type is urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • The value of the client-assertion parameter MUST contain a single signed authentication JWT

The authorization JWT MUST be digitally signed by the EHR-A authorization server as specified in RFC7515, JSON Web Signature, 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.

Upon receipt, the EHR-B authorization server MUST validate the digital signature and 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 EHR-B authorization server MAY use a combination of the JWT ID (jti) and the issuance and expiration parameters (iat and exp respectively) to detect an attempts to replay authorization JWTs. The EHR-B authorization server SHOULD reject authorization requests that have been previously processed and those received outside the time window within which they remain valid.

The authentication JWT contains the following claims. 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; i.e., the EHR-A authorization server's URL
sub REQUIRED The OAuth client_id by which EHR-B knows the EHR-A authorization server
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. 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.
kid REQUIRED Key_id of the keypair used to digitally sign this token
iat OPTIONAL The UTC time the JWT was created by EHR-A.

Access Token

The EHR-B authorization server MUST return either an access token or a message indicating that the authorization request has been denied.

The access token MUST be a JWT bearer token containing the following claims:

Claim Priority Description
iss REQUIRED The issuer URL of the server that issued the token; i.e., the EHR-B authorization server's URL
azp REQUIRED The client_id of the client to whom this token was issued; i.e., the EHR-A authorization server
sub REQUIRED EHR-A's id for the user on whose behalf this request was made. Matches requesting_practitioner.id
kid REQUIRED The key_ID of the keypair used to sign this token
exp REQUIRED The expiration time (integer number of seconds since from 1970-01-01T00:00:00Z UTC), after which the token MUST be considered invalid.
jti REQUIRED A unique JWT Token ID value with at least 128 bits of entropy. This value MUST NOT be re-used in another token. Clients MUST check for reuse of jti values and reject all tokens issued with duplicate jti values.
aud OPTIONAL An array of identifier(s) of FHIR resources for which the token is valid; may contain multiple values. Included at the discretion of the EHR-B authorization server

The following sample claim set illustrates the use of the required claims for an access token as defined in this profile; additional claims MAY be included in the claim set:

{
   "exp": 1418702388,
   "azp": "55f9f559-2496-49d4-b6c3-351a586b7484",
   "sub": "128641521",
   "iss": "https:\\/\\/authzserver.EHR-B.org\\/",
   "jti": "2402f87c-b6ce-45c4-95b0-7a3f2904997f",
   "iat": 1418698788,
   “kid”: “rsa1”
}

The access token MUST be digitally signed by the EHR-B authorization server as specified in RFC7515, JSON Web Signature. The EHR-A 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.

Upon receipt, the EHR-A authorization server MUST validate the digital signature and MUST reject access tokens 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.

Refresh tokens are not supported in this profile.

The EHR-B authorization server MAY encrypt the access token using the EHR-A authorization server's public key.

FHIR Resource Retrieval

The EHR-B FHIR resource server MUST support bearer tokens passed in the Authentication header as defined by RFC6750. The EHR-B FHIR server MAY support the form-parameter or query-parameter methods defined in RFC6750.

The access token MUST be presented to the EHR-B FHIR server by either the EHR-A authorization server (azp parameter in access token) or by the end-user on whose behalf the access was authorized (sub parameter). How the token might be passed to the requesting end-user within EHR-A is beyond the scope of this specification.

Authorized requests MUST be made over TLS, and EHR-A MUST authenticate the EHR-B FHIR server as part of the TLS set-up. The EHR-B FHIR server MAY authenticate the EHR-A TLS-endpoint as well.

An EHR-A presenting entity MUST present the access token to the EHR-B FHIR server by issuing a FHIR API call to the FHIR endpoint on EHR-B's resource server. The request MUST include an Authorization header that MUST identify the access_token as a "Bearer" token:

    Authorization: Bearer [access_token]

(Note that in a real request, access_token is replaced with the actual token value.)

For example:

GET https://ehr/fhir/Patient/123
Authorization: Bearer i8hweunweunweofiwweoijewiwe

{
  "resourceType": "Patient",
  "birthTime": ...
}

EHR-B's FHIR resource 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.

Upon receipt of the access token, the EHR-B resource server MUST validate the digital signature and ensure that the token has not expired. The EHR-B resource server MUST reject expired access tokens, and access tokens 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 EHR-B resource server MUST validate that the iss parameter (token issuer) matches the URL of an EHR-B authorization server, and that the presenter of the token matches either the azp parameter (client_id of EHR-A authorization server to whom the token was issued) or the sub parameter (requesting_practitioner.id). The EHR-B resource server MAY use a combination of the JWT ID (jti) and the issuance and expiration parameters (iat and exp respectively) to detect an attempts to replay an access token. The EHR-B resource server SHOULD reject access tokens that have been previously processed and those received outside the time window within which they remain valid.

If the EHR-B resource server rejects a token for any reason, it MUST return a message to the EHR-A authorization server indicating the reason for rejection. The message MUST NOT disclose any protected health information.

The EHR-B resource server MUST assure that the specified scope covers the requested FHIR resource(s), and MUST NOT return any resources beyond those authorized in the access token.

Add a custom footer
Add a custom sidebar
Clone this wiki locally