# Understanding authentication methods (amr)

When a user authenticates with BankID with biometrics, the resulting ID token includes an [`amr`](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.2) (Authentication Methods Reference) claim. This claim tells you **how** the user authenticated -- for example, whether they used biometrics on their device, or fell back to BankID with a code device.

The `amr` claim is an array of strings. It can contain one or more of the values described below.

## Understanding the prefixes

The `amr` values use two distinct prefixes. Understanding the difference is key to interpreting the claim correctly.

**`bis-` (BankID with biometrics)** -- These values describe the biometric authentication layer. When you see `bis-mfa` and `bis-hwk`, the user completed a WebAuthn-based authentication using hardware-bound keys on their device.

**`bid-` (BankID NetCentric)** -- These values describe a _classic BankID_ authentication (code device or BankID app for OTP, plus password). They only appear when `bis-bid` is also present, meaning the user was redirected to BankID NetCentric during a [fallback](https://docs.stoe.no/bankid-with-biometrics/introduction.md#fallback) or [step-up](https://docs.stoe.no/bankid-with-biometrics/introduction.md#step-up).

## Core values

These values describe the BankID with biometrics layer:

| Value     | Meaning                                                                                                                                                                                                                                                    |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bis-mfa` | The user authenticated with **multiple factors** (e.g. device possession + biometrics).                                                                                                                                                                    |
| `bis-hwk` | The user authenticated using a **hardware-bound key** -- a private key stored in tamper-resistant hardware, such as the secure enclave on the user's phone.                                                                                                |
| `bis-bid` | The user was **redirected to BankID NetCentric** (classic BankID). This happens during [fallback](https://docs.stoe.no/bankid-with-biometrics/introduction.md#fallback) or [step-up](https://docs.stoe.no/bankid-with-biometrics/introduction.md#step-up). |

## Additional values for BankID NetCentric

When `bis-bid` is present, the following values provide more detail about **which BankID method** the user used:

| Value     | Meaning                                                                          |
| --------- | -------------------------------------------------------------------------------- |
| `bid-mfa` | The user completed BankID NetCentric using multiple factors.                     |
| `bid-otp` | The user used a **code device** (kodebrikke) to authenticate.                    |
| `bid-app` | The user used the **BankID app** as the OTP method (instead of a code device).   |
| `bid-pwd` | The user typed their **personal password** as part of the BankID authentication. |

## How to determine if biometrics was used

The most common question is: _"Did the user authenticate with biometrics?"_

The answer depends on which `bis-` values are present:

| Scenario                           | `amr` contains                                                 | Biometrics used?                                                                         |
| ---------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Biometric authentication           | `bis-mfa`, `bis-hwk` (without `bis-bid`)                       | **Yes**                                                                                  |
| Biometric authentication + step-up | `bis-mfa`, `bis-hwk`, `bis-bid`, plus `bid-*` values           | **Yes** (biometrics was used, and then a BankID step-up was also performed)              |
| Fallback to BankID                 | `bis-bid` plus `bid-*` values (without `bis-mfa` or `bis-hwk`) | **No** (the user did not use biometrics; they authenticated with classic BankID instead) |

**In short:** if `bis-mfa` and `bis-hwk` are present, biometrics was used. If only `bis-bid` is present (without `bis-mfa` / `bis-hwk`), biometrics was **not** used.

> **The `bid-*` values do not tell you about biometrics**
>
> Values like `bid-app` and `bid-pwd` describe which **classic BankID** method was used (BankID app or code device for OTP, password). They do not indicate whether biometrics was or wasn't used -- that is determined solely by the `bis-mfa` and `bis-hwk` values. Even if you see `bid-app`, this refers to the BankID app as an OTP method in classic BankID, not to biometric authentication.

## Common examples

Below are examples of the `amr` claim you can expect in typical scenarios.

> **Do not rely on order or a fixed set of values**
>
> The order of values in the `amr` array is not guaranteed and may change. New values may also be added in the future. When implementing logic based on `amr`, always check for the **presence** of specific values in the array rather than comparing against a hardcoded list or expecting a particular order.

### Biometric authentication

The user authenticates using biometrics on their device. No fallback or step-up occurs.

```json
{
  "amr": ["bis-mfa", "bis-hwk"]
}
```

### Fallback to BankID with code device

The user has not activated BankID with biometrics, so authentication [falls back](https://docs.stoe.no/bankid-with-biometrics/introduction.md#fallback) to BankID NetCentric. The user authenticates with their code device and password.

```json
{
  "amr": ["bis-bid", "bid-mfa", "bid-otp", "bid-pwd"]
}
```

Note that `bis-mfa` and `bis-hwk` are **not** present -- the biometric authentication did not take place.

### Fallback to BankID app

Same as above, but the user uses the BankID app for OTP instead of a code device. Password is still required.

```json
{
  "amr": ["bis-bid", "bid-mfa", "bid-app", "bid-pwd"]
}
```

### Step-up with BankID

The user completes biometric authentication, and then a [step-up](https://docs.stoe.no/bankid-with-biometrics/introduction.md#step-up) to BankID NetCentric is also required. Both sets of values are present.

```json
{
  "amr": ["bis-mfa", "bis-hwk", "bis-bid", "bid-mfa", "bid-app", "bid-pwd"]
}
```

Here, `bis-mfa` and `bis-hwk` confirm that biometrics **was** used. The `bis-bid` and `bid-*` values tell you that a BankID NetCentric step-up was _also_ performed, using the BankID app for OTP.

> **Never use the `amr` claim as a security mechanism**
>
> A BankID with biometrics authentication with `bis-bid` is still `LOA=3` as reflected in the `acr` claim, regardless of the internal authentication mechanism(s) provided in the `amr` claim. The level of assurance does not change based on which method was used.

> **Legacy BankID OIDC v1**
>
> If you're using BankID OIDC and are still using [version 1](https://docs.stoe.no/bankid-oidc-provider/resources/api-versions.md) of the [BankID OIDC authorization endpoint](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md), the `amr` claim will always be a string equalling `"BIS"`, indicating the use of BankID Substantial authentication, but not providing any additional value.