Attributes reference
You use Personalausweis to verify the identity of end-users and obtain relevant personal information. The end-user information is mapped to data attributes.
This page shows what attributes you can request when using the following authentication protocols:
Available attributes
Attributes (scopes in OIDC) allow you to specify the desired set of end-user data that you want to retrieve from an authentication transaction.
After the end-user consents to share their personal information and completes an authentication, you can retrieve the data from an endpoint - the endpoint varies per authentication protocol.
The attributes your application can request depend on the user information required by your use case and the plan you purchased in your agreement with Signicat.
National identity number and pseudonym
Since in Germany there is no national identity number (NIN) in the full meaning of the term, Personalausweis does not provide the NIN. Instead, the 'pseudonym' (Dienste- und Kartenspezifische Kennzeichen (DKK)) acts as a unique identifier for an identity card and provider combination.
Signicat returns the pseudonym in the subject ID attribute - a unique identifier to correlate the end-user across multiple authentication transactions. In your application, use the pseudonym to log in the end-user over recurring authentications - this allows you to identify returning users.
The pseudonym is inherently linked to the ID card and changes when the end-user receives a new ID card. You need to design your application to update the pseudonym in your user profile when the end-user gets a new ID card.
Subject ID
The subject ID (sub) maps to the pseudonym in Personalausweis. Note that the subject is the hashed value of the raw pseudonym that Signicat receives from Personalausweis. To obtain the raw value, you must request the idpId (idp-id in OIDC) explicitly in the authentication request.
For more information about the subject and idpId, see the Subject documentation.
If you request only the date of birth attribute to perform age verification, you'll receive a random string instead of the pseudonym in the subject (sub). A random string protects the privacy of the end-user and respects their consent (to only share their date of birth) in the AusweisApp.
Using the subject ID
In your application, you can use the subject ID to log in a specific end-user over recurring authentications.
- First, you obtain the pseudonym/subject ID the first time you perform a full identification of the end-user.
- Next, you store the pseudonym in the database of your application where you map the pseudonym to the personal data of the end-user.
- Then, you can log in the end-user over recurring authentications by matching the subject ID they submit with the value you stored in the database.
Gender
Note that Personalausweis does not return information about gender or biological sex.
OIDC scopes and claims
With OIDC, you specify scopes in the authorization request that triggers an identity verification flow.
After the end-user verifies themselves, consents to sharing their data and the flow is complete, you can retrieve the claims in the ID Token or through the UserInfo endpoint.
Use the following OIDC scopes in your request to perform end-user authentication with Personalausweis:
| Scope | OIDC Claim | Example | Description |
|---|---|---|---|
idp-id | idp_id | Subject ID that represents the 'pseudonym'. Use this to identify users across authentication sessions. | |
profile | given_name | Hans-Günther | Given name(s) of the end-user. |
profile | family_name | von Drebenbusch-Dalgoßen | Last name of the end-user. |
profile | name | Hans-Günther von Drebenbusch-Dalgoßen | Full name, including first and last name, of the end-user. |
date-of-birth | birthdate | 1946-01-25 | Date of birth of the end-user, represented as a string in YYYY-MM-DD date format. |
address | address | {"formatted": "WEG NR. 12 8E, 22043, HAMBURG, D","street_address": "WEG NR. 12 8E","locality": "HAMBURG","postal_code": "22043","country": "D"}, | Postal address of the end-user. Formatted as JSON object containing the following fields:
|
nationality | npa_nationality | D | Nationality of the end-user as specified on the ID document. |
npa-extra | npa_place_of_birth | BREMERHAVEN | Place of birth of the end-user. |
npa-extra | npa_academic_title | Dr.eh.Dr. | Academic title. Available only if the end-user holds a doctoral degree. |
npa-extra | npa_document_type | PASSPORT | ID document type. Available values:
|
npa-extra | npa_issuing_state | D | D for Germany (Deutschland). |
npa-extra | npa_date_of_expiry | 2027-04-05 | Document expiry date, represented as a string in YYYY-MM-DD date format. |
OIDC request example
To trigger an authentication, you build an OIDC request like:
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
&client_id=<OIDC_CLIENT_ID>
&response_type=code
&redirect_uri=<REDIRECT_URI>
&state=1599045135410-jFe
&scope=openid%20profile%20idp-id%20address%20date-of-birth%20nationality%20npa-extra
&acr_values=idp:npa
&prompt=login
&ui_locales=en
&nonce=1599046102647-dv4
OIDC response example
Below, you find an example of a response obtained from an identity verification flow with Personalausweis.
Scopes in request: openid, profile, idp-id, address, date-of-birth, npa-extra
Example of ID token in response:
{
"iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
"nbf": 1712237928,
"iat": 1712237928,
"exp": 1712238528,
"aud": "<OIDC_CLIENT_ID>",
"amr": [
"external"
],
"at_hash": "0zAbHkX...IeNDhkFoWlhKg",
"sid": "8930E9EC6FAF...874DF7BA6FC907383",
"sub": "1q3Yf0-oFOvZCALyfLI98p0lgWgoSneWICAwQOzY18E=",
"auth_time": 1712237927,
"idp": "npa",
"idp_id": "5D6C804FC44BEEDA94265B8CFC1B5D120DC6EBE949D8690DAF515D0D4163066F",
"family_name": "von Drebenbusch-Dalgoßen",
"given_name": "Hans-Günther",
"name": "Hans-Günther von Drebenbusch-Dalgoßen",
"birthdate": "1946-01-25",
"address": {
"formatted": "WEG NR. 12 8E, 22043, HAMBURG, D",
"street_address": "WEG NR. 12 8E",
"locality": "HAMBURG",
"postal_code": "22043",
"country": "D"
},
"npa_nationality": "D",
"npa_place_of_birth": "BREMERHAVEN",
"npa_academic_title": "Dr.eh.Dr.",
"npa_document_type": "ID",
"npa_issuing_state": "D",
"npa_date_of_expiry": "2027-04-05",
"sub": "7xtbj9vkM49arP-rVFIKoseL-rBIzuSjAgzEiixsg50=",
"idp_issuer": "https://eid-epan1-ref.eid-service.de",
"transaction_id": "355f42c4-a1ec-a...-87af-1eaad9a89435",
"sandbox": true
}
Example of a response from the UserInfo endpoint:
{
"family_name": "von Drebenbusch-Dalgoßen",
"given_name": "Hans-Günther",
"name": "Hans-Günther von Drebenbusch-Dalgoßen",
"birthdate": "1946-01-25",
"address": {
"formatted": "WEG NR. 12 8E, 22043, HAMBURG, D",
"street_address": "WEG NR. 12 8E",
"locality": "HAMBURG",
"postal_code": "22043",
"country": "D"
},
"npa_nationality": "D",
"npa_place_of_birth": "BREMERHAVEN",
"npa_academic_title": "Dr.eh.Dr.",
"npa_document_type": "ID",
"npa_issuing_state": "D",
"npa_date_of_expiry": "2027-04-05",
"sub": "7xtbj9vkM49arP-rVFIKoseL-rBIzuSjAgzEiixsg50=",
"idp_issuer": "https://eid-epan1-ref.eid-service.de"
}
Signicat Authentication REST API attributes
The Signicat Authentication REST API supports the following request attributes for Personalausweis:
| Attribute | Example | Description |
|---|---|---|
idpId | Subject ID that represents the 'pseudonym'. Use this to identify users across authentication sessions. | |
firstName | Hans-Günther | Given name(s) of the end-user. |
lastName | von Drebenbusch-Dalgoßen | Last name of the end-user. |
name | Hans-Günther von Drebenbusch-Dalgoßen | Full name, including first and last name, of the end-user. |
dateOfBirth | 1946-01-25 | Date of birth of the end-user, represented as a string in YYYY-MM-DD date format. |
address | {"formatted": "WEG NR. 12 8E, 22043, HAMBURG, D","street_address": "WEG NR. 12 8E","locality": "HAMBURG","postal_code": "22043","country": "D"}, | Postal address of the end-user. Formatted as JSON object containing the following fields:
|
nationality | D | Nationality of the end-user as specified on the ID document. |
placeOfBirth | BREMERHAVEN | Place of birth of the end-user. |
academicTitle | Dr.eh.Dr. | Academic title. Available only if the end-user holds a doctoral degree. |
documentType | PASSPORT | ID document type. Available values:
|
issuingState | D | D for Germany (Deutschland). |
dateOfExpiry | 2027-04-05 | Document expiry date, represented as a string in YYYY-MM-DD date format. |
Authentication API request example
To create a session using the Authentication REST API, you send a POST request to the CreateSession endpoint of the Authentication REST API. This is https://api.signicat.com/auth/rest/sessions.
You define the parameters of the session in the payload of the request. For example:
{
"allowedProviders": [
"npa"
],
"flow": "redirect",
"requestedAttributes": [
"firstName",
"lastName",
"name",
"nationality",
"dateOfBirth",
"placeOfBirth",
"academicTitle",
"documentType",
"issuingState",
"dateOfExpiry",
"address"
],
"callbackUrls": {
"success": "https://example.com/success",
"abort": "https://example.com/abort",
"error": "https://example.com/error"
}
}
Authentication API response example
The following is an example of a response showing the end-user information attributes:
{
...
"id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
"status": "SUCCESS",
"provider": "npa",
"subject": {
"id": "X6hYgXvTvNMf27-mC0cYzOUb4HBWR1feCSh5Ul7KiNQ=",
"idpId": "5D6C804FC44BEEDA94265B8CFC1B5D120DC6EBE949D8690DAF515D0D4163066F",
"firstName": "Hans-Günther",
"lastName": "von Drebenbusch-Dalgoßen",
"name": "Hans-Günther von Drebenbusch-Dalgoßen",
"nationality": "D",
"dateOfBirth": "1946-01-25",
"placeOfBirth": "BREMERHAVEN",
"academicTitle": "Dr.eh.Dr.",
"documentType": "ID",
"issuingState": "D",
"dateOfExpiry": "2027-04-05",
"address": "WEG NR. 12 8E, 22043, HAMBURG, D",
"addressFormatted": {
"FullAddress": "WEG NR. 12 8E, 22043, HAMBURG, D",
"Street": "WEG NR. 12 8E",
"City": "HAMBURG",
"PostalCode": "22043",
"Country": "D"
}
}
...
}
SAML 2.0 attributes
SAML Authentication service
When integrating with SAML 2.0, use the following request attributes in your request with Personalausweis:
| Attribute | Example | Description |
|---|---|---|
idpId | Subject ID that represents the 'pseudonym'. Use this to identify users across authentication sessions. | |
firstName | Hans-Günther | Given name(s) of the end-user. |
lastName | von Drebenbusch-Dalgoßen | Last name of the end-user. |
name | Hans-Günther von Drebenbusch-Dalgoßen | Full name, including first and last name, of the end-user. |
dateOfBirth | 1946-01-25 | Date of birth of the end-user, represented as a string in YYYY-MM-DD date format. |
address | {"formatted": "WEG NR. 12 8E, 22043, HAMBURG, D","street_address": "WEG NR. 12 8E","locality": "HAMBURG","postal_code": "22043","country": "D"}, | Postal address of the end-user. Formatted as JSON object containing the following fields:
|
nationality | D | Nationality of the end-user as specified on the ID document. |
placeOfBirth | BREMERHAVEN | Place of birth of the end-user. |
academicTitle | Dr.eh.Dr. | Academic title. Available only if the end-user holds a doctoral degree. |
documentType | PASSPORT | ID document type. Available values:
|
issuingState | D | D for Germany (Deutschland). |
dateOfExpiry | 2027-04-05 | Document expiry date, represented as a string in YYYY-MM-DD date format. |
SAML 2.0 service provider metadata document
The example below shows a Service Provider (SP) metadata document to connect to Personalausweis and request the attributes: firstName, lastName, name, nationality, dateOfBirth, placeOfBirth, academicTitle, documentType, issuingState, dateOfExpiry and address.
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_45f42f65-39f9-4250-898e-f6297cb3f8ce" entityID="SAML Example SP">
<md:SPSSODescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate><SP_PUBLIC_SIGNING_CERTIFICATE_USED_FOR_SIGNING_REQUESTS></ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://<SP_METADATA_SERVER_DOMAIN>/callback" index="1" isDefault="false"/>
<md:AttributeConsumingService index="1" isDefault="false">
<md:ServiceName xml:lang="en" xmlns:xml="http://www.w3.org/XML/1998/namespace">All attributes</md:ServiceName>
<md:RequestedAttribute Name="firstName"/>
<md:RequestedAttribute Name="lastName"/>
<md:RequestedAttribute Name="name"/>
<md:RequestedAttribute Name="nationality"/>
<md:RequestedAttribute Name="dateOfBirth"/>
<md:RequestedAttribute Name="placeOfBirth"/>
<md:RequestedAttribute Name="academicTitle"/>
<md:RequestedAttribute Name="documentType"/>
<md:RequestedAttribute Name="issuingState"/>
<md:RequestedAttribute Name="dateOfExpiry"/>
<md:RequestedAttribute Name="address"/>
</md:AttributeConsumingService>
</md:SPSSODescriptor>
</md:EntityDescriptor>
SAML 2.0 request example
SAML 2.0 request example:
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
AttributeConsumingServiceIndex="1"
Destination="https://<YOUR_SIGNICAT_DOMAIN>/auth/saml/login"
ID="d2d2ae0656604b839d9bf36edca452a7"
IssueInstant="2024-06-12T07:20:50.265Z"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Version="2.0"
>
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">SAML Example SP</saml:Issuer>
</samlp:AuthnRequest>
SAML 2.0 response example
SAML 2.0 response example:
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
Destination="https://<SP_METADATA_SERVER_DOMAIN>/acs"
ID="_f6298fea54d5f4090c0ac4ebd3247de7"
InResponseTo="d2d2ae0656604b839d9bf36edca452a7"
IssueInstant="2024-06-12T07:21:05.314Z"
Version="2.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
>
<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://<YOUR_SIGNICAT_DOMAIN>/auth/saml</saml2:Issuer>
<saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</saml2p:Status>
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
ID="_e7a8306e71d2dd628fdfb66fa05743bb"
IssueInstant="2024-06-12T07:21:05.321Z"
Version="2.0"
>
<saml2:Issuer>https://<YOUR_SIGNICAT_DOMAIN>/auth/saml</saml2:Issuer>
<saml2:Subject>
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
NameQualifier="https://eid-epan1-ref.eid-service.de"
>X6hYgXvTvNMf27-mC0cYzOUb4HBWR1feCSh5Ul7KiNQ=</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml2:SubjectConfirmationData InResponseTo="d2d2ae0656604b839d9bf36edca452a7"
NotOnOrAfter="2024-06-12T07:23:05.321Z"
Recipient="https://<SP_METADATA_SERVER_DOMAIN>/acs"
/>
</saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:Conditions NotBefore="2024-06-12T07:21:00.321Z"
NotOnOrAfter="2024-06-12T07:23:05.321Z"
>
<saml2:AudienceRestriction>
<saml2:Audience>SAML Example SP</saml2:Audience>
</saml2:AudienceRestriction>
</saml2:Conditions>
<saml2:AttributeStatement>
<saml2:Attribute Name="firstName">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>Hans-Günther</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="lastName">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>von Drebenbusch-Dalgoßen</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="name">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>Hans-Günther von Drebenbusch-Dalgoßen</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="dateOfBirth">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>1946-01-25</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="nationality">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>D</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="placeOfBirth">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>BREMERHAVEN</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="address.fullAddress">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>WEG NR. 12 8E, 22043, HAMBURG, D</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="address.street">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>WEG NR. 12 8E</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="address.city">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>HAMBURG</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="address.postalCode">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>22043</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="address.country">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>D</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="academicTitle">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>Dr.eh.Dr.</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="documentType">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>ID</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="issuingState">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>D</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="dateOfExpiry">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>2027-04-05</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="idpId">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xsd:string"
>5D6C804FC44BEEDA94265B8CFC1B5D120DC6EBE949D8690DAF515D0D4163066F</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
<saml2:AuthnStatement AuthnInstant="2024-06-12T07:21:05.321Z"
SessionIndex="0f45bba4-c605-4278-8278-b9aeb802b6a3"
>
<saml2:AuthnContext>
<saml2:AuthnContextClassRef>high</saml2:AuthnContextClassRef>
<saml2:AuthenticatingAuthority>https://eid-epan1-ref.eid-service.de</saml2:AuthenticatingAuthority>
</saml2:AuthnContext>
</saml2:AuthnStatement>
</saml2:Assertion>
</saml2p:Response>