| Table of Contents |
|---|
Prerequisites
Install Ubisecure SSO
You can find instructions on how to install Ubisecure SSO in Installation - SSO.
Version compatibility with Ubisecure SSO
...
| Table of Contents |
|---|
Prerequisites
Install Ubisecure SSO
You can find instructions on how to install Ubisecure SSO in Installation - SSO.
Version compatibility with Ubisecure SSO
| BankID Adapter version | Ubisecure SSO version |
|---|---|
| 1.0.x | 8.3.x or newer* |
| 1.1.x | 8.8.x or newer |
| 2.x | 9.x or newer |
...
| Note | ||
|---|---|---|
| ||
Although the adapter is currently deployed to the same node as Ubisecure SSO (install on one node only if in HP), it is suggested to secure the adapter by configuring it to use HTTPS in order to avoid exposing of sensitive information. This suggested step allows moving adapters to different servers than Ubisecure SSO. You can refer to Spring Boot Server SSL configuration instructions for more details. |
Adapter configuration properties
The following configuration properties can be set using the configuration prefix:
...
| Property | Type | Required | Default | Description | |||
|---|---|---|---|---|---|---|---|
default-polling-interval | integer | no | 5 | The polling interval returned to the client, i.e. Ubisecure SSO | |||
default-request-expiration | integer | no | 600 | The number of seconds when requests expire | |||
url | string | no | https://appapi2.bankid.com | The base URL to the BankID service provider API. This URL is defined in the BankID Relying Party Guidelines | |||
auth.certificate-policies | string array | no | 1.2.752.78.1.5 | The BankID certificate policy requirements. Defaults to Mobile BankID app only. See BankID Relying Party Guidelines for more detailsmore details | |||
id-token.issuer | string | yes | The issuer of the ID token granted by the service | ||||
id-token.signing-key-alias | string | yes | The alias of the ID token signing key-pair in the key store | ||||
id-token.issuersigning-key-password | string | yes | The issuer password of the ID token granted by the servicesigning key-pair | ||||
id-token.signing-key-alias | string | yes | The alias of the ID token signing key-pair in the key store | id-token.signing-key-password | string | yes | The password of the ID token signing key-pair |
id-token.expiration | int | no | 600 | The time in seconds after which ID tokens granted by this service expire. Note: Ubisecure SSO does not permit ID tokens that have expiration greater than 1 hour. | |||
request-id.token-issuer | string | no | sso-bankid | The issuer of auth_req_id JWTs | |||
request-id.key-id | string | no | (random uuid) | The id of the key used to sign auth_req_id JWTs. kid will be set to this value | key-store.path | string | yes | The path to the key store where BankID key entries reside | key-store.password | string | yes | The password of the key store |
key-store.type | string | no | PKCS12 | The type of the key store | key-store.authentication-key.alias | string | yes | The alias of the BankID client authentication key in the store | key-store.authentication-key.password | string | yes | The password of the BankID client authentication private key | key-store.server-certificate.alias | string | yes | The alias of the BankID server certificate |
Note that these parameters can be also supplied via the command line. See Spring Boot, Externalized configuration for more details.
Client authentication
In order to secure the adapter from unauthorized clients, client authentication is based on OpenID Connect Core chapter 9, Client authentication. Both, the /bc-authorize and /token endpoints are secured. Currently, only private_key_jwt method is supported.
OpenID Connect clients are configured using application properties with the following prefix
| Code Block |
|---|
ubisecure:
sso:
oidc: |
The following configuration properties for clients can be used:
...
| title | key-aliases for Ubisecure SSO |
|---|
...
expiration | int | no | 600 | The time in seconds after which ID tokens granted by this service expire. Note: Ubisecure SSO does not permit ID tokens that have expiration greater than 1 hour. |
request-id.token-issuer | string | no | sso-bankid | The issuer of auth_req_id JWTs |
request-id.key-id | string | no | (random uuid) | The id of the key used to sign auth_req_id JWTs. kid will be set to this value |
key-store.path | string | yes | The path to the key store where BankID key entries reside | |
key-store.password | string | yes | The password of the key store | |
key-store.type | string | no | PKCS12 | The type of the key store |
key-store.authentication-key.alias | string | yes | The alias of the BankID client authentication key in the store | |
key-store.authentication-key.password | string | yes | The password of the BankID client authentication private key | |
key-store.server-certificate.alias | string | yes | The alias of the BankID server certificate |
Note that these parameters can be also supplied via the command line. See Spring Boot, Externalized configuration for more details.
Client authentication
In order to secure the adapter from unauthorized clients, client authentication is based on OpenID Connect Core chapter 9, Client authentication. Both, the /bc-authorize and /token endpoints are secured. Currently, only private_key_jwt method is supported.
OpenID Connect clients are configured using application properties with the following prefix
| Code Block |
|---|
ubisecure:
sso:
oidc: |
The following configuration properties for clients can be used:
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
trust-store.path | string | yes | The path to the key store where client public key certificate entries reside | |
trust-store.type | string | no | PKCS12 | The type of the client key store |
trust-store.password | string | yes | The password of the key store | |
clients | object array | yes | An array of client objects. Each client having its own entry | |
clients[n].id | string | yes | The client_id of the OpenID Connect client | |
clients[n].key-aliases | string array | yes | The aliases of client specific public key certificates stored in the key store denoted by ubisecure.sso.oidc.trust-store. If the client defines the kid JWT header, that is expected to be found in the key store. If the client is not setting kid JWK header, then each alias in this configuration is used to test for a matching key. |
| Info | ||
|---|---|---|
| ||
As of Ubisecure SSO 8.4.1 the |
SSO key rotation impacts BankID adapter
If you implement key rotation for SSO servers then you need to update the trusted certificates for the BankID adapter when the active key used for signing is changed in SSO. More information about key rotation and how to determine the active key in Key rotation - SSO.
When you are using certificates signed by an authority (CA) you can add the certificates you get from the CA to your adapter's trust store using the kid as an alias.
If you are using keys generated by SSO then you need to read the certificates directly from Ubilogin Directory.
Keys are stored in base64 encoded PKCS12 keystores in ubiloginPKCS12 attribute of the ubiloginKeyCredential objects.
The DNs for ubiloginKeyCredential objects used by the server can be found from the ubiloginKeyCredentialDN attribute values in cn=Server,ou=System,cn=Ubilogin,<LDAP suffix> entry.
After adding the certificates to the trust store modify application configuration to include the new kid in clients[n].key-aliases list.
Example configuration using external directory
...