Developer Pages

# Integration with Authentication REST API

Table of contents

This guide details how to set up authentication for Norwegian BankID using the Signicat Authentication REST API. Requests are sent from your backend server to the Authentication REST API.

The currently supported mechanisms for authentication with Norwegian BankID are:

  • BankID High (BID)
  • BankID Biometrics (BIS)
  • BankID on Mobile (BIM)

The mechanisms are set up in the same way, except for some minor differences in field values, as described in the following sections.

General documentation

If you want to read more about the basics of our eID Hub product before you start integrating with Norwegian BankID, see:

# Prerequisites

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

# Step overview

# 1. Get client credentials

Before you can make a request to the Authentication REST API, you need to set up an API client to obtain client credentials. How to do this is described in Accessing Signicat API products > Set up an API client.

# 2. Obtain access token

You use the client credentials in a request to obtain an access token. The access token needs to be passed in as an HTTP Bearer authentication header when sending the requests. For more details, see Accessing Signicat API products > Obtaining an access token.

# 3. Create a session

# Request

You use the CreateSession (opens new window) endpoint to create and start a session. The response from this endpoint will contain an authentication URL, to which you can redirect the end-user to start their Norwegian BankID transaction.

To create a session, send a POST request to https://api.signicat.com/auth/rest/sessions. The following sub-sections show a code example and descriptions of attributes that you can include in the request.

# Request example

Here is an example request body for an authentication with Norwegian BankID High (BID):

{
    "allowedProviders": ["nbid"],
    "flow": "redirect",
    "additionalParameters": {
        "nbid_idp": "BID"
    },
    "prefilledInput": {
        "nin": "17029012345"
    },
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    }
}

Upon sending this request, the Norwegian BankID session will start.

If the authentication completes successfully, the final result will contain the attributes that were requested.

# Attribute descriptions

To initialise an authentication with Norwegian BankID, you can use the following attributes in the initial request:

Field Required Example value Description
allowedProviders No ["nbid"] Specify ["nbid"] if you want to be sent directly to Norwegian BankID. You can specify multiple ID methods to show the user a list of different identity providers. Specifying ["nbid", "sbid"] allows the user to choose between Norwegian BankID and Swedish BankID. Don’t specify this field if you want to show a list of all the ID methods your account has connections for.
flow Yes redirect MUST have the value redirect.
# Control the user flow (additionalParameters)

You use additionalParameters to control the redirect flow. This is not a required field.

Name Values Description
nbid_idp BID, BIS or BIM This value specifies the required Norwegian BankID type (BID=High, BIS=Biometric, BIM=Mobile). If no value is provided, the default behaviour is that the end-user can select either BID or BIM (but not BIS).
nbid_nin_consent true or false If this is an onboarding context, you should set this to true. Then, the user will be prompted for consent to share their national identity number ("fødselsnummer"). If not provided, the user will not be prompted for consent.
# Prefill user information (prefilledInput)

You can use the prefilledInput parameter to prefill information about the user, for example, so the user does not have to fill in this information manually. If prefilled, only the user with the prefilled information will be able to authenticate. This is not a required field.

Available options are:

Name Example value Description
nin "prefilledInput": {"nin": "17029012345"} Prefills the national identity number ("Fødselsnummer")
mobile "prefilledInput": {"mobile": "+47123456"} Prefills the phone number. Used for BIM(BankID on Mobile).
dateOfBirth "prefilledInput": {"dateOfBirth": "1990-02-17"} Prefills date of birth (YYYY-MM-DD). Used for BIM(BankID on Mobile).
# User attributes (requestedAttributes)

You can request the following attributes from users of Norwegian BankID.

Name Example value (in result) Description
name Kari Nordmann Full name of user
firstName Kari First name of user
lastName Nordmann Last name of user
dateOfBirth 1990-10-27 Birth date of user (ISO 8601 format)
nin {
"value": "17029012345",
"issuingCountry": "NO",
"type": "PERSON"
}		 National identity number of user, along with some metadata

You add them in the requestedAttributes as shown in the request example above.

For an overview of all attributes, see the Attributes reference.

# Response

Here is an example response after you have created a session:

{
    "id": "fb432801-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.com:443/?sessionId=fb432801-66f6-6141-9835-e2a3b42e2e35",
        "abort": "https://example.com:443/abort?sessionId=fb432801-66f6-6141-9835-e2a3b42e2e35",
        "error": "https://example.com:443/error?sessionId=fb432801-66f6-6141-9835-e2a3b42e2e35"
    },
    "allowedProviders": [
        "nbid"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "sessionLifetime": 600
}

# What you need to do with the response

You must redirect the end-user to the authenticationUrl found in the response. This is a unique URL which allows the user to perform the Norwegian BankID authentication in context of the session you just created.

# 4. Get the session status

# Request

No data specific for Norwegian BankID needs to be provided in this request.

To get the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can find the id value in the response that was returned when you created the session. For more information about the "Get session status" endpoint, see the API Reference (opens new window) description.

# Response

The response will contain a status field, which indicates the current status of the session. Below you can see an example response for a successfully completed session:

{
    "id": "fb432801-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "SUCCESS",
    "provider": "nbid",
    "subject": {
        "id": "opuc4kyFUWPkfdmfYTzjS89u6ZCWLHWLZfPR5hpBW24=",
        "idpId": "9578-6000-4-1663921",
        "name": "Kari Nordmann",
        "firstName": "Kari",
        "lastName": "Nordmann",
        "dateOfBirth": "1990-02-17",
        "nin": {
            "value": "17029012345",
            "issuingCountry": "NO",
            "type": "BIRTH"
        }
    },
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=58126fb8-c5e2...",
        "abort": "https://example.com/abort?sessionId=58126fb8-c5e2...",
        "error": "https://example.com/error?sessionId=58126fb8-c5e2..."
    },
    "allowedProviders": [
        "nbid"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "sessionLifetime": 600
}

# Status overview

Status Description
CREATED The user has not completed the authentication yet.
SUCCESS The authentication is successful. Authentication result is present in the response.
ABORT The session was cancelled by the end-user.
ERROR Something went wrong during the session, or the session was not completed in time.

# What you need to do with the response

If the returned status is SUCCESS, you will find information about the authenticated user in the subject object.

You will also see what provider was actually used by checking the provider field. This can be useful if you allowed more than one provider when you created the session.

Last updated: 08/05/2024 14:10 UTC

← Attributes reference →