# 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:
- The general eID Hub documentation.
- The API Reference (opens new window) for endpoint descriptions.
# 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.