BankIDAuthenticator
Note
Authenticate or Sign using BankID. Depending on the method used the user may need to enter the personal number.
BankID authenticator allows for three different scenarios:
- Starting BankID on the same device.
- Starting BankID on another device(only v5.1).
- Starting BankID using a QR code.
Every method needs to be activated through configuration.
Translate userVisibleData by adding keyword "bankid.translated.userVisibleData" to this field and update language files with the keyword and translations.
Authentication mode is always the default. To use signature mode, the authentication must be for SAML and the AuthnRequest must contain a SignMessage. The "userVisibleData" for this BankID transaction will then be overridden and set to the value of the SignMessage. You can disable signatures completely by setting the configuration parameter "allowSignTransactions" to "false".
On successful authentication or signature, these parameters will be added to the request sent to the connected pipe:
- userPersonalNumber - The end user personal number (SSID)
- userGivenName - The end user given name
- userSurName - The end user family name
- bid_signature - The signature created in the bankID client during the authentication
- risk - The risk returned from the bankID transaction
Properties
| Name | Description | Default value | Mandatory |
|---|---|---|---|
| pipeID | ID of the pipe to be executed on successful authentication | N/A | Yes |
| keyStore | ID of the key store used to communicate with BankID backend | N/A | Yes |
| mode | If connecting to BankID test backend set this value to "test". | N/A | No |
| version | The version of the bankId-api to use | v6.0 | No |
| userVisibleData | A text that is displayed to the user during authentication with BankID. | No | |
| userVisibleDataFormat | If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters | No | |
| userNonVisibleData | Data not displayed to the user. String | No | |
| requirement | Requirements on how the auth order must be performed. Json format. | No | |
| client_ip_request_param | The parameter of the http client request holding the value of the requesting client | remoteAddress | No |
| certificatePolicy | A comma sepearated string of BankdID policies. If this variable is used all other requirements will be ignored(use requirements attribute below if other settings is required) | N/A | No |
| allowSignTransactions | Whether or not to allow BankID sign transactions to be started if an incoming request contains a SignMessage. | true | |
| returnUrl | BankID returnUrl parameter. Will be used to redirect the user after finished authentication. Will override any other return url set by the initiating client. | No | |
| useWeb | Whether to sent BankID web parameter. Configured referringDomain will be used, together with a cookie based deviceIdentifier and the User-Agent header. Read more on BankID official documentation. |
false | No |
| referringDomain | The BankID referringDomain parameter sent within web. This should be the domain URL of the PAS server. Read more on BankID official documentation. |
No | |
| customReturnUrls | Custom return urls to be used, read more here. | No | |
| allowedModes | Which authenticator modes are allowed to be used. Possible values are 'deviceApp' and 'qrCode', and recommended is to allow both. | deviceApp, qrCode | No |
| timeoutMinutes | Amount of minutes before the transaction expires and a manual restart is needed. Recommended to be at least 5 for accessibility. | 10 | No |
Requirements
The requirement parameter is used to describe how a signature must be created and verified. Add a json(escaped as String) containing one or more of the attributes below to the authenticators configuration.
| Name | Description | Default value | version |
|---|---|---|---|
| pinCode | New in v6.0. Users are required to sign the transaction with their PIN code, even if they have biometrics activated. | false | v6.0 |
| allowFingerprint | Removed in v6.0. Users of iOS and Android devices may use fingerprint for authentication and signing if the device supports it and the user configured the device to use it. | true for authentication. false for signing. | v5.1 |
| mrtd | Boolean. If present, and set to "true", the client needs to provide MRTD (Machine readable travel document) information to complete the order. Only Swedish passports and national ID cards are supported. | false | v6.0 |
| certificatePolicies | The oid in certificate policies in the user certificate. List of String. | N/A | v6.0 and v5.1 |
| issuerCn | The cn (common name) of the issuer. List of String. | N/A | v5.1 |
| cardReader | "class1" or "class2 determines that a cardReader must be used and a Pin code must be entered. See BankID documentation for further information. | no cardReader is required | v6.0 and v5.1 |
| risk | The accepted risk level of the transaction. Either "low" or "moderate". See BankID documentation for further information. | v6.0 |
Example Configuration
{
"id": "bid",
"alias": "bid",
"name": "BankIDAuthenticator",
"configuration": {
"pipeID": "pipeBID",
"keyStore": "bankidkeystore",
"mode": "test",
"version": "v6.0",
"allowedModes": ["qrCode", "deviceApp"],
"requirement": "{\"certificatePolicies\":[\"1.2.3.4.5\"], \"mrtd\": false}",
"userVisibleData": "*This is visible in the BankID application*",
"userVisibleDataFormat": "simpleMarkdownV1"
}
}
Requirements
- A BankID key store issued by an authorized issuer
- The user must have activated BankID prior to authenticating