11[ ![ Quality Gate Status] ( https://sonarcloud.io/api/project_badges/measure?project=oviva-ag_keycloak-gesundheitsid&metric=alert_status&token=64c09371c0f6c1d729fc0b0424706cd54011cb90 )] ( https://sonarcloud.io/summary/new_code?id=oviva-ag_keycloak-gesundheitsid )
22[ ![ Coverage] ( https://sonarcloud.io/api/project_badges/measure?project=oviva-ag_keycloak-gesundheitsid&metric=coverage&token=64c09371c0f6c1d729fc0b0424706cd54011cb90 )] ( https://sonarcloud.io/summary/new_code?id=oviva-ag_keycloak-gesundheitsid )
33
4- # Keycloak Identity Provider for GesundheitsID (eHealthID)
4+ # OpenID Connect Relying Party for GesundheitsID (eHealthID)
55
66## Contents
7+
8+ - [ ehealthid-rp] ( ./ehealthid-rp ) - A standalone application to act as a OpenID Connect (OIDC)
9+ Relying Party. Bridges OIDC and Germany's GesundheitsID OpenID federation.
10+ - [ esgen] ( ./esgen ) - A script to generate keys and federation registration forms.
711- [ gesundheitsid] ( ./gesundheitsid ) - A plain Java library to build RelyingParties for GesundheitsID.
8- - API clients
9- - Models for the EntityStatments, IDP list endpoints etc.
10- - Narrow support for the 'Fachdienst' use-case.
12+ - API clients
13+ - Models for the EntityStatments, IDP list endpoints etc.
14+ - Narrow support for the 'Fachdienst' use-case.
15+
16+ ## Generate Keys & Register for Federation
17+
18+ In order to participate in the GesundheitsID one needs to register the entity statement of the IDP
19+ or in this case the relying party here.
20+
21+ To simplify matter, here a script to generate fresh keys as well as the XML necessary to register
22+ with Gematik.
23+
24+ See [ Gematik documentation] ( https://wiki.gematik.de/pages/viewpage.action?pageId=544316583 ) for
25+ details
26+ on the registration process.
27+
28+ ### Generate Fresh Keys and Prepare Registration
29+
30+ ``` shell
31+ # a string received from Gematik as part of the registration process
32+ export MEMBER_ID=FDmyDiGa0112TU
33+
34+ ./gen_keys.sh \
35+ --issuer-uri=https://mydiga.example.com \
36+ --member-id=" $MEMBER_ID "
37+ --organisation-name=" My DiGA"
38+ --generate-keys
39+ ```
40+
41+ ### Re-use Existing Keys and Prepare Registration
42+
43+ ``` shell
44+ # a string received from Gematik as part of the registration process
45+ export MEMBER_ID=FDmyDiGa0112TU
46+
47+ ./gen_keys.sh \
48+ --issuer-uri=https://mydiga.example.com \
49+ --member-id=" $MEMBER_ID "
50+ --organisation-name=" My DiGA"
51+ --signing-jwks=./sig_jwks.json \
52+ --encryption-jwks=./enc_jwks.json
53+ ```
1154
1255## End-to-End Test flow with Gematik Reference IDP
1356
1457** Prerequisites** :
1558
16591 . Setup your test environment, your own issuer ** MUST** serve a ** VALID** and ** TRUSTED** entity
17- statement. See [ Gematik docs] ( https://wiki.gematik.de/pages/viewpage.action?pageId=544316583 )
60+ statement. See [ Gematik docs] ( https://wiki.gematik.de/pages/viewpage.action?pageId=544316583 )
18612 . Setup the file ` env.properties ` to provide
19- the [ X-Authorization header] ( https://wiki.gematik.de/display/IDPKB/Fachdienste+Test-Umgebungen )
20- for the Gematik
62+ the [ X-Authorization header] ( https://wiki.gematik.de/display/IDPKB/Fachdienste+Test-Umgebungen )
63+ for the Gematik
21643 . Setup the JWK sets for signing and encryption keys
2265
2366``` java
@@ -72,29 +115,35 @@ See [AuthenticationFlowExampleTest](https://github.com/oviva-ag/keycloak-gesundh
72115
73116## Working with Gematik Test Environment
74117
75-
76118### Gematik Test Sektoraler IdP in Browser
77119
78- Since the Gematik reference IDP in the Test Environment needs a custom header, it can not be used directly in the browser for authentication.
120+ Since the Gematik reference IDP in the Test Environment needs a custom header, it can not be used
121+ directly in the browser for authentication.
79122Setting up a proxy with a header filter can get around that limitation though.
80123
81- ** Prerequisite:** Install some Chrome-ish browser like [ Thorium] ( https://github.com/Alex313031/Thorium-MacOS/releases ) or Chromium.
124+ ** Prerequisite:** Install some Chrome-ish browser
125+ like [ Thorium] ( https://github.com/Alex313031/Thorium-MacOS/releases ) or Chromium.
126+
127+ 1 .
128+
129+ launch ` mitmweb ` : ` mitmweb -p 8881 --web-port=8882 --set "modify_headers=/~q & ~d gsi.dev.gematik.solutions/X-Authorization/<value goes here>" `
82130
83- 1 . launch ` mitmweb ` : ` mitmweb -p 8881 --web-port=8882 `
841312 . launch Chrome-like browser
85132 ```
86133 /Applications/Thorium.app/Contents/MacOS/Thorium --proxy-server=http://localhost:8881
87134```
88- 3 . setup ` modify_headers ` option
89- ``` mitmproxy
90- # modify_headers filter
91- /~q & ~d gsi.dev.gematik.solutions/X-Authorization/<value goes here>
92- ```
93135
94136## Setup Test VM
95137
138+ For testing the entity statement of the relying party must be publicly available via HTTPS. Setting
139+ up a quick VM
140+ with a caddy reverse proxy makes that easy.
141+
96142``` shell
97143
144+ # adapt as necessary, make sure to set up the corresponding DNS A records
145+ DOMAIN=mydiga.example.com
146+
98147sudo apt update
99148sudo apt install jq openjdk-17-jre-headless
100149
@@ -105,12 +154,12 @@ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo
105154sudo apt update
106155sudo apt install caddy
107156
157+ # caddy enables itself by default, we don't want it
108158sudo systemctl disable --now caddy
109159
110- sudo caddy reverse-proxy --from=t.oviva.io --to=:1234
160+ sudo caddy reverse-proxy --from=$DOMAIN --to=:1234
111161```
112162
113-
114163## Helpful Links
115164
116165- [ Gematik Sectoral IDP Specifications v2.0.1] ( https://fachportal.gematik.de/fachportal-import/files/gemSpec_IDP_Sek_V2.0.1.pdf )
0 commit comments