For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Headless using CIBA

This guide shows you how to set up headless authentication for Norwegian BankID using the OIDC CIBA flow. With the headless flow, you can provide your own user interface within your app or website.

The headless flow supports the Safe Conversation (Call centre) authentication type.

What is the Safe Conversation feature?

For an introduction to the Safe Conversation feature, see the About page.

Prerequisites​

We assume you have done the initial preparations and received the needed access to the service, as described on the Initial preparations page.

Set up the OIDC client in the Dashboard​

1. Add an OIDC client​

For the complete documentation index, see llms.txt

To create an OIDC client for CIBA:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients.
  2. Select Create/Add client.
  3. Set the Primary grant type to "Ciba".
  4. Enter a name for the client.
  5. Add the OIDC scopes specific for your integration.

For more details about how to add/edit scopes, see the below section.

Configure scopes​

Available scopes for Norwegian BankID are: openid profile idp-id nin nbid-extra

For the complete documentation index, see llms.txt

openid is mandatory for all eIDs.

To be able to add scopes in your request, you first need to define them in the Signicat Dashboard:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
  2. Select Edit to view your client configuration.
  3. Open the Access tab.
  4. Select Add scope in the "Allowed scopes" section and select the scopes from the list.

For descriptions of these scopes, see the Attributes reference.

2. Add a client secret​

For the complete documentation index, see llms.txt

Depending on the type of your application, you may want to add a client secret. To do this:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
  2. Choose your client, go to the Secrets tab and select Add secret.
  3. Enter a name for your client secret and select Create.
  4. Copy your new client secret and store it safely.
Important

Save the client secret in a safe place, since you will only be able to view your client secret once, right after you create it. If you ever forget it or lose it, you have to create a new one.

PKCE

Note that if you intend to use the OIDC client in a frontend flow, then you must always use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the eID and Wallet Hub documentation.

Implement the OIDC authentication flow​

In a CIBA flow:

  • The client application initiates the authentication process by making a backchannel authentication request to the authorization server.
  • The server responds with a unique authentication reference.
  • The client can then receive real-time updates on the authentication status by polling the token endpoint.

1. Start the transaction​

This step describes how to start a transaction towards Norwegian BankID by calling the CIBA endpoint.

The call to the CIBA endpoint should be an HTTP POST request with content-type application/x-www-form-urlencoded. Make sure to authenticate the request with Basic authentication and operational parameters (login_hint, acr_values and scope):

The HTTP request should look something like this:

POST /auth/open/connect/ciba HTTP/1.1
Authorization: Basic ZGV2LW...CamdraTd2
Host: yourdomain.signicat.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 100

login_hint=nin%3A17029012345
&acr_values=idp%3Anbid%20flow%3Aheadless%20nbid_auth_type%3APHONE
&scope=openid%20profile%20nin%20nbid-extra%20idp-id

Scope

The values you specify in the scope parameter must match the values in the configuration of your OIDC client in the Dashboard.

You can find additional authorization request query parameters in the OIDC specification.

The acr_values and login_hint parameters are described in more detail below.

Control the BankID flow (acr_values and login_hint)​

You can control the Norwegian BankID flow by using the acr_values and login_hint parameters.

acr_values​

Available parameters and values are:

login_hint​

For the complete documentation index, see llms.txt

You can use login_hint to prefill end-user information to send to the identity provider, such as the national identification number of the end-user.

login_hint=nin:17029012345

For more details about login hints, see the eID Hub documentation.

Response example​

The response for the authentication request could look as follows (some headers omitted for brevity):

HTTP/1.1 200 OK
content-type: application/json; charset=UTF-8

{
"auth_req_id": "31920977-995e-254d-87d4-b323a6956552",
"expires_in": 300,
"interval": 3
}

The auth_req_id is needed when you request the Token endpoint (see below). The interval is how often you should be polling for a status update in seconds (see 3. Poll the ID Token endpoint).

2. Get the binding message and verify it​

For the end-user to be able to continue the transaction, they need to confirm a binding message in their BankID app to complete their authentication. The binding message format is two words separated by a space, for example "Snedig redning" (see screen example on the About page).

You need to relay the binding message to the end-user. You get this by calling the ID Token endpoint. You will then receive an error response with the authorization_pending status and can find the binding message in the error_description field.

ID Token request​

Here is an example of a typical ID Token request:

POST /auth/open/connect/token? HTTP/1.1
Authorization: Basic ZGV2LW...CamdraTd2
Host: yourdomain.signicat.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 101

auth_req_id=31920977-995e-254d-87d4-b323a6956552
&grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba

ID Token response​

Here is an example of a typical response from the ID Token endpoint where you can see the binding message in the error description:

{
"error": "authorization_pending",
"error_description": "Snedig redning",
"error_uri": "https://api.signicat.dev/auth/open/config/errors/authorization_pending"
}

3. Poll the ID token endpoint​

While the customer service agent is relaying the binding message, and the end-user is completing the transaction on their device, you should poll the ID Token endpoint for the status of the transaction.

Simply call the ID Token request, as you did in the previous step, until the error changes from authorization_pending to a different error, or until you get a success response.

Polling interval

When polling, ensure you use the same interval value (in seconds) as returned in the response of the session creation call (see the response example in step 1).

Once the transaction is successful, you receive an access_token and an id_token in the ID Token endpoint response.

Response example:

{
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
"expires_in": 600,
"token_type": "Bearer",
"scope": "openid profile nin idp-id nbid-extra"
}

You must use the access token in the UserInfo request (see Obtain user information below).

ID token​

An ID token is a JWT that encoded looks like "eyJhbGciOiJSUzI1NiIsImtpZCI6..." (abbreviated).

The decoded payload (data) part of the ID token for the Norwegian BankID Safe conversation flow would then look like:

{
"iss": "https://postman-test.sandbox.signicat.dev/auth/open",
"nbf": 1786967477,
"iat": 1786967477,
"exp": 1786968077,
"aud": "<OIDC_CLIENT_ID>",
"at_hash": "blK6EniyHQDMLvQ-YIs8DA",
"sub": "hC-l5RREjMgnDd3Wuq8v2Bt0X86sPkdzJzcZHbXzEGc=",
"auth_time": 1786967462,
"idp": "nbid",
"idp_id": "9578-6000-4-890775",
"name": "Kari Nordmann",
"family_name": "Nordmann",
"given_name": "Kari",
"birthdate": "1990-02-17",
"nin": "17029012345",
"nin_type": "BIRTH",
"nin_issuing_country": "NO",
"nbid_updated_at": "1728375869",
"nbid_originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
"nbid_acr": "urn:bankid:bis",
"nbid_subject_uuid": "vFafzatjbz1_k_FlizIpRzxrPspN_i_0mGLd0mWRVNM",
"nbid_sid": "tMgeBIZdqu-8BQiPkN1SkiaAOSstbV75VHJ47_9HWWo",
"nbid_alternative_subject": "9578-6000-4-890775",
"nbid_method": "biometric",
"nbid_amr": "bis-mfa, bis-hwk",
"nbid_auth_type": "PHONE",
"nbid_idp": "BIS",
"idp_issuer": "https://current.aletheia-test.idtech.no",
"transaction_id": "02696863-8bfa-9c41-bd42-1890fe78f17a",
"sandbox": true,
"acr": "substantial"
}

In this example we have used the following scopes for Norwegian BankID: openid profile idp-id nin nbid-extra

Control the returned claims in ID Token

For the complete documentation index, see llms.txt

ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes).

To control the data returned in the ID Token:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
  2. Choose your OIDC client and select Edit to view the client configuration.
  3. Navigate to the Advanced > Security tab and edit the ID Token User data. You can choose between:
    • Standard Scopes (default): Returns the standard OIDC scopes.
    • All: Returns all claims.
    • Minimal: Returns only sub.

In the above example, we have set the ID Token User data to All, which means it returns all the claims for Norwegian BankID.

4. Obtain user information​

You use the UserInfo request to obtain the user information as defined in the scopes.

For step details, see the general guide, UserInfo.

Here is a response example:

{
"idp_id": "9578-6000-4-890775",
"sub": "MuTkzKJfQi-X7oQu86mTDtE01AHMGA9gPx3Pe-tlUdM=",
"name": "Kari Nordmann",
"family_name": "Nordmann",
"given_name": "Kari",
"birthdate": "1990-02-17",
"nin": "17029012345",
"nin_type": "BIRTH",
"nin_issuing_country": "NO",
"nbid_updated_at": "1726237448",
"nbid_originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
"nbid_acr": "urn:bankid:bis",
"nbid_subject_uuid": "vFafzatjbz1_k_FlizIpRzxrPspN_i_0mGLd0mWRVNM",
"nbid_sid": "2me2o_eoI4TZQpv4z8qN2GSsWgfMZxCtWowY9s38p8Y",
"nbid_alternative_subject": "9578-6000-4-890775",
"nbid_method": "biometric",
"nbid_amr": "bis-mfa, bis-hwk",
"nbid_auth_type": "PHONE",
"nbid_idp": "BIS",
"idp_issuer": "https://current.aletheia-test.idtech.no"
}

For more details about available scopes and claims, see the Attributes reference.

See also​

Get inspired and learn more about how to set up CIBA for other eIDs: