Integration with OIDC

Table of contents

• Prerequisites
• Step overview
• 1. Set up the OIDC client
• 2. Configure the scope
• 3. Craft the authentication URL
  • Control the Norwegian BankID flow (acrvalues and loginhint)
• 4. Create a Token request
• 5. Create a UserInfo request

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_valuesparameter. 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.