CH EPR FHIR (R4), published by eHealth Suisse. This guide is not an authorized publication; it is the continuous build for version 5.0.0-ballot-ci-build built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/ehealthsuisse/ch-epr-fhir/ and changes regularly. See the Directory of published versions

Get Access Token [ITI-71]

This section describes the national extension for the Swiss EPR to the Get Access Token [ITI-71] transaction defined in the IUA profile published in the IHE IT Infrastructure Technical Framework Trial Implementation “Internet User Authorization”. In this transaction, the OAuth Authorization Code grant type option is enforced for security reasons.

Scope

The transaction is used by an IUA Authorization Client (e.g., portals and primary systems) to pass claims to the IUA Authorization Server and to retrieve an access token to be used for authorization of the access to protected resources of the Swiss EPR.

Depending on the claims made by the IUA Authorization Client, two different flavors of access tokens SHALL be provided by the IUA Authorization Server:

• Basic Access Token – IUA compliant access token authorizing access to the EPR end-points which are NOT protected by the EPR role and attribute based authorization (i.e. for the PIXm endpoints).
• Extended Access Token – IUA compliant access token for the EPR endpoints which are protected by the EPR role and attribute based authorization (i.e. for the MHD endpoints).

When an IUA Authorization Client is authorized, it may launch SMART on FHIR Apps using the EHR launch by claiming a launch indicator. When launched the SMART on FHIR Apps inherit the basic access authorization from the launching app and may retrieve Extended Access Token for EPR endpoints protected by the EPR role and attribute based authorization (e.g. to retrieve documents).

Actor Roles

Actor: IUA Authorization Client
Role: Communicates claims and launch information to the IUA Authorization Server and receives JWT access token.
Actor: IUA Authorization Server
Role: Identifies the Authorization Client, authorizes the access on behalf of the user, verifies claims, optionally authenticates the user and responds a JWT Access Token to the IUA Authorization Client to be incorporated into the transactions to access protected resources.

Referenced Standards

1. IHE ITI Technical Framework Supplement Internet User Authorization (IUA) Revision 2.2
2. SMART Application Launch Framework Implementation Guide Release 2.1.0

Messages

Client Credential Grant Type

This section specifies the OAuth 2.1 client credential grant flow of the IUA Get Access Token transaction, which shall be used by clinical archive systems to retrieve an Access Token.

Authorization Code Grant Type

This section specifies the OAuth 2.1 authorization code grant flow of the IUA Get Access Token transaction, which shall be used by portals and primary systems.

²For SMART on FHIR Apps launched in EHR mode the client_id SHALL be the ID of the portal or primary system which launched the App.

Get Access Token Request

Client Credential Grant Type

Trigger Events

A clinical archive system aims to access the EPR to write documents.

Message Semantics

The Authorization Client SHALL send an IUA compliant Authorization Request for the client credential flow. The Authorization Request SHALL set the scope parameter with one or many scope values as defined in the table below.

³Token format according FHIR token type.

Expected Actions

When receiving a Get Access Token Request with purpose of use set to AUTO and subject role set to TCU, the Authorization Server SHALL identify and authenticate the Authorization Client with the client_id, client_secret and the client's certificate of the TLS connection.

The Authorization Server SHALL verify that the Authorization Client was registered during onboading with the same client_id, client_secret and the client's certificate of the TLS connection and is authorized to access the EHR.

The Authorization Server SHALL verify that the principal_id matches the GLN of the legal responsible healthcare professional the Authorization Client was registered during onboading.

The Authorization Server SHALL respond with the Get Access Token response as defined in Get Access Token Response only if all checks are successful. If one of the above checks fails, the Authorization Server SHALL respond with HTTP 401 (Unauthorized) error.

The Authorization Server SHALL respond with a Extended Access Token, only if the person_id is set in the request. The Authorization Server SHALL respond with a Basic Access Token, if the person_id is not set.

The Authorization Client SHALL use the access token as defined in IUA Incorporate Access Token transaction, when performing requests to resources of the Swiss EPR.

Message Example

POST /token HTTP/1.1 
Host: localhost:9001

Accept: application/json
Content-type: application/x-www-form-urlencoded
Authorization: Basic bXktYXBwOm15LWFwcC1zZWNyZXQtMTIz
grant_type=client_credentials&
access_token_format=urn:ietf:params:oauth:token-type:jwt&
scope=user%2F*.*+openid+fhirUser+purpose_of_use%3Durn%3Aoid%3A2.16.756.5.30.1.127.3.10.5%7CAUTO+subject_role%3Durn%3Aoid%3A2.16.756.5.30.1.127.3.10.6%7CTCU+person_id%3D761337610411353650%5E%5E%5E%262.16.756.5.30.1.109.6.5.3.1.1%26ISO

Authorization Code Grant Type

Trigger Events

A user launches a portal or primary system, or a SMART on FHIR App to access data and documents from the Swiss EPR.

Message Semantics

The Authorization Client SHALL send an IUA compliant Authorization Request for the authorization code flow. The Authorization Request SHALL set the scope parameter with one or many scope values as defined in the table below.

³Token format according FHIR token type.

The scope parameter of the request MAY claim the following attributes:

• There MAY be a scope with name “launch”. If present, it indicates the permission of SMART on FHIR Apps to obtain launch context from a portal or primary system authorized to access the EPR.
• There MAY be a scope with name "purpose_of_use=token". If present, the token SHALL convey the coded value of the current transaction’s purpose of use. Allowed values are NORM (normal access) and EMER (emergency access) from code system 2.16.756.5.30.1.127.3.10.5 of the CH:EPR value set. e.g. purpose_of_use=urn:oid:2.16.756.5.30.1.127.3.10.5|NORM
• There MAY be a scope with name "subject_role=token". If present, the token SHALL convey the coded value of the subject’s role. The value SHALL be either HCP (healthcare professional), ASS (assistant), REP (representative) or PAT (patient) from code system 2.16.756.5.30.1.127.3.10.6 of the CH:EPR value set. e.g.: subject_role=urn:oid:2.16.756.5.30.1.127.3.10.6|HCP
• There MAY be a scope with name "person_id=value". If present, the value SHALL convey the EPR-SPID identifier of the patient’s record and the patient assigning authority formatted in CX syntax. e.g: person_id=761337610411353650^^^&2.16.756.5.30.1.109.6.5.3.1.1&ISO

Note: The parameters need to be url encoded, see above message example.

Depending on the value of the role scope additional scopes are required, as described in the following sections.

Healthcare Professional Extension

In the healthcare professional extension, the scope subject_role SHALL be the code HCP from code system 2.16.756.5.30.1.127.3.10.6 of the CH:EPR value set.

Assistant Extension

In the assistant extension, the scope subject_role SHALL be the code ASS from code system 2.16.756.5.30.1.127.3.10.6 of the CH:EPR value set. There SHALL be a scope with name principal_id=value. The value SHALL convey the GLN of the healthcare professional an assistant is acting on behalf of. There SHALL be a scope with name principal=value. The value SHALL convey the name of the healthcare professional an assistant is acting on behalf of.

There MAY be one or more scopes with name group_id=value and corresponding group=value. If present each value SHALL convey the ID and name of the subject’s organization or group as registered in the EPR HPD. The ID SHALL be an OID in the format of a URN.

Patient Extension

In the patient extension, the scope subject_role SHALL be the code PAT from code system 2.16.756.5.30.1.127.3.10.6 of the CH:EPR value set. The value of the purpose of use scope SHALL be the code NORM from code system 2.16.756.5.30.1.127.3.10.5 of the CH:EPR value set.

Representative Extension

In the representative extension, the scope subject_role SHALL be the code REP from code system 2.16.756.5.30.1.127.3.10.6 of the CH:EPR value set. The token of the purpose_of_use scope SHALL be the code NORM from code system 2.16.756.5.30.1.127.3.10.5 of the CH:EPR value set.

Expected Actions

The IUA Authorization Client SHALL support the HTTP conversation of the OAuth 2.1 Authorization Code grant.

When launched, the IUA Authorization Client SHALL perform HTTP GET request with the URL query parameter as defined in Table and with the scope claims described in Table.

When receiving the request the Authorization Server, the Authorization Server SHALL verify that the Authorization Client was registered during onboading with the same client_id and the client certificate of the TLS connection.

The Authorization Server SHALL authorize the Authorization Client to access the EHR by either verifying that the Authorization Client request is authorized by a policy or by presenting a form to the user to consent to the access by the Authorization Client on behalf of the user. The Authorization Server MAY cache the users decision for for future access by the same Authorization Client.

The Authorization Server SHALL enforce that the user is authenticated compliant to the regulations of the Swiss EHR and has a valid browser session with an certified Identity Provider. If the user is not authenticated the Authorization Server SHALL respond with an error page or redirect the user to a Identity Provider.

If the IUA Authorization Client receives the request from the IUA Authorization Server on the redirect-uri conveying the authorization code, the Authorization Client SHALL perform the HTTP POST request with the client_id and client_secret in the HTTP authorization header field to resolve the authorization code to the access token.

The Authorization Server SHALL respond with the Get Access Token response as defined in Get Access Token Response only if all checks are successful. If one of the above checks fails, the Authorization Server SHALL respond with HTTP 401 (Unauthorized) error.

The IUA Authorization Client SHALL use the access token as defined in IUA Incorporate Access Token transaction, when performing requests to resources of the Swiss EPR.

Message Example

The first step of the conversation is an HTTP GET which may look like for a Basic Access Token:

GET authorize?
    response_type=code&
    client_id=app-client-id&
    redirect_uri=http%3A%2F%2Flocalhost%3A9000%2Fcallback&
    launch=xyz123&
    scope=launch+user%2F%2A.%2A+openid+fhirUser&
    state=98wrghuwuogerg97&
    aud=https%3A%2F%2Fehr%2Ffhir&
    code_challenge=ZmVjMmIwMWYyYTNjZWJiNTgyNTgxYzlmOGYyMWM0MWI3YmZhMjQ4YjU5MDc3Mzk4MDBmYTk0OThlNzZiNjAwMw&
    code_challenge_method=S256

An extended access token where at least purpose_of_use (NORM), subject_role (HCP) and person_id are added to the scope may look like:

GET authorize?
    response_type=code&
    client_id=app-client-id&
    redirect_uri=http%3A%2F%2Flocalhost%3A9000%2Fcallback&
    launch=xyz123&
    scope=launch+user%2F*.*+openid+fhirUser+purpose_of_use%3Durn%3Aoid%3A2.16.756.5.30.1.127.3.10.5%7CNORM+subject_role%3Durn%3Aoid%3A2.16.756.5.30.1.127.3.10.6%7CHCP+person_id%3D761337610411353650%5E%5E%5E%262.16.756.5.30.1.109.6.5.3.1.1%26ISO&
    code_challenge=ZmVjMmIwMWYyYTNjZWJiNTgyNTgxYzlmOGYyMWM0MWI3YmZhMjQ4YjU5MDc3Mzk4MDBmYTk0OThlNzZiNjAwMw&
    code_challenge_method=S256

The second step of the conversation is an HTTP GET Callback conveying the authorization code and may look like:

GET /callback?code=8V1pr0rJ&state=98wrghuwuogerg97

The third step of the conversation is an HTTP POST sending the authorization code to retrieve the authorization token in the response which may look like:

POST /token HTTP/1.1 
Host: localhost:9001

Accept: application/json
Content-type: application/x-www-form-urlencoded
Authorization: Basic bXktYXBwOm15LWFwcC1zZWNyZXQtMTIz
grant_type=authorization_code&
code=98wrghuwuogerg97&
code_verifier=qskt4342of74bkncmicdpv2qd143iqd822j41q2gupc5n3o6f1clxhpd2x11&
access_token_format=urn:ietf:params:oauth:token-type:jwt

Get Access Token Response

Message Semantics

The response SHALL either convey a Basic Access Token in JWT format, granting basic access to the EPR (i.e. to access patient data), or an Extended Access Token to access resources protected by the role and attribute based EPR authorization (i.e. read and write documents).

JSON Web Token Option

The Authorization Server and Resource Server SHALL support the IUA JWT extension with the following claims as defined in Table below.

The claim content for the JWT IUA extensions SHALL correspond to the content defined in the XUA specification (see 1.6.4.2 Get X-User Assertion, A5E1).

The JWT ch_epr extension

The Authorization Server and Resource Server SHALL support the following extensions to the JWT access token for an EPR user:

• user_id: subject identifier according to Annex 5 E1, section 1.6.4.3.4.2 Message Semantics.

The JWT ch_group extension

The Authorization Server and Resource Server SHALL support the following extensions to the JWT access token for a list of groups a subject is member of:

• name: Name of the organization/group. The name SHALL be a string.
• id: The id of the organization/group.The id SHALL be an OID in the format of a URN

The ch_group extension claims shall be wrapped in an "extensions" object with key 'ch_group’ and a JSON array containing the JSON objects with properties name and id. The id SHALL be an OID in the format of a URN.

The JWT ch_delegation extension

The Authorization Server and Resource Server shall support the following extensions to the JWT access token:

• principal (optional) Name of the healthcare professional an assistant is acting on behalf of.
• principal_id (optional) GLN of the healthcare professional an assistant is acting on behalf of.

The ch_delegation extension claims shall be wrapped in an "extensions" object with key 'ch_delegation' and a JSON value object containing the claims. The claim content for the JWT CH:EPR extensions shall correspond to the content defined in the XUA specification (see 1.6.4.2 Get X-User Assertion, A5E1).

Expected Actions

The IUA Authorization Server SHALL support the HTTP conversation of the OAuth 2.1 Authorization Code grant as follows:

If the IUA Authorization Server receives a request, it SHALL authenticate the user by redirecting the request to a Identity Provider using the Open ID Connect protocol. The Identity Provider authenticates the user based on its internal session management (i.e. by checking the requests cookies or other methods) or by validating the user authentication means and returns the identity token to the IUA Authorization Server.

In case of authentication failure, the IUA Authorization Server SHALL respond with HTTP error code 401 ‘Not authorized’.

The IUA Authorization Server SHALL identify the IUA Authorization Client (portal or primary system) based on the digital signature of the messages send by the IUA Authorization Client. The IUA Authorization Server SHALL use the X.509 certificate provided by the portal or primary system in the TLS connection to authenticate the IUA Authorization Client.

The IUA Authorization Server SHALL verify that the IUA Authorization Client (portal or primary system) is authorized to access the EPR on behalf of the users by checking if the IUA Authorization Client has been registered and authorized by the community during the onboarding process.

For SMART on FHIR Apps launched in an EHR Launch, the IUA Authorization Server SHALL validate the launch scope parameter, by verifying that the portal or primary system which launched the SMART on FHIR App has been registered with this launch parameter value by the community during the onboarding process.

In case of failure, the IUA Authorization Server SHALL respond with HTTP error code 401 ‘Not authorized’.

The IUA Authorization Server SHALL validate the scope claim. Depending on the scope claimed, the IUA Authorization Server SHALL either build a Basic Access Token authorizing basic access to the EPR (i.e. to access patient data), or an Extended Access Token to authorize access to resources protected by the role and attribute based EPR authorization (i.e. read and write documents).

The business rules for the IUA Authorization Server for the Healthcare Professional, Assistant, Patient and Representative Extension SHALL be the same as for Annex 5E1 1.6.4.2.4.4 Expected Actions X-Assertion Provider Extensions.

If successful the IUA Authorization Server SHALL generate an OAuth 2.1 authorization code and perform a callback to the URL defined in the request, using the OAuth authorization code as URL query parameter with key ‘code’.

The IUA Authorization Server SHALL store the access token and the assigned authorization code and respond the access token on request to the Authorization Client.

⁴This covers all possible EPR transaction, except the ITI-103 transaction.

Message Example

A basic JWT access token returned by the IUA Authorization Server and to be used to retrieve patient data may look like:

{
  "iss": "http://issuerAdress.ch",
  "sub": "UserId-bfe8a208-b9d0-4012-b2f5-168b949fc3cb",
  "aud": "http://pixmResourceServerURL.ch",
  "exp": 1587294580000,
  "nbf": 1587294460000,
  "iat": 1587294460000,
  "jti": "c5436729-3f26-4dbf-abd3-2790dc7771a",
  "extensions" : {  
    "ihe_iua" : {  
      "subject_name": "Martina Musterarzt", 
      "home_community_id": "urn:oid:1.2.3.4" 
    }, 
    "ch_epr": {
      "user_id": "2000000090092", 
      "user_id_qualifier": "urn:gs1:gln" 
    }
}

An extended JWT access token to be used to access patient documents SHALL have the additional attributes of the purpose of use, subject role, the EPR-SPID of the patient and may look like:

{
  "iss": "http://issuerAdress.ch",
  "sub": "UserId-bfe8a208-b9d0-4012-b2f5-168b949fc3cb",
  "aud": "http://mhdResourceServerURL.ch",
  "exp": 1587294580000,
  "nbf": 1587294460000,
  "iat": 1587294460000,
  "jti": "c5436729-3f26-4dbf-abd3-2790dc7771a",
  "extensions" : {  
    "ihe_iua" : {  
      "subject_name": "Martina Musterarzt",
      "home_community_id": "urn:oid:1.2.3.4",  
      "person_id": "761337610411353650^^^&2.16.756.5.30.1.127.3.10.3&ISO",
      "subject_role": {
          "system": "urn:oid:2.16.756.5.30.1.127.3.10.6",
          "code": "HCP"
      },
      "purpose_of_use": {
          "system": "urn:uuid:2.16.756.5.30.1.127.3.10.5",
          "code": "NORM",
      }
    }, 
    "ch_epr": {
      "user_id": "2000000090092", 
      "user_id_qualifier": "urn:gs1:gln" 
    },
    "ch_group" : [
      {
        "name": "Name of group with id urn:oid:2.2.2.1",
        "id": "urn:oid:2.2.2.1"
      }, 
      {
        "name": "Name of group with id urn:oid:2.2.2.2",
        "id": "urn:oid:2.2.2.2"
      },
      {
        "name": "Name of group with id urn:oid:2.2.2.2",
        "id": "urn:oid:2.2.2.3"
      }
    ]
  }
}

An extended JWT access token to be used to access by an assistant acting behalf on a healthcare professional for a patient SHALL have the additional extension ch_delegation:

{
  "iss": "http://issuerAdress.ch",
  "sub": "UserId-bfe8a208-b9d0-4012-b2f5-168b949fc3cb",
  "aud": "http://mhdResourceServerURL.ch",
  "exp": 1587294580000,
  "nbf": 1587294460000,
  "iat": 1587294460000,
  "jti": "c5436729-3f26-4dbf-abd3-2790dc7771a",
  "extensions" : {  
    "ihe_iua" : {  
      "subject_name": "Dagmar Musterassistent",
      "home_community_id": "urn:oid:1.2.3.4", 
      "person_id": "761337610411353650^^^&2.16.756.5.30.1.127.3.10.3&ISO",
      "subject_role": {
          "system": "urn:oid:2.16.756.5.30.1.127.3.10.6",
          "code": "HCP"
      },
      "purpose_of_use": {
          "system": "urn:uuid:2.16.756.5.30.1.127.3.10.5",
          "code": "NORM",
      }
    }, 
    "ch_epr": {
      "user_id": "2000000090108", 
      "user_id_qualifier": "urn:gs1:gln" 
    }, 
    "ch_group" : [
      {
        "name": "Name of group with id urn:oid:2.2.2.1",
        "id": "urn:oid:2.2.2.1"
      }, 
      {
        "name": "Name of group with id urn:oid:2.2.2.2",
        "id": "urn:oid:2.2.2.2"
      },
      {
        "name": "Name of group with id urn:oid:2.2.2.2",
        "id": "urn:oid:2.2.2.3"
      }
    ],
    "ch_delegation": {
      "principal": "Martina Musterarzt", 
      "principal_id": "2000000090092" 
    }
  }
}

CapabilityStatement Resource

There are no CapabilityStatement resources defined for this transaction.

Security Consideration

IUA Authorization Clients, Authorization Servers and Resource Server actors SHALL use the JWS (signed) alternative of the JWT token as specified in the IUA Trial Implementation. The JWE alternative SHALL not be used.

The actors SHALL support the traceparent header handling, as defined in Appendix: Trace Context.

Security Audit Considerations

There is no audit event required for this transaction.