Skip to main content

Integration with OIDC

This page shows how to integrate with Personalausweis using OpenID Connect (OIDC) as an authentication protocol.

Before you begin​

Before starting your OIDC integration with Personalausweis, make sure you have configured your Signicat account.

Add an OIDC client​

When you register an OIDC client application, you receive a client ID. To do this:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients.
  2. Select Create/Add client.
  3. Enter a name for the client.
  4. In Primary grant type, select the grant type (authentication flow) to use for this client.
    Choosing a grant type

    The Authorization Code flow is recommended for most cases. Learn more about supported flows in the generic OIDC implementation guide and the OAuth 2.0 specification.

  5. In the Redirect URI field, enter the URL where to redirect the end-user after authentication. You can always edit and add more URIs later.
  1. In the Scope field, enter the scopes you want for this client. openid is mandatory.
    Scopes and personal data

    Scopes encode what personal information you request from your end-users. Your billing bundle with Signicat determines what scopes are available. Learn more in the Attributes reference.

  2. Select Create to create the OIDC client.

Add a client secret​

Depending on the type of your application, you may want to add a client secret. To do this:

  1. In the menu for the client, go to the Secrets tab and click Add secret.
  2. Enter a name for your client secret and click Create.
  3. Copy your new client secret and store it safely.
Important

Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one.

PKCE

Note that if you intend to use the OIDC client in a frontend flow, then you must always use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the eID and Wallet Hub documentation.

OIDC authentication flow​

In OIDC, an application first needs to specify which permissions to request, then send the end-user to a browser to get their permission. After the end-user approves the authentication request and gets redirected to your website, your application receives back an authorisation code. You exchange the authorisations code for an access token and an ID token, where you can find the end-user personal information.

Build the authentication request​

To trigger an authentication flow, design your application to build an authentication URI. Then, direct the end-user to the authentication URI in a browser where they can start an authentication flow with Personalausweis.

The authorize endpoint is the place where to start the authentication flow with the end-user. It directs the end-user to the authorisation server, where the end-user logs in with their Personalausweis account.

Your application should send an HTTPS GET request with the appropriate URI parameters. Here is an example of an authentication URI with OIDC:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
    &client_id=<OIDC_CLIENT_ID>
    &response_type=<GRANT_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

The base URL of your authorization_endpoint is available in the discovery document of your OIDC client which you can find under "Well-Known URL for client" in your OIDC client configuration in the Signicat Dashboard.

Note the following query parameters:

  • client_id: The client ID of your OIDC application.
  • response_type: Specifies the desired grant type for the OIDC flow.
  • redirect_uri: The URI where to redirect the user after they approve the request at the end of the OIDC flow. This must be an absolute URI using the HTTPS protocol.
  • state: A randomly generated string used to maintain the state between the request and the callback. It helps mitigate CSRF attacks by ensuring the returned value matches the one sent in the initial request.
  • scope: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow.
  • acr_values: (Optional) A space-separated list of key-value pairs to customise the authentication flow. See the acr_values reference for more details. In the request:
    • idp:npa: Directs the end-user to Personalausweis, skipping the eIDs selection screen. This prevents users from viewing and choosing other eIDs that may be active in your account.

You can find additional authorization request query parameters in the OIDC specification.

Important

The values you specify in the query parameters must match the values in the configuration of your OIDC client in the Dashboard.

End-user authentication​

To authenticate with Personalausweis, your end-users must consent to share their data with you through the Personalausweis confirmation screen.

The process flow involves the following steps:

  1. On your website/application, the end-user clicks on a button to authenticate with Personalausweis. Your application sends an authorisation request to start authentication with Personalausweis, as described in the previous section.
  2. (Optional) The end-user views the ID provider selection screen where they can choose Personalausweis among the eIDs that you support. You can skip this screen by specifying the Personalausweis in the acr_values of the OIDC request.
  3. The end-user is redirected to a screen with a message that explains that they need to open the AusweisApp. If the app is running in the background, then Signicat sends a push to bring the AusweisApp to the foreground.
  4. The AusweisApp displays the name of the provider and the attributes requested for authentication.
  5. If the end-user consents, they select "Proceed to PIN entry".
  6. The end-user must place their identity card on a card reader, either a USB-connected card reader or a paired NFC-enabled smartphone.
  7. The AusweisApp requests the 6-digit PIN code.
  8. Now, the AusweisApp reads the data from the card, therefore performing the authentication.
AusweisApp displays "Signicat GmbH" as provider

In the AusweisApp, the identity provider name appears as "Signicat GmbH". This is because Signicat is the accredited organisation responsible for authentication. We recommend informing your end-users beforehand.

By default, the "Transactional information" field in the AusweisApp displays the name of your organisation, as registered in the Dashboard. To change the name in the AusweisApp, you need to contact us by creating a support ticket in the Signicat Dashboard.

After completion, the authorization server redirects the end-user back to the redirect_uri specified by your OIDC application, adding a code and state to the query string in the server response.

Now, you can retrieve the end-user data by exchanging the authorisation code in the server response for an access token that includes the ID token, where the data is. The steps are explained below.

Server response​

Here is an example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>?
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
&scope=openid%20profile%20idp-id%20address%20date-of-birth%20nationality%20npa-extra
&state=1713343316409-zie
&session_state=PJl854GXgavBXj1-JRlfSvwkh9hpraImao2fvYDTDwE.A6AB53401320A51C5D61F205FE29468B
&iss=https%3A%2F%2F<YOUR_ACCOUNT_DOMAIN>%2Fauth%2Fopen

Your application should check that the state in the redirect matches the original state in the authorization request to mitigate CSRF and other related attacks.

The code is the authorization code generated by the authorization server. You use this code in the request to the token endpoint to obtain an access token and the ID token.

Obtain the access token​

Your application should exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the authorization server token endpoint.

Example token request

curl -X POST https://<YOUR_ACCOUNT_DOMAIN>/auth/open/connect/token -H 'Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=<GRANT_TYPE_CODE>&redirect_uri=<REDIRECT_URI>&code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1&code_verifier=oQDZ3uPQn...W7U'

Example token response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ ... Klmmm.emo ... NzBKFf.gaW8g ... Mzn5"
    "token_type": "Bearer",
    "refresh_token": "eyJ ... zcuUk.mow ... 7HmKmn.ggW8h ... Gz4g",
    "expires_in": 3600,
    "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg"
}

ID token​

An ID token is a JWT that looks like eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA.

The decoded payload (data) part of the ID token for Personalausweis would then look like:

{
  "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"
  },
  "nationality": "D",
  "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"
}
ID Token

Note that ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token, edit the ID Token User data in the Advanced > Security tab of your OIDC client configuration in the Signicat Dashboard.

UserInfo response​

The response examples below show user information retrieved from the UserInfo endpoint.

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"
  },
  "nationality": "D",
  "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"
}
Success!

You have now completed an identity verification flow with Personalausweis.

Next steps​

Continue your journey with more Personalausweis guides:

Attributes reference
Scopes and claims for Personalausweis with OIDC

Dive deeper into OIDC and improve your application with advanced security features:

Advanced OIDC implementation
Learn about available flows, endpoints, claims, key rotation, security, error codes and more
Advanced security considerations
Learn about advanced security measures like PKCE and encryption
On this page