Before you start

Before you can begin integrating with BankID OIDC platform, you need to make sure you have:

• Contacted one of our partners in order to acquire necessary Client credentials (client_id, client_secret) to our test environments (PREPROD, CURRENT). Request here.
• A Web Application with server side components (Pure frontend applications are not supported)

We strongly recommend that you make use of an OpenID Connect client library applicable for your platform. You can see some examples below, and you can also refer to the officially certified implementations.

OpenID Connect at a glance

OpenID connect is a protocol for authentication that builds on the OAuth 2.0 authorization framework. This getting started guide describes how to implement BankID OIDC using the authorization code flow.

In short, the steps necessary to perform an OpenID Connect authentication request is:

1. Redirect the end-user to the OIDC Service authorization endpoint with applicable parameters. The user will now authenticate using BankID.
2. After end-user has authenticated, she is redirected back to your web application at a pre-defined redirect URI endpoint.
3. Check the parameters received in the redirect and perform an Code-for-Token exchange request to the Token endpoint.
4. Use the Token received in order to access additional Value-Added services provided by the BankID OIDC Service.

Step by step

Get OIDC configuration

The OIDC library for your framework should allow you to provide a discovery URL to a JSON document containing configuration details for your OIDC provider. See Openid-configuration for more details.

Implementation details

Build authorization URL and initiate authentication request

The OIDC configuration contains an authorization endpoint. This is the URL you want to redirect your user to, in order to initiate the authentication request.
Additional information must be added to the request as query parameters. This includes scope to limit which information and resources you request access to and a redirect_uri to receive the callback from the BankID OIDC client, state to mitigate CSRF attacks and nonce to associate the client session with the id_token and mitigate replay attacks.
See Authorize for a full list of request parameters and more information.

Implementation guide

• Get the authorization_endpoint from the OIDC configuration.
• Generate a random string value and store it in a variable called state.
• Generate a random string value and store it in a variable called nonce.
•  Store the state and nonce value in your application so they can be retrieved later. It is up to you to decide how you want to store this information in your application, but make sure the nonce value is not available outside the application.
• Build the authorization URL by adding the following query parameters:
  • client_id: (your client id)
  • scope: openid profile (Request basic profile information and use the OIDC protocol).
  • redirect_uri: (URL to your backend callback POST endpoint to receive response from BankID OIDC)
  • response_type: code
  • state:(generated value for state)
  • nonce: (generated value for nonce)
• Redirect browser to the completed authorization URL.

Handle callback from BankID OIDC

After user has logged in with BankID OIDC, your web applicaton will receive a POST request to the redirect_uri that was provided in the authentication request. The web application will receive a 

Step 3: Receive code for token exchange and get access token

• Callback endpoint in your backend - expected of implementation/relying party:
  • Check that state query param is valid (check that it is the same as the one you created)
  • Get id_token and access_token by sending POST request to token endpoint.
  • Verify nonce in id_token
  • Save session in your framework/library of choice (suggestions?)