Overview#

This guide will help you get started integrating ID-Card into your application.

ID-Card uses OpenID Connect protocol for authentication, it builds on OAuth 2.0 authorization framework. This section describes how to authorize your application, and interact with our ID-Card API's.

Flow#

The flow is triggered by a user or customer presenting a QR-code through BankID App. The consumer that wants to validate the user's ID, from here reference to as the Merchant, reads the QR-code and gets a sessionId. This sessionId is one-time use, and valid for 30 seconds. The merchant then authorizes against BankID OIDC to get a access token. This token is then used, together with sessionId, in requests to ID-Card API to retrieve data about the user.

sequenceDiagram
    actor u as User/Customer
    participant m as Merchant backend application
    participant b as BankID OIDC
    participant v as ID-Card API    

    u->>m : User presents a QR-code
    m->>m : Read QR-code and retrieve the embedded sessionId
    m->> b: Request BankID OIDC for a token
    b-->> m: Obtain access token
    m->> v: Request session detail with BankID access token and sessionId
    v -->> m: Obtain session detail

Implementation Steps:#

1. Get a SessionId#

1. 1
   Scan the QR Code

   Use a QR code scanner or an optical reader to read the QR code.

2. 2
   Extract the string

   Extract the string contained in the QR code.

3. 3
   Verify the string

   SessionId should look something like this:
   "VisLeg-9fa44f41-ce68-4f03-bc1a-498b00cf5fec"
   Verify that the GUID starts with "VisLeg". If not, then discard it.

Example of a genuine QR code

2. Authentication Request#

The authentication should be done backend-to-backend, not in merchant frontend. The credentials will be provided after agreement. For more details on how to implement and code examples, see Authentication

3. Session Request#

In this step we are retrieving user data using SessionId from ID-Card API. The response will only return the data the merchant has a need for. If a merchant only needs Age of a user, the rest of the fields will be empty. This is controlled by the scope provided in the authentication request.

In this example we have the scope: identity_picture_age when we asked for the access token. So when we request user data, only documentPhoto and age are filled with values.

4. Testing the Integration#

To help with testing the integration, we have create an endpoint that returns QR-codes to be used for testing. They need to be generated and then used the same way as a regular flow.

For more details please see the test documentation and the postman-collection provided.