IDP plugin to integrate the gematik central-IDP with the gematik Authenticator application. Allows a user to log in with his HBA (Heil-Berufs-Ausweis) card, supplying HBA and SMCB (Elektronischer Praxis-/Institutionsausweis) card information. Additionally, HBA- and SMCB-specific IDP mappers are provided.
Please be aware, that this plugin was developed for and tested with Keycloak 24, 25 and 26 Quarkus. With version 22, Keycloak moved from JavaX to Jakarta, which is why this version is incompatible with other versions of Keycloak.
- Run
mvn clean installin this directory.- By default, the Kotlin dependency is included in the jar. If you already have the Kotlin dependency in place,
run
mvn clean install -P=-includeKotlin,excludeKotlinwhich excludes Kotlin from the jar.
- By default, the Kotlin dependency is included in the jar. If you already have the Kotlin dependency in place,
run
- After completion, install the
gematik-idpjar from the target folder into your Keycloak instance by copying it into your Docker container under/opt/keycloak/providers/and rebuilding the Quarkus environment. - Add the new Identity Provider
gematik-idpfollowing the official guide Integrating identity providers. Specific configuration properties are listed below. - Set the login theme in your realm, where you added the Identity Provider, to gematik-idp for the full support of
all features. You can also add the content from
./themes/gematik-idpto you custom theme if necessary.- By default, the theme-resources are included in the jar. If you have your own theme, you can exclude the
theme-resources with specifying the maven profile
excludeThemeResources.
- By default, the theme-resources are included in the jar. If you have your own theme, you can exclude the
theme-resources with specifying the maven profile
A docker-compose.yml file is provided, which starts a Keycloak and a Postgres container, respectively. It also imports
the fully configured Gematik-IDP realm defined under sample-realm/GematikIDP-ref-idp.json. This deployment depends on
a parallel running ref-idp-server instance, which is also started by the
docker-compose file.
You'll need to manually switch the Admin console theme to gematik-idp in the master realm. The new admin console theme
is
currently not supported by this plugin.
If you don't see any of these attributes, please make sure to switch to the old admin console theme. We currently don't support the new theme with this plugin.
| Name | Value | Description |
|---|---|---|
| Multiple Identity Mode | ON or OFF | If this option is switched on, the current timestamp is appended to the Gematik-IDP-ID, which means that an eHBA can be linked to several users at the same time. You will not be able to login with your registered IDP credentials in this case. |
| Authentication Flow | Either single, HBA, SMCB or multiple request | Choose your preferred authentication flow. When single, HBA or SMCB is selected, only a single request is made to the Gematik-Authenticator, but this flow requires at least an Authenticator in version 4.6.0. Otherwise, multiple requests are made to the Gematik-Authenticator. |
| Authenticator Timeout (ms) | default: 20000 | Timeout in milliseconds until the process of establishing a connection to the Authenticator is aborted |
| Gematik IDP openid configuration url | https://idp.app.ti-dienste.de/.well-known/openid-configuration https://idp.zentral.idp.splitdns.ti-dienste.de/.wellknown/openid-configuration |
https://idp.app.ti-dienste.de availble from public internet https://idp.zentral.idp.splitdns.ti-dienste.de/ only available from TI (Telematik-Infrastruktur) |
| Enable token signer certificate validation | ON or OFF (default) | If enabled, the ID-Token signing certificate is validated against the full gematik certificate chain. A caching mechanism is used to avoid redundant validations. |
| Enable openid discovery document signing certificate validation | ON or OFF (default) | If enabled, the signing certificate of the JWS openid discovery document, is validated with the full gematik certificate chain. |
| Gematik IDP timeout (ms) | default: 10000 | Timeout in milliseconds until the process of establishing a connection to the Gematik IDP is aborted |
| Gematik IDP User-Agent | User-Agent Header as specified in "gemILF_PS_eRp - A_20015-01": <Produktname>/<Produktversion> <Herstellername>/<client_id> |
|
| Client ID | Client ID to verify your request on C-IDP side. Assigned on registration for the IDP on Gematik side | |
| Client Secret | Client Secret to verify your request on C-IDP side. Assigned on registration for the IDP on Gematik side | |
| Scopes | default: openid | Scopes to send on each request. |
| Authenticator Auto-Launch | ON or OFF (default) | When ON, the login page opens the Gematik Authenticator immediately and skips the confirmation modal. When OFF (default), the modal is shown and the user must confirm before the app is launched. |
Because of limitations in the way, Keycloak displays dynamic identity provider settings, it is currently not possible to
define a custom alias or display name for the Gematik-IDP identity provider. This means, that only a single Gematik-IDP
identity provider can be configured per realm, since that one always gets the alias gematik-idp and the alias cannot
be shared between identity providers.
If you need to have multiple Gematik-IDP identity provider for your realm or want to define a custom display name, please consider importing them via a partial realm import. A discussion regarding this problem ist currently being done in the Keycloak-Github:
On server startup, the gematik TSL XML file is downloaded from the urls defined in GEMATIK_IDP_TSL_PRIMARY_URL or
GEMATIK_IDP_TSL_SECONDARY_URL environment variables.
See gemSpec_TSL for the available
urls.
The XML signing certificate is validated against the intermediate certificates from the TSL file and the gematik
root certificates from the Keycloak truststore. To add the gematik root certificates to the Keycloak truststore,
configure Keycloak correctly (see
Keycloak - Configuring trusted certificates) and download the
root certificates from:
- PU: https://download.tsl.ti-dienste.de/ECC/ROOT-CA/
- RU: https://download-ref.tsl.ti-dienste.de/ECC/ROOT-CA/
or execute the script:
chmod +x ./gematik-root-certificates/download-certificates.sh &&
./gematik-root-certificates/download-certificates.sh ./gematik-root-certificatesAll certificates stored in gematik-root-certificates are mounted to the Keycloak truststore for local development.
If the signing certificate is valid, the gematik certificate chain is stored and used for future validation of the signing certificate of the openid-configuration JWS.
Additionally, a periodic task is scheduled to update the gematik certificate chain from the TSL XML every 6 hours. The
interval can be overwritten via the environment variable GEMATIK_IDP_TSL_UPDATE_INTERVAL_MS.
The ID-Token signing certificate can be validated against the intermediate certificates from the TSL file and the gematik
root certificates from the Keycloak truststore. This feature is disabled by default and can be enabled via the
Enable token signer certificate validation toggle in the admin UI.
A caching mechanism avoids redundant validations: once a certificate is validated, it is cached for 1 hour (default).
The TTL can be overwritten via the environment variable GEMATIK_IDP_CERTIFICATE_VALIDATION_CACHE_TTL_MS.
The cache is automatically invalidated when the TSL is updated.
The template and JavaScript files are supplied as part of the compiled jar and are available under
/src/main/resources/theme-resources. To use the script it has to be added to the theme.properties file as scripts:
scripts=js/gematik-idp.js. Sample theme configuration can be found under /themes/gematik-idp. For more information
about extending your own themes please read
the Deploying Themes section in
the Keycloak documentation.
Please make sure to use your standard browser without an incognito window, when using the authenticator://
Authenticator Url
If you configured the Authenticator Url authenticator:// and aren't using the new authentication flow, the Gematik-
Authenticators opens two tabs in your standard browser while authenticating. This is necessary, because the Gematik-cIDP
doesn't support requests for the SMCB and eHBA at the same time and this plugin therefore needs to do two separate calls
to the Gematik-Authenticator. Additionally, the Gematik-Authenticator isn't able to open the response in the same tab,
because of limitations of the authenticator:// endpoint.
This can cause problems, when you aren't using your standard browser or an incognito window while authenticating. In this case, the tab opened by the Gematik-Authenticator doesn't know anything about your session, which in turn leeds to exception in the plugin backend.
If Multiple Identity Mode is set to TRUE, it is possible to create multiple IDP links for one user, but registering the same IDP for the same user is still not possible and will result in a database error. To prevent this error from happening, it is possible to extend the appropriate flow that uses Multiple Identity Mode with a conditional branch that displays a more appropriate error message if a user has already registered an IDP link for your Gematik-IDP, so this illegal state cannot be reached.
- Go to "Roles > Realm Roles" and create a new role that registered users will get assigned
- Go to "Identity Providers > Your Gematik-IDP > Mappers" and create a new mapper of the type "Hardcoded Role" that maps to the newly created role
- Go to "Authentication > Flows" and select your registration authentication flow from the dropdown. Click "Add flow"
and add a new generic flow
- Check the "CONDITIONAL" radio button next to the new entry
- Add executions for "Condition - User Role" and "Deny Access" as children to this flow via the "Actions" menu
- Check the radio button "REQUIRED" next to both added executions
- Configure the "Condition - User Role" execution to check for the newly create role from step 1
- Configure the "Deny Access" execution to show the error message. You're able to localized messages by using a message property key here.
- Move the newly added flow up to the top of the list.
Now the OTC Registration flow will check, if the user that tries to go through this flow has the newly created role and will show the "already registered" error page in that case. Otherwise, the flow continues as usual and the user will be assigned the newly created role via the hardcoded role mapper on completion of the registration.
Currently, this plugin makes two requests against the Gematik-Authenticator, as described above: One for the eHBA and on for the SMCB data.
Some browsers based on Chromium (e.g. Chrome, Edge, etc.) block the second request with an error message when no user interaction was done between the requests. To prevent this from happening, a modal is shown which the user has to acknowledge before the Gematik-Authenticator is opened.
A description of the different authentication flows can be found in the following files: