Foreign ID Document Verification Via Issuer Bank

1. Overview

This documentation describes the integration process for banks to support the issuance of BankID for users registering with a non-Norwegian identity document (e.g., passport). In such cases, the user provides both a foreign identity document and their National Identity Number (NNIN) or D number. Since the foreign document does not contain the NNIN, the service performs a lookup via the bank’s database to validate that the provided NNIN corresponds to the supplied document.

2. Purpose and Scope

The primary objectives are to:

Validate that a user presenting a non-Norwegian identity document, along with their NNIN/D number, exists in the bank’s records.
Ensure that the bank, as the issuer of the BankID certificate, confirms the registration of the NNIN and identity document combination.

If a match is found, an IdToken is generated, allowing the user to register for BankID. If no record is found, the user is informed that their application cannot proceed.

3. API Endpoint Specification

Endpoint: `/check_id`

Request

The API must accept a JSON payload with the following details:

Field	Type	Description	Example

Field	Type	Description	Example
nnin	string	National Identity Number or D number provided by the user	"12345678901"
originator	object	Information about the issuer of the BankID certificate	(See properties below)
originator.id	string	BankID issuer ID	"9980"
document	object	Details of the identity document provided by the user	(See properties below)
document.type	string	Type of document (e.g., passport, ID card)	"passport"
document.number	string	The document number	"CCC014356"
document.issuer	string	Issuing country code of the document	"AUS"
Authentication	-	API uses Entra ID-based authentication with JWT Bearer token	-
Response Fields	-	-	-
nnin	string	National Identity Number or D number from the request	"12345678901"
timestamp	string	Date-time of the verification result	"2025-02-10T12:00:00Z"
matchFound	boolean	Indicates if the NNIN and document were successfully verified	true / false

Error Responses

Status Code	Description

Status Code	Description
400 Bad Request	Invalid input data.
500 Internal Server Error	Unexpected server issue.

Sample OpenAPI Definition

openapi: 3.0.1
info:
  title: Check ID document against issuer
  version: 0.0.1
  description: Use ID document as a lookup method to find a user (NNIN or D number)
paths:
  /check_id:
    post:
      summary: Check ID document against issuer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nnin:
                  type: string
                  description: National Identity Number or D number
                  example: "12345678901"
                originator:
                  type: object
                  description: Issuer of the BankID certificate
                  properties:
                    id:
                      type: string
                      description: BankID issuer ID
                      example: "9980"
                document:
                  type: object
                  description: ID document information
                  properties:
                    type:
                      type: string
                      description: Type of document (e.g., passport, ID card)
                      example: "passport"
                    number:
                      type: string
                      description: ID document number
                      example: "CCC014356"
                    issuer:
                      type: string
                      description: Issuer of the ID document (country code)
                      example: "AUS"
      responses:
        '200':
          description: Lookup completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  nnin:
                    type: string
                    description: National Identity Number or D number
                    example: "12345678901"
                  timestamp:
                    type: string
                    format: date-time
                  matchFound:
                    type: boolean
                    description: Indicates if a match was found
                    example: true
        '400':
          description: Bad request
        '500':
          description: Internal server error

4. Business Flow

User Submission:
The user provides their NNIN/D number along with a non-Norwegian identity document (e.g., passport) that contains the document number but not the NNIN.
Validation Request:
The service sends an API request to the bank’s endpoint containing the user’s NNIN/D number and the provided document details.
Bank Lookup:
The bank performs a lookup in its database to verify whether the NNIN (or D number) matches the supplied identity document details.
Response Handling:
- If the bank confirms a match, the API responds with (matchFound: true), and the service proceeds to generate an IdToken to allow the user to register for BankID.
- If no match is found, the user is informed that their record could not be validated, and they will not be able to obtain BankID via the application.

Authentication: Entra ID-Based Access

The API uses Microsoft Entra ID for authentication. The client application obtains an OAuth 2.0 access token from Entra ID and includes it in the request header as a JWT Bearer token.

Example Request Header

Authorization: Bearer <access_token>
Content-Type: application/json

Token Validation by Bank

The receiving bank's system must validate the access token to ensure it is issued by Entra ID.
The token must be validated against the audience (aud) and the claims role-based access (roles).
If the token is valid, the request should be processed.