This section on technical documentation contains information on how to integrate with the services supported by the OpenID Connect Provider from BankID. 

• See the problems we solve for further information on the products, features and functions of such services
• See the getting started guide for a step-by-step description on how to integrate BankID over OpenID Connect
• Access developer resources for info on environments, provisioning, and how to monitor the operational status of BankID
• See the 2023-08-22_12-43-16_Release Notes for information on changes and new features supported

BankID OpenID Connect overview

BankID services are available over OpenID Connect (OIDC) where we have a multi-tenant OpenID provider offering authentication and signing with BankID netcentric and BankID on mobile at LoA4. This OpenID provider has the capability to host several BankID merchant certificates where a Client (Relaying Party, BankID Merchant) may either be configured with its own BankID merchant certificate, or share a common BankID merchant certificate with other Clients.

The term OIDC Client is used for any application that integrates with the OIDC Provider, corresponding to the following terms in related vocabularies:

• OAuth2 clients in OAuth vocabulary
• Relying Party in OIDC vocabulary
• Merchant in BankID vocabulary

The BankID service is implemented as two different Identity providers offering support for both BankID netcentric and BankID on mobile.

OIDC Clients use Scopes and Claims to request access to services. Identity Providers return ID Tokens containing assertions about the end-user and (optionally) Access Tokens to gain subsequent access to resource servers for downloading signign results or end-user data through api-userinfo. Consent handling is a key feature of the OIDC Provider that puts the end-user in control of delegating rights to an OIDC Client to access any end-user data on behalf of the end-user. 

Test Users are available to test and get familiar with the OIDC Provider and its supported services.

...

Before you start

OpenID Connect with Authorization Code flow

OpenID Connect is a protocol for authentication that builds on the OAuth 2.0 authorization framework. This getting started guide describes how to integrate BankID in your application using authorization code flow.

The steps necessary to perform an OpenID Connect authentication request is:

1. Redirect the end-user to the authorization endpoint with applicable parameters. 
2. The end user authenticates using BankID and is redirected back to your web application.
3. Handle the redirect request by checking parameters and handle potential errors. 
4. Exchange the code parameter for tokens by making a request to the token endpoint. 
   
   1. Use the ID token to identify the user.
   2. Use the Access token to access resource servers, for example in the context of signing documents online.
   3. Use the Refresh token to retrieve new access tokens.

Implementation

Initiate authentication request

1. Connect to the appropriate OIDC discovery endpoint using your preferred framework and store the JSON response in your application.
   Note: Make sure to keep the response updated every so often (at least daily).
   
   For the public test environment (CURRENT) the Discovery endpoint is:
   https://auth.current.bankid.no/auth/realms/current/.well-known/openid-configuration.
   
   
2. Use the authorization_endpoint found in the Discovery endpoint response.
   Note: Do not hard code the authorization_endpoint value. Always retrieve it from the OpenID Connect configuration, as it may change.
   
   
3. Generate a random string value and store it in a variable called state.
   Important: The value must be non-guessable (e.g. GUID) and unique for each request.
   This value will be used to mitigate cross-site request forgery, but can also be used to link the callback to the original request.
   
   
4. Generate a random string value and store it in a variable called nonce.
   Important: The value must be non-guessable, cryptographically random (your framework/language most likely have support for this) and unique for each request.
   This will be used to verify integrity of ID token and mitigate replay attacks.
   
   
5. Store the state and nonce value in your application so they can be retrieved later, i.e. using your preferred session mechanism. These values should be stored together.
   
   
6. Build the authorization URL by adding the following query parameters (see Authorize for more options and details):
   • client_id: Unique client identifier provided when provisioning the client.
   • scope: Specify which information (see ID token) and resources you request access to. In the example, we use openid and profile to get a regular ID token.
   • redirect_uri: URI to your server-side callback endpoint where you want to receive response from the BankID OIDC service.
   • response_type: Determines message flow. Only "code" is supported.
   • state: Your generated value for state.
   • nonce: Your generated value for nonce.
     
     

   Code Block
   title Example authorization request
   GET authorization_endpoint ?client_id=myclient-bankid-current &scope=openid+profile &redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback &response_type=code &state=01e3ac8e-4a26-4dfb-79ca-2631394c4144 &nonce=1fb72f68-1bea-2ba2-12d7-24df1c999d1b

7. Redirect end-user to the completed authorization URL.

Handle callback from BankID OIDC

1. Create an endpoint in your web application's backend for receiving the callback from the application (i.e. a GET request to your redirect_uri).
   
   
2. Check that the state query parameter returned corresponds to the state parameter you created when initiating the request.
   
   1. If the state is missing or is not matching a state value stored in your application, reject the request.
   2. If the state match a state stored in your application, update the state from in your session mechanism and continue to the next step.
      
      
3. Check if the request contains the response parameter error.
   1. If the error parameter is not present, continue to the next step.
   2. If the error parameter is present, you need to handle the error.
   • • The possible ASCII values for the error query parameter is defined in the specification for OIDC (§3.1.4.6) or OAuth 2.0 (RFC 6749, §4.1.2.1).
     • If the end-user cancels an authentication request in the BankID OIDC client, error will have the value access_denied.
     • In addition to error, the response parameter error_description might be available, but it is only intended for developers and not to be shared with the end-user.
       
       
4. Retrieve the ID token, Access token and Refresh token. by sending a POST request to the token endpoint.
   1. Verify that the nonce claim in the received ID token corresponds to the nonce value you belonging to the same session (i.e. the nonce belonging to the state).
      1. If the nonce is missing or does not match the nonce stored in your application, reject the request and do not continue.
      2. If the nonce match the nonce stored in your application, delete the state and nonce in your session mechanism and continue to the next step.
         
         
5. The ID token contains claims that can be used to identify the end-user. See ID token for available claims.
   
   
6. The Access token can be used to access additional services such as document signing or additional user information through api-userinfo.

Next steps

It is recommended to take a look at Session handling to get a better understanding of the session lifetime.

Known issues contains a list of restrictions, caveats and known problems. 

The Deprecations list is also interesting to keep an eye on.

The list of error codes displayed to the end-user is useful for troubleshooting.