Skip to main content

CIBA flow in iframe (advanced)

This guide details how to embed the Norwegian BankID authentication inside an iframe in your own flow (as opposed to redirecting to another page).

Available for special use cases

Using an iframe in authentication comes with security considerations. It is NOT supported for regular BankID authentication. However, we support using iframes for ecommerce customers under certain conditions.


iframe is primarily used with BankID Biometric (BIS), which gives a substantial level of assurance. If you want to use a higher level of assurance, you can configure a step-up to BankID High, meaning the end-user must authenticate with a password after the biometric identification.


If you want access to the iframe functionality, please contact us by creating a support ticket in the Signicat Dashboard.

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:

  1. In the Signicat Dashboard, go to eID Hub > OIDC clients and select Create/Add client.
  2. Set the Primary grant type to "Ciba".
  3. Enter a name for the client.
  4. 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 ID methods.

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

  • In the Dashboard, go to the OIDC Client you intend to use for the ID method.
  • Click Edit: to view your client configuration.
  • Open the Access tab.
  • Click Add scope in the "Allowed scopes" section and select the scopes from the list.

For descriptions of these scopes, see the Attributes reference.

Add parent domains​

When embedding Norwegian BankID in an iframe, you must add parent domains:

  1. In the menu for the OIDC Client, select Advanced > Security.
  2. In the Allowed Parent Domains for Embedded flows field, add at least one domain.

2. Add a client secret​

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

  1. In the menu for the OIDC Client, go to the Secrets tab and click Add secret.
  2. Enter a name for your client secret and click Create.
  3. 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.
  • If you intend to use the OIDC client in a frontend flow or any type of application that cannot store a client secret, you must 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 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 could look 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=nbid_ciba&
acr_values=idp%3Anbid&%20flow%3embedded&
scope=openid%20profile%20nin
return_url=https%3A%2F%2Fexample.com
Important

The values you specify in the query parameters must match the values in the OIDC client configuration 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:

Step-up

BankID does an internal risk assessment and will force users to do a step-up if they deem it necessary, but by providing high you can force a step-up if you have your own risk assessment strategy. Transactions with forced step-up will be billed differently than transactions where it is not forced.

login_hint​

login_hint=nbid_ciba

login_hint=nin:17029012345

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": 1
}

The auth_req_id is needed when you request the Token endpoint (see below).

2. Obtain the authentication URL​

To obtain the authentication URL where the user should be redirected, you must make a request to the Token endpoint.

To do that, you perform a HTTP POST call to the Token endpoint with the following parameters

  • auth_req_id = 31920977-995e-254d-87d4-b323a6956552 (The auth_req_id received in the previous response.)
  • grant_type = urn:openid:params:grant-type:ciba

An example of HTTP request would look like this:

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

In the first call to the Token endpoint the response will contain the error_uri element (some headers omitted for brevity):

{
    "error": "authorization_pending",
    "error_description": "Authentication Pending, you need to log using the url",
    "error_uri": "https://api.signicat.dev/idps/sandbox/nbid/ciba/initialize-auth?transactionId=31920977-995e-254d-87d4-b323a6956552&messageId=eddc24af-ccb8-409d-b5d3-e591111e2807"
}

You must redirect the user to this error_uri.

3. Retrieve the sessionNonce​

After the user has finished the authentication and been redirected to your specified return_url, you must retrieve the returned sessionNonce value and include it in the ID token request (see below) to get information about the transaction and the user.

Security measure

We return the sessionNonce value to ensure that the communication session is unique and cannot be used in replay attacks.

The sessionNonce value is returned at the end of the return_url, for example:

https://example.com/?sessionNonce=P-zvdIDsW6ZKGn5__48Df9RitMlxHvUe1RHZ-PLxczc

4. Retrieve the ID token​

Once the user has successfully completed the authentication, you must perform a new HTTP POST call to the Token endpoint with the following body parameters:

  • auth_req_id = 31920977-995e-254d-87d4-b323a6956552 (the auth_req_id received when creating the session.)
  • grant_type = urn:openid:params:grant-type:ciba

You must also include the sessionNonce in the POST request to the Token endpoint (see Retrieve the sessionNonce). It must be included as a query parameter called session_nonce.

POST /auth/open/connect/token?session_nonce=zvdIDsW6ZKGn5__48Df9RitMlxHvUe1RHZ-PLxczc

Full request example:

POST /auth/open/connect/token?session_nonce=zvdIDsW6ZKGn5__48Df9RitMlxHvUe1RHZ-PLxczc 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

By sending this request you will receive an access_token and an id_token in the 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"
}

ID token​

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

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

{
  "iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
  "nbf": 1730276949,
  "iat": 1730276949,
  "exp": 1730277549,
  "aud": "<OIDC_CLIENT_ID>",
  "at_hash": "L5ArXYPIth0nCL38oSdt2w",
  "sub": "MuTkzKJfQi-X7oQu86mTDtE01AHMGA9gPx3Pe-tlUdM=",
  "auth_time": 1730276926,
  "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_alternative_subject": "9578-6000-4-890775",
  "nbid_idp": "BIS",
  "nbid_subject_uuid": "vFafzatjbz1_k_FlizIpRzxrPspN_i_0mGLd0mWRVNM",
  "nbid_updated_at": "1726237448",
  "nbid_sid": "BiXRO3eqJqn6HAUdCSA6aRcFAzKwGBDY613XHLEPQvc",
  "nbid_originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
  "idp_issuer": "https://current.aletheia-test.idtech.no",
  "transaction_id": "00f4cf79-bf99-5949-8db3-e302dc735905",
  "sandbox": true
}

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

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. Open the Dashboard OIDC clients and select your OIDC client.
  2. Go 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.

The access token will be used in the UserInfo request (see Obtain user information below).

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_originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
    "nbid_sid": "BiXRO3eqJqn6HAUdCSA6aRcFAzKwGBDY613XHLEPQvc",
    "nbid_updated_at": "1726237448",
    "nbid_subject_uuid": "vFafzatjbz1_k_FlizIpRzxrPspN_i_0mGLd0mWRVNM",
    "nbid_idp": "BIS",
    "nbid_alternative_subject": "9578-6000-4-890775",
    "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 ID methods:

Swedish BankID
Set up Swedish BankID with CIBA
MobileID
Set up MobileID with CIBA
Last updated:
On this page