CH EPR FHIR (R4)
5.0.0-ballot-ci-build - ci-build
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
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”.
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:
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: IUA Authorization Client
Role: Communicates claims and launch information to the IUA Authorization Server and receives JWT access token,
optionally authenticates the user and presents the IDP token to the IUA Authorization Server together with the claims
and launch information.
Actor: IUA Authorization Server
Role: Identifies the Authorization Client, authorizes the access on behalf of the user, verifies claims, optionally
enforces user authentication by redirecting the Authorization Client to a certified IdP and responds a JWT Access Token
to the IUA Authorization Client to be incorporated into the transactions to access protected resources.
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.
Step | Action | Parameter | Opt (Basic/ Extended). | Reference | Remark |
---|---|---|---|---|---|
00 | The Authorization Client sends an HTTP POST request to the IUA Authorization Server endpoint. | grant_type | R | IUA | The value SHALL be client_credentials. |
client_id | R | IUA | The ID, the Authorization Client is registered at the IUA Authorization Server. | ||
client_secret | R | IUA | An unguessable value registered for the Authorization Client during onboarding. | ||
scope | R | IUA | Attributes the Authorization Client claims (see detailed description below). | ||
aud | R | SMART on FHIR | The URL or array of URL of the Resource Servers the token is intended to be used for. | ||
01 | The Authorization Server responds with the access token in the HTML body element. | access_token | R | IUA | A string containing the access token which SHALL be a JWT token. |
token_type | R | IUA | The value of the parameter shall be Bearer. | ||
scope | R | IUA | The scope granted by the Authorization Server. | ||
expires_in | R | IUA | Maximum duration of 5 minutes. |
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.
Step | Action | Parameter | Opt (Basic/ Extended). | Reference | Remark |
---|---|---|---|---|---|
00, 01 | The Authorization Client sends an HTTP GET request to the IUA Authorization Server endpoint. | response_type | R | IUA | The value SHALL be code. |
client_id | R | IUA | The ID, the Authorization Client is registered at the IUA Authorization Server1. | ||
redirect_uri | R | IUA / SMART on FHIR | Used as the callback URL the IUA Authorization Server will send the authorization code to. The URL SHALL match one of the client’s pre-registered redirect URIs. | ||
state | R | IUA | An unguessable value used by the Authorization Client to track the state between the authorization request and the callback to the redirect_uri. | ||
scope | R | IUA / SMART on FHIR | Attributes the Authorization Client claims (see detailed description below). | ||
aud | R | SMART on FHIR | The URL or array of URL of the Resource Servers the token is intended to be used for. | ||
launch | R | SMART on FHIR | An opaque identifier which indicates that a SMART on FHIR App was launched from a portal or primary system which is authorized to access the Swiss EPR as EHR launch. | ||
code_challenge | R | IUA | Transformed version of code_verifier with code_challenge_method. | ||
code_challenge_method | R | IUA | SHALL be “S256”. | ||
02, 03 | The Authorization Server performs an HTTP GET on the Authorization Client redirect_uri conveying the authorization code. | code | R | IUA | The authorization code generated by the Authorization Server. |
state | R | IUA | The unguessable value used by the Authorization Client to track the state between the authorization request and the callback (redirect_uri). | ||
04 | The Authorization Client performs an HTTP POST with parameter as a form-encoded HTTP entity body, passing its client_id and client_secret as an HTTP authorization header field. | client_id | R | IUA | The ID the Authorization Client is registered at the IUA Authorization Server1. |
grant_type | R | IUA | Value shall be “authorization_code”. | ||
code | R | IUA | The authorization | ||
code_verifier | R | IUA | The original code verifier string. | ||
client_assertion_type | O | Swiss extension | An identifier of the client assertion type, either "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" if a signed JWT is presented, or "urn:ietf:params:oauth:client-assertion-type:saml2-bearer" for base64url encoded SAML 2 assertions 2. | ||
assertion | O | Swiss extension | The identity token the Authorization client retrieved from the certified Identity Provider after successful authentication of the user, either a signed JWT, or a base64url encoded SAML 2 assertion 2. | ||
05 | The Authorization Server responds with the access token in the HTML body element. | access_token | R | IUA | The access token which SHALL be a signed JWT token. |
token_type | R | IUA | The value of the parameter shall be Bearer. | ||
scope | R | IUA | The scope granted by the Authorization Server. | ||
expires_in | R | IUA | Maximum duration of 5 minutes. |
1For SMART on FHIR Apps launched in EPR mode the client_id SHALL be the ID of the portal or primary system which launched the App.
2The presentation of the IdP token is recommended for IUA Authorization Clients which do not use SMART on FHIR EHR launch.
A clinical archive system aims to access the EPR to write documents.
The Authorization Client SHALL send an IUA compliant OAuth 2.1 Authorization Request for the client credential grant type with Swiss extensions:
client_credentials
.urn:ietf:params:oauth:token-type:jwt
.The Authorization Request SHALL use the following Swiss extension:
Authorization Clients SHALL sent the scope values in the Authorization Request:
Scope | Optionality (Basic/ Extended) | Type | Reference | Remark |
---|---|---|---|---|
purpose_of_use | R/R | token3 | See sections below. | Shall be AUTO as defined in the code system 2.16.756.5.30.1.127.3.10.5 of the CH:EPR value set. |
subject_role | R/R | token | See sections below. | Shall be the value TCU as defined in the code system 2.16.756.5.30.1.127.3.10.1.1.3 of the CH:EPR value set. |
3Token format according FHIR token type.
When receiving a Get Access Token Request with purpose of use set to AUTO and subject role set to TCU, the Authorization Server SHALL:
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 an 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.
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&
requested-token-type=urn:ietf:params:oauth:token-type:jwt&
person_id=761337610411353650%5E%5E%5E%262.16.756.5.30.1.109.6.5.3.1.1%26ISO&
principal_id=9801000050702&
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%7CTC
A user launches a portal, primary system or a SMART on FHIR App to access data and documents from the Swiss EPR.
The Authorization Client SHALL send an IUA compliant OAuth 2.1 Authorization Request for the client credential grant type with Swiss extensions:
The Authorization Request SHALL use the following Swiss extension:
Authorization Clients SHALL sent the scope values in the Authorization Request:
Scope | Optionality (Basic/ Extended) | Type | Reference | Remark |
---|---|---|---|---|
launch | O/R | SMART on FHIR | An opaque identifier of a SMART on FHIR App launched in an EHR launch. The claim is required for SMART on FHIR Apps launched from a portal or primary system. | |
purpose_of_use | O/R | token | See sections below. | Value taken from code system 2.16.756.5.30.1.127.3.10.5 of the CH: EPR value set in [FHIR token type](https://www.hl7.org/fhir/search.html#token) format. |
subject_role | O/R | token | See sections below. | Value taken from code system 2.16.756.5.30.1.127.3.10.1.1.3 of the CH: EPR value set in [FHIR token type](https://www.hl7.org/fhir/search.html#token) format. |
The scope parameter of the request MAY claim the following attributes:
Note: The parameters need to be url encoded, see above message example.
Depending on the value of the subject-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.
The IUA Authorization Client and Authorization Server SHALL support the HTTP conversation of the OAuth 2.1 Authorization Code grant type.
When launched, the IUA Authorization Client SHALL send an HTTP GET request to the Authorization Servers authorization endpoint with query parameter as defined in Table and with the scope claims described in Table.
When receiving the request the Authorization Server
In case of failure, the IUA Authorization Server SHALL respond with HTTP error code 401 ‘Not authorized’.
In case of success, the IUA Authorization Server SHALL send the authorization code to the Authorization Client redirect-uri via the user agent.
The Authorization Client SHALL perform the HTTP POST request to the Authorization token endpoint to resolve the authorization code to the access token, sending the client_id and client_secret in the HTTP authorization header field.
When retrieving the token request, the Authorization Server SHALL verify that the user is authenticated compliant to the regulations of the Swiss EPR, either by validating the identity token send with the token request or by redirecting the Authorization Client's user agent to an certified Identity Provider.
The Authorization Server SHALL respond with the Get Access Token response as defined in Get Access Token Response only if all checks are successful.
In case of failure, the IUA Authorization Server SHALL respond with HTTP error code 401 ‘Not authorized’.
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.
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 specified may look like:
GET authorize?
response_type=code&
client_id=app-client-id&
redirect_uri=http%3A%2F%2Flocalhost%3A9000%2Fcallback&
launch=xyz123&
person_id=761337610411353650%5E%5E%5E%262.16.756.5.30.1.109.6.5.3.1.1%26ISO&
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&
code_challenge=ZmVjMmIwMWYyYTNjZWJiNTgyNTgxYzlmOGYyMWM0MWI3YmZhMjQ4YjU5MDc3Mzk4MDBmYTk0OThlNzZiNjAwMw&
code_challenge_method=S256
In the second step of the conversation, the IUA Authorization Server send a HTTP GET to the Authorization Client's user agent conveying the authorization code, e.g.:
GET /callback?code=8V1pr0rJ&state=98wrghuwuogerg97
In the third step of the conversation, the IUA Authorization Client sends a HTTP POST request to the token endpoint of IUA Authorization Server to exchange the authorization code and optional identity token (signed JWT or SAML 2 Assertion) to the access token, e.g.:
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&
requested_token_type=urn:ietf:params:oauth:token-type:jwt
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUlMyNTYifQ[...omitted for brevity...]
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).
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).
JWT Claim (Extension) | Optionality (Basic/ Extended) | XUA Attribute EPR | Remark |
---|---|---|---|
subject_name | R/R | urn:oasis:names:tc:xspa:1.0:subject:subject-id | Plain text's username. |
subject_organization | O/O | urn:oasis:names:tc:xspa:1.0:subject:organization | The name of the user’s organization or institution as text. |
subject_organization_id | O/O | urn:oasis:names:tc:xspa:1.0:subject:organization-id | The OID of the user’s organization in URN notation. |
subject_role | O/R | urn:oasis:names:tc:xacml:2.0:subject:role | Code indicating the user role. In the Swiss EPR the value SHALL be taken from the EPR Role Code Value Set. |
purpose_of_use | O/R | urn:oasis:names:tc:xspa:1.0:subject:purposeofuse | Code indicating the purpose of use. In the Swiss EPR the value SHALL be taken from the EPR Purpose Of Use Value Set. |
home_community_id | O/R | urn:ihe:iti:xca:2010:homeCommunityId | The user’s home community identifier where the request originated. Its value should be an OID in URN notation. |
person_id | O/R | urn:oasis:names:tc:xacml:2.0:resource:resource-id | SHALL be the EPR-SPID of the patients EPR. |
The Authorization Server and Resource Server SHALL support the following extensions to the JWT access token for an EPR user:
JWT Claim (Extension) | Optionality (Basic/ Extended) | XUA Attribute EPR | Remark |
---|---|---|---|
user_id | O/R | <NameID> child element of the <Subject> | |
user_id_qualifier | O/R | Name qualifier attribute of <NameID> |
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:
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.
ch_group array element | Optionality (Basic/ Extended) | XUA Attribute EPR | Remark |
---|---|---|---|
name | O/R | urn:oasis:names:tc:xspa:1.0:subject:organization | An array of groups with properties name and id. |
id | O/R | urn:oasis:names:tc:xspa:1.0:subject:organization-id | An array of group names and group ids. |
The Authorization Server and Resource Server shall support the following extensions to the JWT access token:
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).
JWT Claim (Extension) | Optionality (Basic/ Extended) | XUA Attribute EPR | Remark |
---|---|---|---|
principal | O/R | urn:e-health-suisse:principal-name | Name of the healthcare professional an assistant is acting on behalf of. |
principal_id | O/R | urn:e-health-suisse:principal-id | GLN of the healthcare professional an assistant is acting on behalf of. |
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.
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"
}
}
}
There are no CapabilityStatement resources defined for this transaction.
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.
When receiving requests of transactions where the EPR-SPID is provided in the IUA token and in the transaction body, the Resource Servers SHALL verify that both are the same.
The actors SHALL support the traceparent header handling, as defined in Appendix: Trace Context.
There is no audit event required for this transaction.