# Integration with OIDC
Table of contents
This guide details how to set up authentication for Norwegian BankID using the OIDC protocol.
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. Set up the OIDC client
- 2. Configure the scope for the Norwegian BankID
- 3. Craft the authentication URL
- 4. Create a Token request
- 5. Create a UserInfo request
# 1. Set up the OIDC client
Set up the OIDC client in the Signicat Dashboard (opens new window). For step details, see the general guide, Set up an OIDC client.
# 2. Configure the scope
Available scopes for Norwegian BankID are: openid profile nin nbid-extra idp-id
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 (opens new window) 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 more details about these scopes, see the Attributes reference.
# 3. Craft the authentication URL
This step describes how to generate the URL that opens the Norwegian BankID login screen.
You can pre-select an ID method in your authorization request by including the name of the identity provider (idp
) in the acr_values
parameter. To pre-select Norwegian BankID, include acr_values=idp:nbid
in your authorization request.
Here is an example authentication URL:
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
client_id=sandbox-example-client-123
&response_type=code
&scope=openid
&prompt=login
&acr_values=idp:nbid+nbid_idp:BID
&redirect_uri=https://myservice.example/redirect
The URL consist of two parts:
- The first part is the base URL,
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize
. - The remainder constitutes parameters to set things like Client ID, Norwegian BankID flow and redirects.
# Control the Norwegian 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
You can use the acr_values
parameter to set the preferred Norwegian BankID flow.
Available parameters and values are:
Name | Values | Description |
---|---|---|
idp | nbid | Specify idp: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 idp: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. |
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). This parameter works in conjunction with login_hint. |
nbid_nin_consent | true or false | If set to true, 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. |
For a conceptual description of the main product types, including screen images of user flows, see the About page.
# Example
acr_values=idp:nbid nbid_idp:BIS nbid_nin_consent:true
This will have the following effect:
- BankID Biometrics (BIS) will be pre-selected for the user.
- The user will be asked for consent to share their national identity number.
# login_hint
You can use login_hint
to prefill user information that we send to Norwegian BankID, for example, the end-user's national identity number ("fødselsnummer").
Available options are:
Name | Description | More details |
---|---|---|
nin | Prefilled national identity number ("Fødselsnummer") | Used when creating the login_hint for all Norwegian BankID flows (BID ,BIS and BIM ). |
mobile | Prefilled phone number | Used when creating the login_hint for BIM (BankID on Mobile). |
birthdate | Prefilled date of birth (YYYY-MM-DD) | Used when creating the login_hint for BIM (BankID on Mobile). |
# Example
The format is a space-separated list of key-value pairs:
login_hint=nin:17029012345 mobile:90123456
This will prefill the national identity number and the mobile number of the end-user to the specified value.
# 4. Create a Token request
You use the Token request to obtain an access token to be used in the UserInfo request.
For step details, see the general guide, Token.
# 5. Create a UserInfo request
You use the UserInfo request to obtain the user information as defined in the scopes (see step 2 and 3).
For step details, see the general guide, UserInfo.
See also the Attributes reference page for a list of available scopes, claims and a userInfo response.