| Table of Contents |
|---|
...
Version compatibility with Ubisecure SSO and BankID Web service API version:
| BankID Adapter version | Ubisecure SSO version | BankID API version |
|---|---|---|
| 1.0.x | 8.3.x or newer* | 5 |
| 1.1.x | 8.8.x or newer | 5 |
| 2.x | 9.0.x - 9.3.x | 5.1 |
| 3.x | 9.4.x or newer | 6.0 |
*) Ubisecure SSO 8.4.1 requires specific key id configuration (see Client authentication for more details)
...
The application can be configured as described in Spring Boot, Externalized configuration. I.e. you can either use properties files or YAML files, YAML being the preferred option.
...
When deploying the application, in addition to Spring Boot common configuration properties, the following properties can be used to configure the application
...
| 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 Guidelinese.g. Environments (bankid.com) |
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 /auth (bankid.com) for more 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.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.
| duration | no | default configuration: 5s if not set: 30s | BankID adapter timeout when accessing the BankID server Adapter retries request in the following cases:
Therefore, if you configure
|
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 /device/bc-authorize and /device/token endpoints are secured. Currently, only private_key_jwt method is supported.
...
| Info | ||
|---|---|---|
| ||
As of Ubisecure SSO 8.4.1 the |
SSO key rotation impacts BankID adapter
...
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.
...
The adapter can be deployed and executed as a standalone executable as defined in Installing Spring Boot applications.
The adapter package includes the default Spring Boot launch script which means that on Unix based systems, you can run the adapter as an executable
...
| Endpoint | Secured | Description |
|---|---|---|
/device/authorize | yes | BankID device authentication endpoint |
/device/token | yes | BankID device token endpoint with specific BankID parameters |
/device/.well-known/oauth2-configuration | no | BankID provider configuration metadat metadata endpoint |
/v3/api-docs | no | Swagger 3.0.1 schema of the API |
/swagger-ui/ | no | Swagger UI to explore the API |
/actuator/health | no | For health checks. This only checks that the adapter is up and running. No external requests are made. Health check of the BankID provider is not included |
/actuator/info | no | For adapter version information |
...
See Swedish BankID method for more details on how to configure Swedish BankID as a same device flow external authentication method to Ubisecure SSO.
Obtaining OpenID Connect Provider metadata for
...
Swedish BankID authentication method configuration
The BankID service adapter exposes OpenID Connect Provider metadata in two forms
...
| Endpoint | Description | |
|---|---|---|
http(s)://localhost:<port>/oidcdevice/.well-known/openid-configuration | OpenID Connect Provider metadata | |
http(s)://localhost:<port>/oidc/jwks | ID Token signing keys and issuer metadata |
An example OpenID Connect Provider metadata response:
| Code Block | ||
|---|---|---|
| ||
{
"issuer": "https://sso-bankid.example.com",
"device_authorization_endpoint": "http://localhost:8082/device/authorize",
"token_endpoint": "http://localhost:8082/device/token",
"jwks_uri": "http://localhost:8082/oidc/jwks",
"response_types_supported": [
"id_token"
],
"grant_types_supported": [
"urn:ietf:params:oauth:grant-type:device_code"
],
"scopes_supported": [
"openid"
],
"id_token_signing_alg_values_supported": [
"RS512"
],
"token_endpoint_auth_methods_supported": [
"private_key_jwt"
],
"token_endpoint_auth_signing_alg_values_supported": [
"RS256",
"RS512"
]
}
|
An example JWKS response:
| Code Block | ||
|---|---|---|
| ||
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "sso-bankid-id-token-signing-key",
"e": "AQAB",
"n": "AMiqPLgjEKAvUBO6jBhq5RJgk1uCj8mWyNFAMiqPLgjvUEKABO6jBhq5RJgk1uCj8mWyNF-MhQipP-wb9LMehqw95VNZg3gJZs9fkrGjxWHDkNoM4H3WZT9997dlyOFJvdgtZh3iMtX-Y1356QjckpsH_AiUfvsp6CBh4OwRxHslwJfL8eV5ceYGbpn72pbOjJA5ZK6vJs82kZqvMqvrPIHSCvmoyR3x71ZmkYExE_XkuORsvmLsRIZOQJCRr1QQLK33rAfk9WWKtEzmh_0NAg5JUgtMVOW8upk_oZ-RU2gn0Bx1JqXVIcWBzguTYL-zk52V55UhsAb02rlezMjU4BY8Peiuge5_ZtnK_wiIUSuUzbjv9iGhIduYxk="
}
]
} |
...