eIDs
Learn more about German Personalausweis token contents, how to test your integration and how to gain access to production.
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 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.
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).
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.
To configure the desktop AusweisApp to use the simulator, follow these steps:
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:
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.
To configure the desktop AusweisApp to use the simulator, follow these steps:
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:
The AusweisApp should now skip the card scanning step and you should see 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. 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.
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, the profile will always 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 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.
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 5 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.