The BankID consentor provides the ability for the users to sign the consent attributes using the Swedish BankID. It is possible to configure the consentor to use a test or a production version of BankID.
The consentor has to integrate with the BankID in order for the user to use it and sign the consent attributes. Curity Identity Server uses the BankID API to integrate directly and for that reason a client certificate is needed. The certificate can be obtained from any authorized bank or reseller when the consentor is used in production. For testing purposes, you may use a test key available from BankID.
Fig. 152 BankID integration overview
In order to sign the consent data, the user has two possible options. The first option is to sign on the same device by clicking on the link shown on the consentor form. That will start the native BankID application on the same device, and will let the user sign the data that they consent to. If the user wants to sign on another device, this feature is provided by scanning the QR Code shown on the consentor form.
As mentioned above, if the BankID application is not installed on the current device, the user can scan the code using their BankID application on the device where it is installed, and carry on the signing from there, without entering personal number to the Curity Identity Server.
By configuring personal-number-attribute-path, the consentor can tie the QR code to a specific personal number. The attribute path corresponds to an attribute path inside the subject attributes from authentication, so configuring subject would give you the authenticated subject. Configuring attributes.personalNumber would expect the subject attributes to contain an object attributes, with an entry of personalNumber.
personal-number-attribute-path
subject
attributes.personalNumber
attributes
personalNumber
The consentor will throw an exception if it can’t find a personal number, or if it finds an invalid personal number. If using a username authenticator to prompt the user for a personal number, it is recommended to add a request validation procedure to make sure the personal number is valid before passing on to the consentor.
A typical configuration would be:
YYYMMDDXXXX
There is an option to cancel the signing of the consent data. That is feasible either via clicking on the cancellation button or cancel via the BankID application. That option will cancel signing and return an error message to the client indicating that the user cancelled the signing process.
The configuration for the BankID consentor is described in the section Profile configuration. This section describes the configuration parameters that are available for the BankID consentor.
Important
Consentor base is /profiles/profile{id type}/settings/authorization-server/consentors
List Entry: <consentor_base>/consentor/ (key id)
type http-client-ref
mandatory
It is important that this client trust the CA used to sign BankID’s SSL certificate. This can be obtained using the SSL Server Trustore dialog, or if the admin UI is not available, openssl can be used. To obtain the CA certificate of BankID’s production SSL certificate, this command can be executed:
SSL Server Trustore
$ openssl s_client -showcerts -connect appapi2.bankid.com:443 </dev/null
See below for information about how to configure this certificate to be trusted.
test
production
type enumeration
default production
The BankID consentor uses the token-issuer and text-to-display parameters which are described in Consentors section. The former is used to generate the JWT containing the consent attributes and the text-to-display. The latter is a human readable representation of the content that user is about to sign.
Being more specific, the request to the BankID will contain the JWT as the userNonVisibleData, thus it will not be rendered in the BankID application. That request field is the actual value that will get signed and returned from the BankID application. The text-to-display is the content that will be shown on the BankID application while the user is signing. Thus, the request sent to BankID servers will contain the text-to-display as the userVisibleData.
use-markdown-format: BankID API also supports the Markdown format for presenting the text-to-display content within the BankID application. The format instructions could be find from BankID Developer Guides section Formatting.
<consentor> <id>bankidConsentor</id> <description>consentor1</description> <signing-consentor> <token-issuer>ConsentorTokenIssuer</token-issuer> <text-to-display-procedure>ZnVuY3Rpb24gcmVzdWx0KGNvbnRleHQpIHsKICByZXR1cm4gInRleHQtdG8tZGlzcGxheSI7Cn0=</text-to-display-procedure> <bankid-signing-consentor xmlns="https://curity.se/ns/ext-conf/bankid-signing-consentor"> <mode>test</mode> <http-client> <id>bankid-client</id> </http-client> </bankid-signing-consentor> </signing-consentor> </consentor>
After configuring the Curity Identity Server for production mode, it can be used with any production BankID. For test, a test BankID credential needs to be setup on a device. How to do this is described below.
The outcome of the BankID signing consentor is persisted in the form of Attributes (as described in the SDK documentation). The response is persisted along with the delegation and contains several fields returned from BankID.
These Attributes consist of:
OCSP - Online Certificate Status Protocol (OCSP). Name - the signing person’s name. User - the signing person’s details. personalNumber - the Swedish personal number of the person signing. name - the signing person’s full name. givenName - the signing person’s first name. surname - the signing person’s surname. device - details about the signing device. ipAddress - the IP address of the signing device. Personal Number - the Swedish personal number of the person signing. Signature - XML signature of the JWT previously referred also as userNonVisibleData.
For more information on the values returned from BankID, please consult the corresponding documentation BankID developer guide.
To test the integration with BankID using the test service provided by BankID, the mode configuration setting must be set to test. Otherwise, the Curity Identity Server will attempt to contact the production BankID servers. It will not be able to authenticate to this service using a test certificate, and authentication will fail. With the mode set correctly, an HTTP client that refers to one that uses client authentication should be configured. If this key is the test certificate provided by BankID, integration should work as expected and user authentication should succeed.
mode
For more information about testing BankID, refer to the BankID developer portal. That web site has information about obtaining a test BankID, installing BankID on Android, iOS, and other details.
Warning
A test BankID and a production BankID cannot be used on the same device. If a test BankID is installed on a device, the regular one that is used for personal reasons will be cleared. Therefore, it is recommended that testing occurs on a separate device.
If required, it is possible to configure Curity to save the BankID responses. This can be helpful for audit or regulatory purposes. If this is needed, make the following changes to the $IDSVR_HOME/etc/log4j2.xml file which controls how logging is performed:
$IDSVR_HOME/etc/log4j2.xml
Add a new appender to the <Appenders> section, like this:
<Appenders>
<RollingFile name="bankid-log" fileName="${env:IDSVR_HOME}/var/log/bankid.log" filePattern="${env:IDSVR_HOME}/var/log/bankid.log.%i.gz"> <RegexFilter regex=".*COMPLETE.*" onMatch="ACCEPT" onMismatch="DENY"/> <Policies> <SizeBasedTriggeringPolicy size="1GB"/> </Policies> <PatternLayout pattern="<message time="%date{yyyy-MM-dd'T'HH:mm:ss:SSSZ}">%msg</message>%n"/> </RollingFile> This will cause a new file to be created in the $IDSVR_HOME/var/log directory named bankid.log. This will be rolled after the file grows beyond one GB. If preferred, a different kind of Log4j appender can be used instead. By using the RegexFilter, the only BankID-related messages that will be logged are those that contain the word COMPLETE. These are the final responses from BankID after a user successfully logs in. The appender described above is also valid and can be created for the authenticators running on the the Curity Identity Server. That said, if an appender has already been created for an authenticator, that can be reused for the consentor as well. In that case, a new AsyncLogger can be created using the same appender as any already existing authenticator.
<RollingFile name="bankid-log" fileName="${env:IDSVR_HOME}/var/log/bankid.log" filePattern="${env:IDSVR_HOME}/var/log/bankid.log.%i.gz"> <RegexFilter regex=".*COMPLETE.*" onMatch="ACCEPT" onMismatch="DENY"/> <Policies> <SizeBasedTriggeringPolicy size="1GB"/> </Policies> <PatternLayout pattern="<message time="%date{yyyy-MM-dd'T'HH:mm:ss:SSSZ}">%msg</message>%n"/> </RollingFile>
This will cause a new file to be created in the $IDSVR_HOME/var/log directory named bankid.log. This will be rolled after the file grows beyond one GB. If preferred, a different kind of Log4j appender can be used instead. By using the RegexFilter, the only BankID-related messages that will be logged are those that contain the word COMPLETE. These are the final responses from BankID after a user successfully logs in.
$IDSVR_HOME/var/log
bankid.log
RegexFilter
COMPLETE
The appender described above is also valid and can be created for the authenticators running on the the Curity Identity Server. That said, if an appender has already been created for an authenticator, that can be reused for the consentor as well. In that case, a new AsyncLogger can be created using the same appender as any already existing authenticator.
In the Loggers section of the same file, add a new logger like this:
Loggers
<AsyncLogger name="io.curity.identityserver.plugin.bankid.BankidSigningConsentor" additivity="false" level="TRACE"> <AppenderRef ref="bankid-log"/> </AsyncLogger> The key here is the name of the logger. Be aware that the name of the logger is subject to change, and should be verified to continue working in future versions. The additivity attribute value ensures that the messages from the BankidSigningConsentor logger are not also handled by any other loggers. The level must be TRACE or the BankID Web service messages will not be logged.
<AsyncLogger name="io.curity.identityserver.plugin.bankid.BankidSigningConsentor" additivity="false" level="TRACE"> <AppenderRef ref="bankid-log"/> </AsyncLogger>
The key here is the name of the logger. Be aware that the name of the logger is subject to change, and should be verified to continue working in future versions. The additivity attribute value ensures that the messages from the BankidSigningConsentor logger are not also handled by any other loggers. The level must be TRACE or the BankID Web service messages will not be logged.
additivity
BankidSigningConsentor
TRACE
This will cause sensitive, personally identifiable information (e.g., personal number, IP address, name, etc.) to be logged. Also, this additional logging could negatively impact performance; the use of an asynchronous logger will help mitigate this, but the impact of the change should be verified before deploying it.