Implement with OIDC

This guide shows you how to implement a connection with OpenID Connect (OIDC) for Czech Bank iD.

Before you begin

Before starting your OIDC integration with Czech Bank iD, make sure to have set up Czech Bank iD.

Add an OIDC client

An OIDC client allows your application to authenticate users with Czech Bank iD as a provider using standardised, secure OAuth 2.0 protocols.

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

In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients.
Select Create/Add client.
Enter a name for the client.
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.
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.

In the Scope field, enter the scopes you want for this client. openid is mandatory. Find out what scopes are supported in the Attributes reference.
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.
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:

In the menu for the client, go to the Secrets tab and select Add secret.
Enter a name for your client secret and select Create.
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

An authentication flow with OIDC typically involves the following steps:

You build the authentication request with the appropriate parameters.
Redirect the user to the authorization endpoint.
User authenticates with Czech Bank iD.
After successful authentication, the provider sends the user to the Redirect URI.
At the same time, your application receives the authorization code and the state.
Your backend exchanges the code for tokens: ID token, access token and refresh token (optional).
You validate the ID token before establishing a session.
Optionally, you retrieve additional information through the userInfo endpoint.

Below, you find instructions to complete an authentication flow with Czech Bank iD.

Build the authentication request

To begin an authentication flow, design your application to build an authentication URI which points to the authorization (authorize) endpoint. Then, you direct the end-user to the authentication URI in a browser, where the end-user can log in by choosing their bank for authentication with Czech Bank iD.

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%20nin%20address%20email%20phone%20gender%20date-of-birth%20eighteen-or-older%20nationality%20marital-status%20idp-id%20name%20bankid-cz-extra%20bankid-cz-idcards%20bankid-cz-title%20bankid-cz-bank
    &acr_values=idp:bankid-cz
    &prompt=login
    &nonce=1599046102647-dv4

You can find the base URL of your authorization_endpoint in the discovery document of your OIDC client available in the Signicat Dashboard under "Well-Known URL for client".

The above example uses the following parameters:

client_id: The OIDC client you created in the Signicat Dashboard.
response_type: The grant type (flow). For the authorization code flow, use code.
redirect_uri: The Redirect URI where to send the end-user after authentication.
state A random string to prevent cross-site request forgery (CSRF). Verify it when the user is redirected back to your app.
scope: A space-delimited list of scopes to indicate what personal data to request. Find out what scopes are supported with Czech Bank iD in the Attributes reference.
acr_values=idp:bankid-cz: Optional. ACR values specifies aspects such as assurance level or identity provider. In this example, idp:bankid-cz forces authentication with Czech Bank iD.
prompt=login: Optional. Forces the login screen to be shown, even if the user is already authenticated.
nonce: A cryptographically random string used to associate the request with the returned ID token. Helps prevent replay attacks and must be validated after login.

You can find additional authentication 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.

AML verification

Czech Bank iD offers flows for compliance with Anti-Money Laundering (AML) laws and regulations. Learn more about the data attributes for AML in the Attributes reference overview page.

End-user authentication

To authenticate with Czech Bank iD, end-users must authenticate with their bank and consent to share their personal data with you in the confirmation screen.

You can view an example of end-user authentication flow with Czech Bank iD in the Test it out page.

After successful authentication, the authorization server redirects the end-user back to the redirect_uri. The response message contains the authorization code and state in the query string. This may vary depending on the authentication flow.

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

Server response

Example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>?
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
&scope=openid%20profile%20nin%20address%20email%20phone%20gender%20date-of-birth%20eighteen-or-older%20nationality%20marital-status%20idp-id%20name%20bankid-cz-extra%20bankid-cz-idcards%20bankid-cz-title%20bankid-cz-bank
&state=1599045135410-jFe
&session_state=PJl854GXgavBXj1-JRlfSvwkh9hpraImao2fvYDTDwE.A6AB53401320A51C5D61F205FE29468B
&iss=https%3A%2F%2F<YOUR_SIGNICAT_DOMAIN>%2Fauth%2Fopen

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

The code holds 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 can now exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the token endpoint of the authorization server.

Example token request

POST /auth/open/connect/token HTTP/1.1
Host: <YOUR_SIGNICAT_DOMAIN>
Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==
Content-Type: application/x-www-form-urlencoded

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.

What is a JWT?

A JSON Web Token (JWT) consists of three parts separated by dots (.), which correspond to:

Header
Payload
Signature

A JWT typically looks like:

xxxxx.yyyyy.zzzzz

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

{
  "iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
  "sub": "987654321",
  "aud": "<OIDC_CLIENT_ID>",
  "nbf": 1712237928,
  "exp": 1712256000,
  "iat": 1712252400,
  "nonce": "abc456",
  "idp_id": "bankid-cz",
  "name": "Josef Dvořák",
  "given_name": "Josef",
  "family_name": "Dvořák",
  "middle_name": "Karel",
  "birthdate": "1990-05-20",
  "gender": "male",
  "place_of_birth": "Brno",
  "country_of_birth": "CZ",
  "nationality": "CZ",
  "address": {
    "street_address": "Náměstí Republiky 5",
    "postal_code": "11000",
    "locality": "Praha",
    "country": "CZ"
  },
  "nin": {
    "value": "8505051234",
    "issuingCountry": "CZ",
    "type": "PERSON"
  },
  "phone_number": "+420601234567",
  "email": "josef.dvorak@example.cz",
  "eighteen_or_older": true,
  "marital_status": "married",
  "bankid_cz_title_prefix": "Ing.",
  "bankid_cz_title_suffix": "Ph.D.",
  "bankid_cz_pep": false,
  "bankid_cz_limited_legal_capacity": false,
  "bankid_cz_payment_accounts": [
    {
      "IBAN": "CZ6508000000000000123456"
    }
  ],
  "bankid_cz_updated_at": "2024-03-15T10:15:30Z",
  "bankid_cz_id_card": {
    "type": "ID",
    "number": "98765432"
  }
}

ID Token

By default, the ID Token returns only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token, go to your OIDC client configuration in the Signicat Dashboard and edit the ID Token User data in the Advanced > Security tab.

UserInfo response

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

Example response UserInfo endpoint

{
  "name": "Josef Dvořák",
  "given_name": "Josef",
  "family_name": "Dvořák",
  "middle_name": "Karel",
  "birthdate": "1990-05-20",
  "gender": "male",
  "place_of_birth": "Brno",
  "country_of_birth": "CZ",
  "nationality": "CZ",
  "address": {
    "street_address": "Náměstí Republiky 5",
    "postal_code": "11000",
    "locality": "Praha",
    "country": "CZ"
  },
  "nin": {
    "value": "8505051234",
    "issuingCountry": "CZ",
    "type": "PERSON"
  },
  "phone_number": "+420601234567",
  "email": "josef.dvorak@example.cz",
  "eighteen_or_older": true,
  "marital_status": "married",
  "bankid_cz_title_prefix": "Ing.",
  "bankid_cz_title_suffix": "Ph.D.",
  "bankid_cz_pep": false,
  "bankid_cz_limited_legal_capacity": false,
  "bankid_cz_payment_accounts": [
    {
      "IBAN": "CZ6508000000000000123456"
    }
  ],
  "bankid_cz_updated_at": "2024-03-15T10:15:30Z",
  "bankid_cz_id_card": {
    "type": "ID",
    "number": "98765432"
  }
}

Success!

You have now completed an authentication flow with Czech Bank iD.

UX considerations

To use the Czech Bank iD buttons, texts, logos and other graphic elements correctly in your applications, you need to follow the UX style guide at https://ux.bankid.cz/.