eIDs
Learn more about German Personalausweis token contents, how to test your integration and how to gain access to production.
| Country | Germany |
| Operated by | Federal Ministry of the Interior and Community |
| eID service provider | adesso Group |
acr_values | urn:grn:authn:de:personalausweis |
| Levels of assurance (LoA) | High |
| User data | sub (from the Pseudonym) |
| Optional user data |
|
| Flows | Same device · Another device (flow selection) |
Triggered with acr_values=urn:grn:authn:de:personalausweis.
The level of assurance for all Personalausweis authentications is: High. Learn more about assurance levels.
The Personalausweis is a physical card with an embedded chip which can be read by, for example, an NFC-enabled smartphone 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.
The AusweisApp for scanning the physical Personalausweis card is available for both desktop and mobile. Download AusweisApp. Use it with a physical test card or configure it to use a simulator instead, as described below.
If you do not have a physical Personalausweis test card, configure the AusweisApp to use a simulator. 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. For more details, see AusweisApp extended documentation for administrators and developers (PDF).
Desktop simulator
The AusweisApp will now use the hard-coded test user for every authentication. To test it, click See my personal data on the Start page and proceed through the flow as follows:
The AusweisApp should now skip the card scanning step and show the data for the test user Erika Mustermann.
You have to disable the simulator to use the AusweisApp to scan physical cards.
Mobile simulator
The AusweisApp will now use the simulator during authentications. To test it, swipe to the right and tap See my personal data on the Start page, then proceed through the flow as follows:
The AusweisApp should now skip the card scanning step and show the data for the test user Erika Mustermann.
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.
Note that the Pseudonym is both service-specific and card-specific.
Service-specific means that you cannot use the Pseudonym (i.e. the sub) to link users across services.
Card-specific means that the Pseudonym will change when the user gets a new physical Personalausweis (e.g. due to having lost the card or changing address).
This means that you must store other data about the user if you plan to use the Personalausweis to identify users, such that you can match the identity of the user when they obtain a new physical Personalausweis.
Please refer to the German Act on Identity Cards and Electronic Identification for more details about what you are allowed to do with the data from the Personalausweis.
The data groups are bundled together into profiles which contain collections of data groups. Idura 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.
| Profile | Data groups | Intended use case |
|---|---|---|
| Pseudonym | Pseudonym | User login after registration |
| Profile 1 | Pseudonym, First Name, Family Name, Religious Order / Artistic Name, Academic Title, Date of Birth, Place of Birth, Birth Name | User registration/one-time authentication |
| Profile 2 | Everything in Profile 1, plus Nationality and Address (normal place of residence) | Know-your-customer (KYC) |
| Profile 3 | Everything in Profile 2, plus Document Type, Issuing Country (always “D” for Germany), Date of Expiry and Residence Permit I | Extended KYC with document metadata |
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.
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).
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.
You can use Idura’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.
To start accepting real users with Personalausweis, you need your own client credentials. The credentials consist of a client id and a client secret.
To request them, fill out the Personalausweis order form. You must have a Production domain before you submit the form. As part of the credential request, you can also register custom profiles and a transaction information template.
Processing typically takes 10-15 business days. When adesso approves your request, we receive your client credentials and install them in your Dashboard. You can then use Personalausweis to authenticate real users.
