Skip to main content

Authorization code flow

This guide details how to set up regular Norwegian BankID authentication (High and Biometric) using the standard OIDC authorization code flow.

Prerequisites​

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

Set up the OIDC client in the Dashboard​

1. Add an OIDC client​

When you register an OIDC client application, you receive a client ID. To do this:

  1. In the Signicat Dashboard, go to eID Hub > OIDC clients and select Create/Add client.
  2. Enter a name for the client.
  3. In Primary grant type, select which grant type you want to use with this client. We strongly recommend AuthorizationCode. For further information about the different grant types, refer to the OIDC specification and the OAuth 2.0 specification.
  4. In the Redirect URI field, enter the URL that you want to redirect your end-user to when the authentication process is finished. Note that if you want to use more than one redirect URI, you can still add them after the client has been created.

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 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. Add a client secret​

Depending on the type of your application, you may want to add a client secret. To do this:

  1. In the menu for the OIDC Client, go to the Secrets tab and click Add secret.
  2. Enter a name for your client secret and click Create.
  3. Copy your new client secret and store it safely.
Important
  • Save the client secret in a safe place, since you will only be able to view your client secret once, right after you create it. If you ever forget it or lose it, you have to create a new one.
  • If you intend to use the OIDC client in a frontend flow or any type of application that cannot store a client secret, you must use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the eID Hub documentation.

Implement the OIDC authentication flow​

In OIDC, an application first needs to specify which permissions to request, then send the end-user to a browser to get their permission. After the end-user approves the authentication request and gets redirected to your website, your application receives back an authorization code that it can exchange for an access token and an ID token. You can find the end-user data attributes in the ID token or in the UserInfo endpoint.

1. Build the authentication request​

This step describes how to generate the URL that opens the Norwegian BankID login screen.

To begin the authentication flow, your application should build an authentication URI that the end-user can open in a browser to start an authentication flow with BankID. The authorize endpoint starts the authentication flow with the end-user. It directs the end-user to the authorisation server, where the end-user logs in with their BankID account.

Your application sends an HTTPS GET request with the appropriate URI parameters.

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 consists of two parts:

  • The first part is the base URL, https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize. This URL is available in the discovery document of your OIDC client which you can find under Well-Known URL for client in your OIDC client configuration in the Dashboard.
  • The remainder constitutes parameters to set things like Client ID, flow and redirects.

Note the following query parameters:

  • client_id: The client ID of your OIDC application. You can find this in the Dashboard > OIDC Clients.
  • response_type: Specifies the required grant type for the OIDC flow.
  • scope: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow.
  • prompt: Controls the behaviour of the authentication flow. For more details, see Forcing re-authentication.
  • acr_values: (Optional) A space-separated list of key-value pairs to customise the authentication flow.
  • redirect_uri: The URI where to redirect the user after they approve the request at the end of the OIDC flow. This must be an absolute URI using the HTTPS protocol.
Important

The values you specify in the query parameters must match the values in the OIDC client configuration in the Dashboard.

You can find additional authorization request query parameters in the OIDC specification.

The acr_values and login_hint parameters are described in more detail below.

Control the 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​

Available parameters and values are:

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 Biometric (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"), nin.

login_hint=nin:17029012345

This will prefill the national identity number to the specified value. Then only the user with the prefilled information will be able to authenticate.

End-user authentication​

The end-user follows these steps:

  1. On your website/application, the end-user clicks on a button to authenticate with Norwegian BankID. Your application sends an authorization request to start an authentication, as described in the previous section.
  2. The end-user is redirected to the BankID authentication page.
  3. The end-user logs in using their BankID credentials (this step may involve two-factor authentication).

After the end-user approves the request, the authorization server redirects the browser back to the redirect_uri specified by the application, adding a code in the server response.

For screen examples, see About Norwegian BankID.

Server response​

Here is an example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>/?
code=DBB67B2E8E95933A1B8D283C04848DC6A878855B943671DED1310736A811D44E-1
&scope=openid%20profile%20idp-id%20nin%20nbid-extra
&session_state=MZvUqShFyumujsPPyby4cyUNhxrSKvmkBuDFvONHlcw.00C7928A96EBC64F87BEA33E37C3290B
&iss=https%3A%2F%2F<YOUR_SIGNICAT_DOMAIN>%2Fauth%2Fopen

The code is the authorization code generated by the authorization server. You use this code in the request to the token endpoint to obtain an access token and the ID token (see the next sections).

2. Obtain the access token​

Your application should exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the authorization server token endpoint.

Example token request​

curl -X POST https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/token -H 'Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=authorization_code&redirect_uri=<REDIRECT_URI>&code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1&code_verifier=oQDZ3uPQn...W7U'

Example token response​

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
    "expires_in": 600,
    "token_type": "Bearer",
    "scope": "openid profile idp-id nin nbid-extra"
}

ID token​

An ID token is a JWT that encoded looks like "eyJhbGciOiJSUzI1NiIsImtpZCI6..." (abbreviated).

The decoded payload (data) part of the ID token for Norwegian BankID would then look like:

{
  "iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
  "nbf": 1713946792,
  "iat": 1713946792,
  "exp": 1713947392,
  "aud": "<OIDC_CLIENT_ID>",
  "amr": "[\"external\"]",
  "at_hash": "EKuiasgSHLDX8lOnxPBKew",
  "sid": "C2CFE1642F3C388EDE033AE0578A9B97",
  "sub": "47HtEWLEaHc8Bk5UtIqfpWg1iAD8DukDg3jzXIOqTEg=",
  "auth_time": 1730277705,
  "idp": "nbid",
  "idp_id": "9578-6000-4-877",
  "name": "Kari Nordmann",
  "family_name": "Nordmann",
  "given_name": "Kari",
  "birthdate": "1990-02-17",
  "nin": "17029012345",
  "nin_type": "BIRTH",
  "nin_issuing_country": "NO",
  "nbid_updated_at": "1669629608000",
  "nbid_subject_uuid": "e6418f52-b90d-49ea-a448-a73d39f24ec7",
  "nbid_idp": "BID",
  "nbid_alternative_subject": "9578-6000-4-877",
  "nbid_tid": "7240b9ae-19cc-45bc-908c-e78d03a9851b",
  "nbid_additional_cert_info": "{\"certValidFrom\":1606394130000,\"serialNumber\":\"1407572\",\"keyAlgorithm\":\"RSA\",\"keySize\":\"2048\",\"policyOid\":\"2.16.578.1.16.1.12.1.1\",\"monetaryLimitAmount\":\"100000\",\"certQualified\":true,\"monetaryLimitCurrency\":\"NOK\",\"certValidTo\":1669466130000,\"versionNumber\":\"3\",\"subjectName\":\"CN=Nordmann\\\\,Kari,O=TestBank1 AS,C=NO,SERIALNUMBER=9578-6000-4-877\"}",
  "nbid_auth_time": "1730277704",
  "nbid_originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
  "idp_issuer": "https://auth.current.bankid.no/auth/realms/current",
  "transaction_id": "122abafd-e0d8-514c-a23a-86ea452a97ba",
  "sandbox": true
}

In this example we have used the following scopes for Norwegian BankID: openid profile idp-id nin nbid-extra

Control the returned data in ID Token​

ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes).

To control the data returned in the ID Token:

  1. Open the Dashboard OIDC clients and select your OIDC client.
  2. Go to the Advanced > Security tab and edit the Id Token User data. You can choose between:
    • Standard Scopes (default): Returns the standard OIDC scopes.
    • All: Returns all claims.
    • Minimal: Returns only sub.

3. Obtain user information​

You use the UserInfo request to obtain the user information as defined in the scopes.

This response example shows user information retrieved from the UserInfo endpoint:

{
  "idp_id": "9578-6000-4-877",
  "name": "Kari Nordmann",
  "family_name": "Kari",
  "given_name": "Nordmann",
  "birthdate": "1990-02-17",
  "nin": "17029012345",
  "nin_type": "BIRTH",
  "nin_issuing_country": "NO",
  "nbid_updated_at": "1669629608000",
  "nbid_subject_uuid": "e6418f52-b90d-49ea-a448-a73d39f24ec7",
  "nbid_idp": "BID",
  "nbid_alternative_subject": "9578-6000-4-877",
  "nbid_tid": "7240b9ae-19cc-45bc-908c-e78d03a9851b",
  "nbid_additional_cert_info": "{\"certValidFrom\":1606394130000,\"serialNumber\":\"1407572\",\"keyAlgorithm\":\"RSA\",\"keySize\":\"2048\",\"policyOid\":\"2.16.578.1.16.1.12.1.1\",\"monetaryLimitAmount\":\"100000\",\"certQualified\":true,\"monetaryLimitCurrency\":\"NOK\",\"certValidTo\":1669466130000,\"versionNumber\":\"3\",\"subjectName\":\"CN=Nordmann\\\\,Kari,O=TestBank1 AS,C=NO,SERIALNUMBER=9578-6000-4-877\"}",
  "nbid_auth_time": "1730277704",
  "nbid_originator": "CN=BankID - TestBank1 - Bank CA 3,OU=123456789,O=TestBank1 AS,C=NO;OrginatorId=9980;OriginatorName=BINAS;OriginatorId=9980",
  "sub": "47HtEWLEaHc8Bk5UtIqfpWg1iAD8DukDg3jzXIOqTEg=",
  "idp_issuer": "https://auth.current.bankid.no/auth/realms/current"
}

See also the Attributes reference page for a list of available scopes, claims and a userInfo response.

Success

You have now completed an authentication flow with Norwegian BankID.

Next steps​

Dive deeper into the possibilities and improve your application with advanced code examples:

OIDC code examples
Get inspired by our basic and advanced code examples

For ecommerce customers under certain conditions, it is also possible to embed the Norwegian BankID authentication into your own flow:

CIBA flow (advanced)
Embed the BankID authentication in an iframe
Last updated:
On this page