Getting started¶

This page will help you get started using BankID with biometrics (BIB) in your product.

Before you can start integrating, you'll need to know which integration flow(s) to use. BankID with biometrics has three main integration flows, and depending on your product you'll normally want to pick one of them:

Authorization Code Flow
Authorization Code Flow with upfront permissions
Client Initiated Backchannel Authentication (CIBA) Flow

Expand the below tip if you need help determining what kind of integration to use for your product.

Tip: Picking an integration flow

This diagram should help you determine what kind of integration you're looking for.

flowchart LR
    classDef flow fill:#D6F8D6,stroke:#333,color:#000;
    classDef modifier fill:#FFEEBE,stroke:#ccc,color:#000;

    Start(["Start"])
    Constrained{"Constrained user\nenvironment?\n\n(e.g. smart TV,\ngaming console,\n3D Secure payment)"}

    ConfigurablePermissions{"<i>Configurable*</i>\npermissions?"}

    MobileApp{"Authenticating from\nan iOS app?"}

    IACF["Authorization Code"]
    EACF["Authorization Code\nwith upfront\npermission"]
    EACF_APPCALLBACK["Use\napp_callback_uri\n(in public preview)"]
    EACF_NO_APPCALLBACK["Do not use\napp_callback_uri"]

    CIBA["Client Initiated\nBackchannel Authentication"]

    Start --> Constrained
    Constrained  --> |Yes| CIBA:::flow
    Constrained  --> |No| ConfigurablePermissions 

    ConfigurablePermissions --> |Yes| EACF:::flow
    ConfigurablePermissions --> |No| IACF:::flow

    EACF --> MobileApp

    MobileApp --> |Yes| EACF_APPCALLBACK:::modifier
    MobileApp --> |No| EACF_NO_APPCALLBACK:::modifier

*configurable means being able to use a permission type that is not the standard authentication/login (authentication.v1).

Let's look at a brief overview of each flow and what steps to take to get started.

Authorization Code Flow¶

The Authorization Code Flow is the most common integration flow, which offers authentication (permission type authentication.v1) using BankID with biometrics. The user sees the merchant name associated with your BankID OIDC client as the context for the login.

How to implement the Authorization Code Flow depends upon whether or not you already have a BankID OIDC integration.

With an existing BankID OIDC integration¶

If you already have an integration with BankID OIDC, all you need to do is:

Ensure you have a BankID agreement that includes BankID with biometrics. All agreements after 1. September 2022 include BankID with biometrics by default. If your agreement is older than this, you'll need to contact your BankID partner to get BankID with biometrics enabled.
Once you have an agreement including BankID with biometrics, you can set acr_values to urn:bankid:bis in the request parameter for the authorization endpoint every time you initiate a login.
Verify that the acr claim of the returned ID token includes LOA=3, which represents Level of Assurance 3, indicating the trust level of the authentication.

You're done 🎉

That's it, you're up and running with BankID with biometrics using your existing BankID OIDC integration! Users will now be able to authenticate with your product using BankID with biometrics.

Without an existing BankID OIDC integration¶

If you do not already have an integration with BankID OIDC, you'll need to follow the steps described on the Authorization Code page.

Authorization Code Flow with upfront permissions¶

The Authorization Code Flow with upfront permissions has the same user experience as the Authorization Code Flow, but allows using other permission types than authentication.v1.

Refer to the Authorization Code Flow page on how to integrate this flow.

Client Initiated Backchannel Authentication¶

The Client Initiated Backchannel Authentication Flow is different from the other flows in that it is the OIDC client, not the user, who initiates the authentication.

In BankID with biometrics, initiating a CIBA flow will normally result in the user receiving a push notification on their mobile device, and the authentication will take place in the supported app. This is advantageous if you'd like to initiate an authentication flow when the user is in environment with limited capabilities, such as on a Smart TV, gaming console or in a 3D Secure payment iframe, and have the user finish the authentication in a more capable environment.

Warning

There is no fallback mechanism in the CIBA flow.

As the above warning states, there is no fallback mechanism in the CIBA flow. This is because the CIBA flow is based on sending a push notification, and this push notification cannot be sent unless the user has installed a supported app and enabled BankID with biometrics. Unless this notification is sent, we have nowhere to fall back from.

In other words, you should know whether the user has enabled BankID with biometrics before attempting to initiate a backchannel authentication.

Checking if the user has enabled BankID with biometrics

Before initiating a CIBA flow, you should always check whether the user has enabled BankID with biometrics. This can be done using the /user-exists endpoint documented in the the Permission API spec.

Handling failed CIBA flows

Even if the user has enabled BankID with biometrics at some point, they might have uninstalled the app since, or removed the screen lock from their phone causing the WebAuthn private key to be deleted, rendering the device unable to complete a WebAuthn authentication.

Always have a backup strategy in case the initiation or authentication fails.

Refer to the Client Initiated Backchannel Authentication (CIBA) Flow page on how to integrate.

Code Examples¶

Take a look at our integration examples. They serve as a good starting point for your journey with BankID OIDC and BankID with biometrics. The provided examples cover various authentication flows and are available in multiple programming languages and frameworks.

How to test¶

See Testing for details how to test your integration.

It is also possible to test a BankID with biometrics authentication without setting up an integration first. This is done register a test user and initiate a login from the BankID with biometrics' tester. See how to register a test user for details.