Skip to main content

OpenID Connect

This section details how to integrate with Swedish BankID using OpenID Connect (OIDC) as an authentication protocol.

The currently supported mechanisms for Swedish BankID are:

  • QR code: Launches the QR code flow on a remote device.
  • App launch: Launches the BankID app locally on the same device.
  • MRTD check: Adds an extra security check to a normal authentication flow.
  • Phone flow: Allows authentication via a telephone call.

The above mentioned mechanisms are set up in the same way for all protocols, except for some minor differences in field values, as described in the following sub-sections.

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 Swedish BankID are: openid profile nin sbid-extra sbid-evidence 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 section describes how to generate the URI that opens the Swedish BankID authentication page.

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 Swedish 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 Swedish BankID, include acr_values=idp:sbid in your authorization request.

Here is an example of an OIDC authentication URI:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
client_id=sandbox-example-client-123
&response_type=code
&scope=openid
&prompt=login
&acr_values=idp:sbid
&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)​

Signicat provides different flow options for BankID. This section describes how to control those flow options when using the OIDC protocol.

You can use the acr_values parameter to adjust how the authentication flow behaves by using the following available parameters and corresponding values:

The Phone flow requires "trusted" acr_values

You must send sbid_auth_type and sbid_phone_initiatoras "trusted" parameters. This means you must use signed authorisation requests (see code examples in the general eID Hub docs).

Examples​

Remote flow with QR code and intention text:

acr_values=idp:sbid sbid_initial_flow:REMOTE_FLOW sbid_intention_text:VGVzdCBpbnRlbnRpb24gdGV4dAo=

Phone flow:

acr_values=idp:sbid sbid_auth_type:PHONE sbid_phone_initiator:OPERATOR

login_hint (prefill user information)​

You can use the login_hint parameter to prefill information about the user, for example, so the transaction is locked down to a specific user.

Only for nin

Prefilling of user information only applies to the national identification number (nin) for Swedish BankID. You cannot prefill other user data.

Example​

login_hint=nin:199002171234

This will prefill the national identity number of the end-user to the specified value.

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

3. Create a UserInfo request​

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

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.

Next steps​

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

OIDC CIBA flow (advanced)
Learn how to set up BankID with the CIBA flow
OIDC code examples
Get inspired by our basic and advanced code examples
Last updated:
On this page