-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
a17f82c
commit c257a25
Showing
1 changed file
with
17 additions
and
24 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,29 +3,29 @@ | |
|
|
||
|  | ||
|
|
||
| This plugin delivers the eID identity provider which enables user creation and authentication with the German ID card. | ||
| This plugin enables registering and authenticating users via the German ID card in Keycloak. The actual checking of the ID card is not done in Keycloak, but in a so-called eID server. If you follow the guide below, we connect to the Governikus test server that is publicly available. If you would use this plugin in production, you would need your own eID-server. | ||
|
|
||
| ## Known limitations | ||
| Users are authenticated with the `restrictedID` which is assigned to exactly one ID card. | ||
| The `restrictedID` changes when a user gets a new ID card. Currently, there is no solution implemented to update a user account in this case. | ||
| The `restrictedID` changes when a user gets a new ID card. Currently, there is no solution implemented to update a user account in this case. | ||
|
|
||
| :warning: This plugin is not considered production ready, but should rather show that eID authentication with Keycloak is possible. If you want to use this in production, feel free to reach out to the @schmitzhermes via e-mail. | ||
|
|
||
| ## Installation guide | ||
| ### Requirements | ||
| For the authentication process, Keycloak communicates with the [Governikus ID Panstar](https://www.governikus.de/en/loesungen/produkte/id-panstar/) server and the locally running [AusweisApp](https://www.ausweisapp.bund.de/download). | ||
| It is necessary to have access to both, the respective Governikus ID Panstar Server URL and the keys and certificates that secure the communication with the server. | ||
| To get you started as fast as possible, we deliver an out-of-the-box solution that uses publicly available keys and certificates provided by the Governikus ID Panstar SDK. | ||
| This must be understood as a Proof-of-Concept and is NOT production ready. Feel free to reach out to us if you have any questions: [email protected]. | ||
|
|
||
| ### Quickstart with Docker | ||
| ### 1) Run Keycloak with the eID Provider | ||
| Use the following commands to set up Keycloak with the eID identity provider plugin in a Docker container. | ||
|
|
||
| `git clone [email protected]:L21s/keycloak-eid-identity-provider.git` | ||
| `cd keycloak-eid-identity-provider` | ||
| `mvn clean package -P dev` | ||
| `docker-compose up` | ||
|
|
||
| ### Configuration | ||
| #### Keycloak | ||
| If the eID identity provider plugin was registered successfully, `TcTokenEndpointFactory` and `EidIdentityProviderFactory` are detected and logged throughout the execution of the build and the run command. | ||
|
|
||
| <img width="1730" alt="Bildschirmfoto 2024-01-29 um 12 06 30" src="https://github.com/L21s/keycloak-eid-identity-provider/assets/85928453/1844fcfd-b863-4db6-944c-a383e56a3906"> | ||
|
|
||
| ### 2) Configure Keycloak to enable the eID provider | ||
| Follow these steps to configure the eID identity provider for using the Proof-of-Concept. | ||
| 1. Go to `https://localhost:8443` and log in to the Keycloak Admin UI with `admin` as Username and Password. | ||
| 2. Go to identity providers and select eID. | ||
|
|
@@ -38,25 +38,18 @@ The final configuration looks like this. | |
|
|
||
|  | ||
|
|
||
| #### AusweisApp | ||
| ### 3) Configure the AusweisApp for test purposes | ||
| > [!NOTE] | ||
| > This is only necessary in a test setup. In production setups, of course, users do not need to follow these steps. | ||
| For using the Proof-of-Concept, the AusweisApp must be running on the same machine as Keycloak. In addition, it must be configured to mock an ID card. | ||
| Therefore, the developer mode must be activated as described [here](https://www.ausweisapp.bund.de/ausweisapp2/help/1.20/en/Windows/settings-developer.html#aktivieren-des-entwicklermodus). | ||
| Afterward, go to Settings -> Developer options and activate the internal card simulator. | ||
| Now, everything is set to go to `https://localhost:8443`, log out of the admin console, and click `eid` to start the authentication process. | ||
| As a result, you are logged in with the test user *erika mustermann*. Please note: You probaly won't see anything here in the first place, because Erika Mustermann is no Keycloak Admin and you are trying to log in to the admin console. You can use any frontend of your choice to test it or make erika_mustermann an Keycloak Admin (login via the `admin` user). | ||
|
|
||
| ### Setup without Docker | ||
| Follow these steps to run Keycloak including the eID identity provider without Docker: | ||
| 1. Download Keycloak [here](https://github.com/keycloak/keycloak/releases). | ||
| 2. Go to this project's directory and run `mvn clean package -P dev`. | ||
| 3. Copy the content of this project's `target/deploy` directory to the downloaded Keycloak's `providers` directory as described [here](https://www.keycloak.org/docs/latest/server_development/index.html#registering-provider-implementations). | ||
| 4. Open the keycloak directory and use `bin/kc.sh build` to build the project including the eID identity provider. | ||
| 5. Run `bin/kc.sh start-dev --https-key-store-file=<path-to-keycloak-eid-identity-provider-repository>/src/main/resources/keys/tls-ssl-commcert.p12 --https-key-store-password=123456` to start Keycloak. | ||
| 6. Go to `https://localhost:8443` and manually create a user to add and configure an eID identity provider. | ||
|
|
||
| If the eID identity provider plugin was registered successfully, `TcTokenEndpointFactory` and `EidIdentityProviderFactory` are detected and logged throughout the execution of the build and the run command. | ||
| ### 4) Login with (simulated) ID card | ||
| If you now login into Keycloak, you can choose "eid" as an identity provider in the login dialog. If you click on it, the AusweisApp will start and authenticate you. If you followed the guide, it will also authenticate you without actually presenting an ID card, as the AusweisApp is in development mode. | ||
|
|
||
| <img width="1730" alt="Bildschirmfoto 2024-01-29 um 12 06 30" src="https://github.com/L21s/keycloak-eid-identity-provider/assets/85928453/1844fcfd-b863-4db6-944c-a383e56a3906"> | ||
| :warning: If you try this on the Keycloak admin console you will end up in a blank page, because the person registering via eID does not have access to the Keycloak admin console (as they are no admins, of course). | ||
|
|
||
| ## Detailed explanation of authentication flow | ||
| ```mermaid | ||
|
|
||