# 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 mapping for OIDC.

# 2. Control the BankID flow

Signicat provides different flow options for BankID (e.g. 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://test.sandbox.signicat.example/auth/open/connect/authorize?
client_id=dev-test-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 mapping 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:

Name Values Description
sbid_app_redirect myapp://redirect Possibility to apply the app redirect URL that you have added to the allowlist in the Dashboard Configuration (opens new window) page.
sbid_initial_flow DETECT, APP_LAUNCH or REMOTE_FLOW Controls 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_auth_type NORMAL or PHONE Controls 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 (opens new window).
- It must be a "trusted" parameter (see note below this table)
sbid_phone_initiator USERor OPERATOR Defines 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_text TG9nIGludG8gbXkgb25saW5lIGJhbmtpbmcgYWNjb3VudA== 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_format simpleMarkdownV1 Defines 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:TG9nIGludG8gbXkgb25saW5lIGJhbmtpbmcgYWNjb3VudA==

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.

Name Description
nin Prefills 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

Last updated: 14/02/2024 09:46 UTC