German Personalausweis

​

JWT/Token example

Triggered with acr_values=urn:grn:authn:de:personalausweis.

​

Testing

The Personalausweis is a physical card with an embedded chip which can be read by e.g. a NFC-enabled smart phone for use as an eID. The solution thus always requires the user to scan their physical card to authenticate with their eID. In testing you can either use a physical test card (if you have one) or a simulator.

​

Installing the AusweisApp

The AusweisApp for scanning the physical Personalausweis card is available for both desktop and mobile (download). It can be used to scan a physical test card (if you have one) or be configured to use a simulator instead (see below).

Configuring the AusweisApp for testing

If you do not have a physical Personalausweis test card, you can configure the AusweisApp to use a simulator for testing. When configured to use the simulator, the AusweisApp will skip the scanning step and instead always use the same hard-coded test user. Note that the simulator does not work exactly the same on desktop and mobile. The official documentation for the AusweisApp is available here.

Configuring desktop simulator

To configure the desktop AusweisApp to use the simulator, follow these steps:

1. Open the AusweisApp
2. On the Start page, click Help
3. On the Help page, click Information (on the left)
4. On the Information page, click on the Application Version text 10 times
5. You should now get a notification from the AusweisApp saying "Developer options activated"
6. Click Back (in the top left) to go back to the Start page
7. On the Start page, click Settings
8. On the Settings page, click Developer options (on the left)
9. On the Developer options page:
   1. Toggle Testmode for the self-authentication to be "on" (toggle button to the right)
   2. Toggle Internal card simulator to be "on" (toggle button to the right)
10. Click Back (in the top left) to go back to the Start page

The AusweisApp will now use the hard-coded test user for any authentications. You can test this by clicking See my personal data on the Start page and proceeding through the flow as follows:

1. Click See my personal data
2. Click Proceed to PIN entry

The AusweisApp should now skip the card scanning step and you should see the data for the test user Erika Mustermann.

Note that you will have to disable the simulator to use the AusweisApp to scan physical cards.

Configuring mobile simulator

To configure the desktop AusweisApp to use the simulator, follow these steps:

1. Open the AusweisApp
2. On the Start page, tap Help (on the bottom bar)
3. On the Help page, scroll to the bottom and tap Version information
4. On the Version Information page, tap on the Application Version text 10 times
5. A popup will appear saying "Advanced settings activated"
6. Tap Settings (on the bottom bar)
7. On the Settings page, scroll to the bottom where you should see Developer options
8. On the Developer options page:
   1. Toggle Testmode for the self-authentication to be "on" (toggle button to the right)
   2. Toggle Internal card simulator to be "on" (toggle button to the right)
9. Tap Start (on the bottom bar) to go back to the Start page

The AusweisApp will now allow you to select the Simulator during authentications. You can test this by swiping to the right and tapping See my personal data on the Start page, then proceeding through the flow as follows:

1. Tap See my personal data
2. Tap Proceed to PIN entry
3. On the Identify screen, you should now be able to select SIM (instead of just NFC and WiFi)
4. Select SIM and then tap Continue

The AusweisApp should now skip the card scanning step and you should see the data for the test user Erika Mustermann.

​

Integrating with Personalausweis

​

Data profiles for German Personalausweis

The Personalausweis has a number of data groups which contain e.g. the given name, the address or the nationality of the person authenticating. The AusweisApp will inform the user which data groups are being requested when they scan their Personalausweis.

One of the data groups is the Pseudonym, which is a service- and card-specific identifier (German: dienste- und kartenspezifisches Kennzeichen) of the user. The Pseudonym uniquely identifies the user in a privacy-preserving way and is used to generate the sub claim identifying the subject of the JWT.

The data groups are bundled together into profiles which contain collections of data groups. Criipto has defined some standard profiles for various use cases, and request pricing is based on these profiles.

The table below contains a description of the data groups and standard profiles.

For applications configured to use a dynamic scope strategy, a profile can be selected on each request using the scope parameter prefixed with odis:, e.g. odis:Profile1. For applications configured to use a static scope strategy, you can configure the profile in the Dashboard. If nothing is configured, the profile will be Pseudonym.

It is possible to define your own profiles if you have special requirements; if you would like to do so, please contact sales.

​

Transaction information

You can add a reference text to display to the user while they scan the physical Personalausweis with the AusweisApp. The reference text consists of a template with a single placeholder and a dynamic parameter called txinfo. If a template is registered for the client, txinfo must be passed as a login_hint on each request. The template may be up to 118 characters long and can contain any characters. The txinfo parameter can be up to 32 characters long and can only contain alphanumeric characters (in particular, it cannot contain spaces).

​

Flow selection

You should usually let the end user select whether they would like to use the AusweisApp on the same device as their browser or on another device (e.g. a mobile phone). Verify will normally display a screen to let the user select which device they would like to use. You can skip this screen for a request by passing either flow:same-device or flow:another-device as a login_hint.

This can be useful in testing, and also allows you to build your own selection screen instead of using the one displayed by Verify. We do not recommend skipping the selection screen under any other circumstances, since you risk "stranding" users who would have chosen the other option.

​

Test authorize requests

You can use Criipto's test environment to test your integration before ordering your own client credentials (see below). The test environment has a transaction information template registered, so you must pass a txinfo parameter on every request. The template is set up such that you can for instance use your company name as the txinfo parameter.

You can use the Authorize URL builder to generate URLs for testing.

It is possible to set up your own test environment if you require custom profiles and/or a custom transaction information template. If you would like to do so, please contact support.

​

Getting ready for production

To start accepting real users with Personalausweis, you must first request your own client credentials and provide a client certificate to be signed. The credentials consist of a client id and a client secret. You must have completed step 4 in the Getting ready for production guide. You will need the production domain to complete the order for your client credentials. As part of the credential request, you may also register custom profiles and a transaction information template (see above).

Once you have a signed client certificate, you can upload it in the dashboard. You will then be able to use your client credentials and your tenant for Personalausweis authentication.