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.
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
To create an OIDC client for CIBA:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients.
- Select Create/Add client.
- Set the Primary grant type to "Ciba".
- Enter a name for the client.
- 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
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:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
- Select Edit to view your client configuration.
- Open the Access tab.
- 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
Depending on the type of your application, you may want to add a client secret. To do this:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
- Choose your client, go to the Secrets tab and select Add secret.
- Enter a name for your client secret and select Create.
- Copy your new client secret and store it safely.
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.
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
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
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.
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
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:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
- Choose your OIDC client and select Edit to view the client configuration.
- 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: