Skip to main content

Setup of Swedish BankID

Integration with BankID is done similarly to Signicat's other ID methods. This page describes the specifics for setting up BankID. For more general information on how to integrate with Signicat's protocols, see the Quick start guide.

Initial preparations​

The setup descriptions below assume you have completed the following initial preparations:

Sandbox account

We recommend that you test our services with your sandbox account before implementing them in production.

Add BankID in the Dashboard​

Sign an agreement

You do not need any agreement to add BankID with a sandbox account. However, before you can start integrating in production, you need to configure BankID access with an onboarding manager. To get help with this, follow the steps in Sign agreements and order certificate or contact us.

To add BankID to the list of supported ID methods:

  1. In the Signicat Dashboard, go to eID Hub > ID Methods.
  2. Click Add new.
  3. Choose Swedish BankID in the list and click Save.

You can now continue with selecting a protocol and configuring the ID method.

Select protocol and configure​

This section describes how you select and set up different BankID integrations. You can choose between the following protocols:

Which protocol?

Choice of protocol depends on what you prefer and what you want to achieve. The Signicat Authentication REST API gives you a lot of flexibility and enables options such as headless flow in addition to redirect. Between the other two, we recommend using OIDC, since SAML 2.0 is much more complex to implement on your side and usually requires a federation agent already in place. OIDC is industry standard and you do not need to manage user sessions on your own (like with the Authentication REST API).

You can find more information about the different types in the general section, Authentication protocols.

OIDC

This section details how to set up Swedish BankID with the OIDC protocol.

1. Add OIDC configuration

Before you start building the integration, you need to set up an OIDC client and create a client secret in the Dashboard. Follow the steps in the Quick start guide.

For an overview of available scopes for BankID (needed when you define the OIDC client), see the Scopes and claims for OIDC.

2. Control the BankID flow

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

Example authorization request

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 on an authorization 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:sbid
&redirect_uri=https://myservice.example/redirect

The URL consist of a base URL https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize and the following parameters:

  • client_id: OIDC Client ID you created in the Dashboard.
  • scope: OIDC scopes that determine the BankID flow. openid is a required parameter. For an overview of available scopes and claims for BankID, see the Scopes and claims for OIDC.
  • redirect_uri: The URI where the end-user is redirected to at the end of the authentication flow. This must be the same as you defined in the OIDC configuration in the Dashboard.
  • response_type: Based on the response flow you set for the OIDC Client (this is an advanced feature).

The acr_values and login_hintparameters are described in more detail below.

acr_values

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

NameValuesDescription
sbid_app_redirectmyapp://redirectPossibility to apply the app redirect URL that you have added to the allowlist in the Dashboard Configuration page.
sbid_initial_flowDETECT, APP_LAUNCH or REMOTE_FLOWControls which authentication flow should be presented first to the user:
- DETECT automatically determines if the user is on a mobile or a desktop device, and presents APP_LAUNCH or REMOTE_FLOW respectively. This is the default behaviour.
- APP_LAUNCH launches the BankID app locally.
- REMOTE_FLOW presents the QR code flow.
sbid_require_mrtdtrue or falseSetting this parameter to true, will enforce the end-user to do an additional confirmation with either their Swedish ID-Card or their Swedish passport. This should be used in transactions where extra security might be warranted, for example high risk transactions. For this parameter to work, you must also add the sbid-extra scope in the request. This scope includes the sbidMrtd claim. Note: You must validate that the sbidMrtd value is returned as true to prevent any tampering with the sbid_require_mrtd parameter. For feature details, see the About page > MRTD.
sbid_auth_typeNORMAL or PHONEControls which type of flow is started for Swedish BankID:
- NORMALlaunches the regular Authentication flow (can be further specified by sbid_initial_flow) .
- PHONE launches the Phone flow.

Notes: :
- For the Phone flow to work, you must also include sbid_phone_initiator and enable the Phone flow in the Dashboard configuration.
- It must be a "trusted" parameter (see note below this table)
sbid_phone_initiatorUSERor OPERATORDefines the default selected radio button in the first screen of the Phone flow:
- USER means the User radio button is selected as default.
- OPERATOR means the Operator button is selected as default.

Note: It must be a "trusted" parameter (see note below this table)
sbid_intention_textVGVzdCBpbnRlbnRpb24gdGV4dAo=A text specifying the intention of the authentication.

Notes:
- Must be encoded in UTF8 Base64 format.
- Max length of the Base64 encoded string: 1500 characters.

For more details, see Define intention text.
sbid_intention_text_formatsimpleMarkdownV1Defines the format of the intention text to be simpleMarkdownV1.

For more details, see Define intention text.
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.

NameDescription
ninPrefills the national identity number. The prefilled value will lock down BankID to restrict the authentication to a person with that national identity number.

Example

login_hint=nin:199002171234

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

See also

Define intention text​

You may add an intention text on the IDENTIFICATION screen of the BankID app to underline the purpose of the authentication for the end-user.

Your intention text will always be prefixed with "My intent", as shown in the following example, where the intention text is set to Log into my online banking account:

Front matching

Front matching

You may also add security related information (see a screen example in the next section).

Do not use the text space for marketing or sales

Swedish BankID does not allow using this text space for other than intention of the identification and security-related information.

You can define the intention text in two ways:

Add intention text in the Dashboard​

  1. Open the Swedish BankID configuration page in the Dashboard.
  2. Add your intention text in the Intention text input field.
Note

If the intention text is long and needs a scrollbar, the end-user must scroll to the bottom before they can proceed.

  1. Optionally, you may add formatting to the text in simple markdown format (simpleMarkdownV1). This allows you to add headings, bullets and more (for details, see Swedish BankID's guide). Here is an example text in markdown format:
Log into my online banking account

### Security note
Remember, we will never contact you directly by telephone, email or SMS to verify your identity and will never ask you to provide your passwords or codes.

If anyone contacts you directly about this, please contact us by telephone or mail:
+ 111 11 111
+ bank@bank.se

This would look as follows:

Front matching

Front matching

  1. If the intention text contains formatting, choose simpleMarkdownV1 from the Intention text format drop-down menu.

Add intention text using prefilling​

You may also add intention text per transaction by using prefilling of the two additional parameters, sbid_intention_text and sbid_intention_text_format.

Notes about prefilling
  • You cannot mix prefilled and configured (in the Dashboard) values. Prefilling will override the intention text you have defined in the Dashboard (see the above section).
  • The additional parameters must be trusted. The Authentication REST API makes this easy, since it always provides trusted parameters. For OIDC, you must use signed authorisation requests (see the general eID Hub documentation on how to do this).

To add the intention text in your integration code:

  1. Create your intention text. You may format the intention text using simple markdown format (see the above example).
  2. Encode the text into UTF-8 Base64 format. The maximum length of the the Base64 encoded string is 1500 characters.
  3. Include the Base64 encoded intention text into your request. For protocol specific setup and examples, see the separate Authentication REST API and OIDC sections.
  4. You can verify that the text looks as expected by testing a transaction in the sandbox environment.

Theming​

You can set your own theme with logo and colours in the Dashboard. For more details, see Account theming.

Last updated on