# 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 four 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
- Iframe Flow
- Client Initiated Backchannel Authentication (CIBA) Flow

> **Terms and conditions**
>
> The integration options available to you depend on the terms of your agreement. If you are unsure about your rights or permissions, please review the details in your agreement or contact us or your vendor for further guidance.

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.
>
> ```mermaid
> flowchart TB
>     classDef flow fill:#D6F8D6,stroke:#333,color:#000;
>     classDef modifier fill:#FFEEBE,stroke:#ccc,color:#000;
>
>     Start(["Start"])
>     RedirectsSupported{"Redirects<br/>supported?"}
>     IframeSupported{"iframe<br/>supported?"}
>
>     ConfigurablePermissions{"Configurable\* <br/>permissions?"}
>     MobileApp{"Authenticating from<br/>a native iOS app?"}
>     MobileAppNoWebview{"Direct app switch<br/>instead of<br/>embedding client?<br/>"}
>
>     IACF["Authorization code<br/> flow"]
>     IF["Iframe flow w/<br/>upfront permission"]
>     CIBA["CIBA flow w/<br/>upfront permission"]
>
>     UP["\+ upfront permission"]
>     UPAC["\+ upfront permission w/<br/>*app_callback_uri*"]
>     App2App["\+ native App2App<br/>flow"]
>
>     Start --> RedirectsSupported
>     RedirectsSupported ---> |Yes| IACF:::flow
>     RedirectsSupported --> |No| IframeSupported
>
>     IACF --> MobileApp
>
>     MobileApp --> |No| ConfigurablePermissions
>     MobileApp ---> |Yes| MobileAppNoWebview
>
>     MobileAppNoWebview --> | Yes| App2App:::flow
>     MobileAppNoWebview --> | No| UPAC:::modifier
>
>     ConfigurablePermissions --> |Yes| UP:::modifier
>
>     IframeSupported --> |Yes| IF:::flow
>     IframeSupported --> |No| CIBA:::flow
> ```
>
> \*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:

1. 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.
2. 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](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md) every time you initiate a login.
3. Verify that the `acr` claim of the returned [ID token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/id-token.md) 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](https://docs.stoe.no/bankid-with-biometrics/flows/code.md) 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](https://docs.stoe.no/bankid-with-biometrics/introduction.md#context-permission-types) than `authentication.v1`.

> **Rich Authorization Requests**
>
> As an alternative to registering permissions upfront via the Permissions API, you can use [Rich Authorization Requests (RAR)](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/authorization-details.md#authorization-details) to include permission details directly in the BankID OIDC authorization request. See the [RAR section](https://docs.stoe.no/bankid-with-biometrics/flows/code-flow-for-payments.md#alternative-rich-authorization-requests) for details.

Refer to the [Authorization Code Flow](https://docs.stoe.no/bankid-with-biometrics/flows/code-flow-for-payments.md) page on how to integrate this flow.

## Iframe Flow

The _Iframe Flow_ is designed for environments where redirects are not supported but iframes are, such as 3D Secure payment flows in ecommerce.
It allows the authentication to take place inside an iframe while using [upfront permissions](https://docs.stoe.no/bankid-with-biometrics/introduction.md#context-permission-types) to provide context for the user.

Refer to the [Iframe Flow](https://docs.stoe.no/bankid-with-biometrics/advanced-topics/iframes-support.md) page on how to integrate.

## 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.

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 BankID app.
This is advantageous if you'd like to initiate an authentication flow when the user is in an 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.

You need to know whether the user is registered with a sufficiently up-to-date BankID App before attempting to initiate a backchannel authentication.

> **Checking if the user can authenticate with CIBA**
>
> Before initiating a CIBA flow, you always need to check whether the user is registered with a sufficiently up-to-date BankID App to support app-required flows. This can be done using the `/user-exists` endpoint documented in the [Permission API spec](https://docs.stoe.no/bankid-with-biometrics/apis/permissions-api.md).

Refer to the [Client Initiated Backchannel Authentication (CIBA) Flow](https://docs.stoe.no/bankid-with-biometrics/flows/ciba.md) page on how to integrate.

## Code Examples

Take a look at our [integration examples](https://github.com/BankIDNorge/oidc-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](https://docs.stoe.no/bankid-with-biometrics/testing.md) 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](https://bidaletheiacurrent-tester.azurewebsites.net/).
See [how to register a test user](https://docs.stoe.no/bankid-with-biometrics/testing.md#register-a-test-user) for details.