Swedish BankID

BankID overview

Token example

Once a user has successfully authenticated with BankID, Idura Verify issues an ID token in JWT format to your application. The token contains a set of claims about the user and the authentication event itself. The examples below show the structure of the ID tokens issued for Swedish BankID logins.

Optional claims for native BankID signature verification

If your use case requires verifying the signature (which is not required, but possible), you have an option to request the evidence data as returned by the underlying eID provider. This can be done by adding scope=openid evidence (or login_hint=scope:evidence) to your authorize request.

With this configuration, the issued JWT will contain two additional claims: evidence and ocspResponse:

The full content of evidence and ocspResponse is omitted for brevity.

Avoiding excessively large JWT payload

When included in the payload, evidence and ocspResponse claims will significantly increase the size of the JWT token, potentially causing it to exceed the size limitations of an HTTP header. The bloated JWTs would thus become unusable as Bearer tokens for accessing APIs.

To address this concern, consider changing the response type in your authorization request to response_type=code id_token.

In this case, a more compact ID Token with only essential claims will be issued from the Token endpoint. The client can subsequently fetch all data about the user from the Userinfo endpoint.

_ With code id_token response type, the ID Token from the token endpoint will always be the same (and have nothing but a sub that is user-specific). In contrast, when using the response_type=code, the full ID Token is returned immediately in exchange for code._

Test users

Swedish BankID test users are created at the Demo Bank web site.

For more information on how to configure your device for test and setup test users, see BankID for test. Follow the steps outlined in the guide:

1. Download the app/program.
2. Configure the client for test.
3. Get a BankID for test. If you already have a fully-configured production or test BankID, you can use it to create a test user. Otherwise, see below on how to bootstrap the process.

Note that, as is also described on the website, using test BankID users does require a reconfiguration of the BankID application. This means it cannot be used for real BankID. So if you are Swedish and already have BankID on your phone, you may want to use a spare phone for testing.

Caller Authentication

facilitates user authentication during a phone call.

For details and integration instructions, see Caller Authentication with CIBA.

BankID Headless Authentication

Overview

Headless authentication is designed for flows where you want maximum control over how user interacts with same device and QR flows for BankID.

For instance you could render the QR flow in your own website, or trigger app2app in your native app without having to open a browser

The underlying Headless flow

Idura Verify facilitates Swedish BankID headless authentication via the Headless flow.

Implementing BankID Headless Authentication

The Headless flow is only available to traditional server-based web applications (confidential clients) and requires client validation for authentication requests. We’ll use private key JWTs for authentication in the example below. An alternative (less secure) approach is to use client_secret for authentication.

1. HTTP POST request to the /headless/authorize endpoint:

# Replace `$client_assertion` with your JWT assertion
# Replace `YOUR_DOMAIN.idura.broker` with your Idura domain

HTTP POST https://YOUR_DOMAIN.idura.broker/headless/authorize
Content-Type: application/x-www-form-urlencoded

scope=openid
&end_user_ip=127.0.0.1
&acr_values=urn:grn:authn:se:bankid
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=$client_assertion

2. A successful response will look something like this:

{
  "headless_req_id" : "3857f8ff-21b9-48ae-a732-a3bd8128a7ae",
  "expires_in" : 120,
  "acr_data": {
    "qrData": "bankid.5367b735-a3f9-47d9-aafc-6d2ad5a14901.0.425c66c472e756fc6a070b86eef1adb4fac0a2714d828c902afa77a5b15e8590",
    "autoStartToken": "d2c96ea2-f8d9-4e9f-8d39-4f2e88e10e1c"
  }
}

3. Poll the token endpoint (/oauth2/token) to get a response with an ID token. The headless_req_id is used to construct a poll request on the token endpoint:

# Replace `HEADLESS_REQ_ID` with the id returned by authentication response
# Replace `$client_assertion` with your JWT assertion

HTTP POST https://YOUR_DOMAIN.idura.broker/oauth2/token
Content-Type: application/x-www-form-urlencoded

headless_req_id=HEADLESS_REQ_ID
&grant_type=urn:urn:params:grant-type:headless
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=$client_assertion

Polling Frequency: Bear in mind, that the authentication process requires interacting multiple times with the end-user, so the identification process could take some time. Consequently, the token endpoint should be polled every 5 seconds.

4. The result of a poll request will depend on the state of the process:

On successful user identification, a successful token response is returned, e.g.:

{
  token_type: 'Bearer',
  expires_in: '120',
  id_token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjgyN0Q5QTNFOTg2MTY0OTVBQzZGRTE3MUFFNkRBM0IzQ0ExNDE5MjEifQ.eyJpc3MiOiJodHRwczovL25hdGFsaWEtZGV2LXRlc3QuY3JpaXB0by5pbyIsImF1ZCI6InVybjpjaWJhIiwiaWRlbnRpdHlzY2hlbWUiOiJzZWJhbmtpZCIsImF1dGhlbnRpY2F0aW9udHlwZSI6InVybjpncm46YXV0aG46c2U6YmFua2lkIiwiYXV0aGVudGljYXRpb25tZXRob2QiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpTb2Z0d2FyZVBLSSIsImF1dGhlbnRpY2F0aW9uaW5zdGFudCI6IjIwMjQtMDUtMjJUMTA6NDE6NDEuMzYxWiIsIm5hbWVpZGVudGlmaWVyIjoiYmI5YzIzNjRkZmFlNDRmM2JjZmQ5OTkwNTNkOTRmOWUiLCJzdWIiOiJ7YmI5YzIzNjQtZGZhZS00NGYzLWJjZmQtOTk5MDUzZDk0ZjllfSIsInNlc3Npb25pbmRleCI6ImI2NWYxMWI2LWViYTctNDg4Mi05MDBhLTVmMmQ5M2EzOGRiYSIsInNzbiI6IjE5NjgwMjAyMDU3NSIsIm5hbWUiOiJUZXJuZSBQYXVsc2VuIiwiZ2l2ZW5uYW1lIjoiVGVybmUiLCJnaXZlbl9uYW1lIjoiVGVybmUiLCJzdXJuYW1lIjoiUGF1bHNlbiIsImZhbWlseV9uYW1lIjoiUGF1bHNlbiIsImlwYWRkcmVzcyI6IjE4NS4xNTcuMTM0LjEzNCIsImNvdW50cnkiOiJTRSIsImlhdCI6MTcxNjM3NDUwMSwibmJmIjoxNzE2Mzc0NTAxLCJleHAiOjE3MTYzNzU3MDF9.RVQnlukfoH597uXzE1Gays5DElGzAr8xgOmi7ZWppaL3QPGhV4vK2o6qLhxXg_-FKG9xCwHR6gEhnNzWA3W3B6Q2zJeQTYh9okUvTmmhAFIyDL7lEtfWVVKUKvauDisYVZDjAxJQS_1zbgPEi5I-UJ6_kvMGH-wC13MAD2bZGTGR2dR-ZevBUn7plOt0PKXrIZD3vwxDfebTMPQqX_9SNT5F7GLjCcpeVK-T5LOgmUMFcTAbHvNyklqP5ymRHsZLDw_ib4I7ZqODhR-3uISWo1NvG4Y84iBcqv50WRNlmMUm004LfPw1flM5DNsVyUWCqYW8m7eBEwLp5va-6OQG4w',
  access_token: 'cf1ce646-7fbe-4740-9c56-fe3f0891f6c6'
}

The user has not yet completed the authentication, acr_data.hintCode provides details as to how far they are in the process.:

HTTP/1.1 400 Bad Request
{
  "error": "authorization_pending",
  "error_description": "awaiting first user interaction",
  "acr_data": {
    "qrData": "bankid.5367b735-a3f9-47d9-aafc-6d2ad5a14901.0.425c66c472e756fc6a070b86eef1adb4fac0a2714d828c902afa77a5b15e8590",
    "hintCode": "...."
  }
}

The user did not acknowledge that the identification request warranted or canceled the request before identification was performed:

HTTP/1.1 400 Bad Request
{
  "error": "access_denied",
  "error_description": "user declined"
}

Signing text/markdown

Swedish BankID supports signing text and markdown.

Text signing is triggered by using the action and message parameters via login_hint.

• The action parameter must be set to sign
• The message parameter must be base64 encoded and at most 40,000 characters after base64 encoding.
• The message parameter supports markdown text.

Note: Signing produces very large JWTs that are not appropriate for authentication/Bearer header use

Text signing has a different eID cost than authentication. If you have questions, please contact sales.

Round-tripping data that is not visible to the end user

Swedish BankID allows you to send data along in both authentication and signature flows, which they will then embed in the evidence claim after a flow completes succesfully.

You can supply this value via a nonVisibleData parameter in the login_hint. The supplied value must be base64 encoded. Idura does not attempt to parse or validate the value, we only pass on what is given to the native provider API.

Ordering Swedish BankID

To start accepting real users with Swedish BankID, you must order a certificate that identifies your organization. You order it through the Idura dashboard.

Idura acts as a reseller for Swedbank, which means that your order goes through a simple approval process with Swedbank. The process is managed by Idura.

To order:

1. In the Idura dashboard, switch to the production environment.
2. Open the Swedish BankID provider page.
3. Fill out the order form. The form guides you through the required information.

After you submit, Idura reviews your order and forwards it to Swedbank for approval. Once approved, we install the certificate in your Idura tenant. Expect 8-15 working days from submission until BankID is enabled in production. The dashboard shows the status of your order.