# 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://<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 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: - `NORMAL`launches 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`	`USER`or `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

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

← Overview SAML 2.0 →