Skip to main content

Implement with OIDC

This guide shows you how to implement a connection with OpenID Connect (OIDC) for ID Austria.

Before you begin

Before starting your OIDC integration, ensure to complete the steps to Configure ID Austria services.

Add an OIDC client​

An OIDC client allows your application to authenticate users with ID Austria 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:

  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. Find out what scopes are supported in the Attributes reference.
    OIDC scope configuration

    Scopes encode what personal information you request from your end-users.

    When configuring scopes for your OIDC client, note that they are limited by the settings in your ID Austria service provider. The scopes you request must already be present and approved in your service provider's configuration in Mein USP.

  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 select Add secret.
  2. Enter a name for your client secret and select 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

We strongly recommend using PKCE, even when you are using a client secret. 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).

Learn more about PKCE in the eID and Wallet Hub documentation.

OIDC authentication flow​

An authentication flow with OIDC typically involves the following steps:

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

Below, you find instructions to complete an authentication flow with ID Austria.

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 ID Austria.

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%20age-verification%20nationality%20marital-status%20idp-id%20idaustria-extra
    &acr_values=idp:idaustria%20idaustria_service_id:<YOUR_SERVICE_UUID>
    &prompt=login
    &nonce=1599046102647-dv4
    &code_challenge_method=S256
    &code_challenge=Qr_Nb4Ge6pPGzGW5pMThE8QSHzhP432v4NfIgeNFylI
Authorisation endpoint

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 ID Austria in the Attributes reference.
  • acr_values: Optional. Authentication Context Class Reference (ACR) values determine the type or level of authentication required. For ID Austria, the following values are supported:
    • idp:idaustria: Routes the end-user to ID Austria thus skipping the eID selection screen. This applies when you have multiple eIDs active in the Signicat Dashboard and want to automatically route end-users to the ID Austria login screen.
    • idaustria_service_id:<YOUR_SERVICE_UUID>: Specifies the unique identifier (UUID) of the ID Austria service to use for this specific authentication request. This allows you to specify a different service on a per-request basis without changing the default configuration in your Signicat Dashboard.
  • 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 you configured for your OIDC client in the Dashboard.

End-user authentication​

To authenticate with ID Austria, end-users must authenticate with their ID Austria credentials and consent to share their personal data with you in the confirmation screen.

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

Test an authentication​

To test an authentication flow during the implementation phase, you can use the test user credentials available in the Try it out page.

Server response​

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.

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

curl -Ss -X POST \
https://example.sandbox.signicat.dev/auth/open/connect/token \
-H 'Authorization: Basic ZGV2LWRyYWItYW5nbGUtNDI2OjR3bGhKRFlZQUhXeVBaRGt2SGh2dXJDM2FFUXBMa0Nxb2FkMVJnU1pDRGt1czlkVA==' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&redirect_uri=https%3A%2F%2Foauth.tools%2Fcallback%2Fcode&code=19BC17FECFFA7DE2E543BF4512CD07318DEFC7095FFECADC1621BD7AAE75DC6D-1&code_verifier=FTHs8sVZveTGQ4SYsYARZ9u269LTseRxIIC2UdvYp2elJXXhJAgc0hW7INIAmyAD'

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%20idaustria-extra%20idaustria-idcards%20idaustria-title%20idaustria-bank
&state=1599045135410-jFe
&session_state=PJl854GXgavBXj1-JRlfSvwkh9hpraImao2fvYDTDwE.A6AB53401320A51C5D61F205FE29468B
&iss=https%3A%2F%2F<YOUR_SIGNICAT_DOMAIN>%2Fauth%2Fopen

You 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​

You 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 ID Austria 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": "idaustria",
  "name":"XXXĤáčęk Elfriede Hàčêk XXXMûstérfřău",
  "family_name":"XXXMûstérfřău",
  "given_name":"XXXĤáčęk Elfriede Hàčêk",
  "picture":"/9j/4AAQSGrrP6...XLyEo//2Q==",
  "gender":"W",
  "birthdate":"1995-02-02",
  "nin":"XERSB+9110037664968:thJvI0tmiqSk60SErBLXmsXiJVU=",
  "nin_type":"PERSON",
  "idp_issuer":"https://idp.ref.id-austria.gv.at",
  "transaction_id":"ebfeac3e-149d-b847-b16d-534f0dd60157",
  "sandbox":true,
  "acr":"high"
}
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":"XXXĤáčęk Elfriede Hàčêk XXXMûstérfřău",
  "family_name":"XXXMûstérfřău",
  "given_name":"XXXĤáčęk Elfriede Hàčêk",
  "picture":"/9j/4AAQSGrrP6...XLyEo//2Q==",
  "gender":"W",
  "birthdate":"1995-02-02",
  "nin":"XERSB+9110037664968:thJvI0tmiqSk60SErBLXmsXiJVU=",
  "nin_type":"PERSON",
  "address":
  {
      "formatted": "Testgasse, 1a-2b, Testort A, 0088",
      "street_address": "Testgasse 1a-2b",
      "street": "Testgasse",
      "house_number": "1a-2b",
      "locality": "Testort A",
      "postal_code": "0088",
      "country": "AT"
  },
  "nationality": "[\"AUT\",\"DEU\",\"CHE\"]",
  "marital_status": "verheiratet",
  "idaustria_country_of_exhibition": "AT",
  "idaustria_authentication_level": "http://eidas.europa.eu/LoA/high",
  "idaustria_level": "urn:eidgvat:eid.status.full",
  "idaustria_type_of_identity": "http://eid.gv.at/eID/status/testidentity",
  "idaustria_bpk_area": "urn:publicid:gv.at:wbpk+XERSB+9110037664968",
  "idaustria_url_citizen_card_environment": "https://hs-abnahme.a-trust.at/securitylayer2",
  "idaustria_signature_certificate": "MIIFdj.../vw==",
  "idaustria_signature": "/9j/4AAQS...kZJRgABA",
  "idaustria_health_service_providers": "eyJn...9fX0=",
  "idaustria_current_photo_capture_date": "2024-02-03",
  "idaustria_reported_since": "2020-02-05",
}
Success!

You have now completed an authentication flow with ID Austria.

UX considerations​

To use the ID Austria buttons, badges, logos and other graphic elements correctly in your applications, you can download the ID Austria logo package and guide. For more information, visit the ID Austria website.

Next steps​

Continue your journey with more ID Austria guides:

Attributes reference
Scopes and claims for ID Austria 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