Table of Contents

...

Version compatibility with Ubisecure SSO and BankID Web service API version:

1

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

title	Securing HTTP connections

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.

Client authentication

...

responseTimeout

duration

no

default configuration: 5s

if not set: 30s

BankID adapter timeout when accessing the BankID server

Adapter retries request in the following cases:

both authentication initialisation and status query request once after a 500 ms delay in case the BankID server is inaccessible
in authentication initialisation 3 times with minimum delay of 300 ms and exponential backoff strategy if the BankID server responds with service temporary unavailable error

Therefore, if you configure responseTimeout > 5s you should also check the value for

spring.mvc.async.request-timeout (default configuration value 1m). This value sets the timeout for a pending client (SSO) request to adapter to fail and it should cover the retry attempts.

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

title	key-aliases for Ubisecure SSO

As of Ubisecure SSO 8.4.1 the clients[n].key-aliases entry has to match to the kid published by SSO in its JWKS metadata response. See See OAuth 2.0 and OpenID Connect metadata - SSO for for more details.

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

...

On Windows, please refer to the Spring Boot installation instructions linked above.

Exposed endpoints

The application exposes the following endpoints

...

.

...

Exposed endpoints

The application exposes the following endpoints

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

...

pattern is optional and is just to tidy the output a bit.

Configuring Ubisecure SSO to use Swedish BankID

See OpenID Connect CIBA authentication method for more details on how to configure Swedish BankID as an external authentication method to Ubisecure SSO.the output a bit.

Configuring Ubisecure SSO to use Swedish BankID

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
`http(s)://localhost:<port>/device/.well-known/oauth2-configuration`	Swedish BankID provider metadata

An example OpenID Connect Provider metadata response:

Code Block

language	js

{
    "issuer": "https://sso-bankid.example.com",
    "backchanneldevice_authenticationauthorization_endpoint": "http://localhost:8082/oidcdevice/bc-authorize",
    "token_endpoint": "http://localhost:8082/oidcdevice/token",
    "jwks_uri": "http://localhost:8082/oidc/jwks",
    "response_types_supported": [
        "id_token"
    ],
    "grant_types_supported": [
        "urn:openidietf:params:modrnaoauth:grant-type:backchanneldevice_requestcode",
    "urn:openid:params:grant-type:ciba"],
  ],   "scopes_supported": [
        "openid"
    ],
    "id_token_signing_alg_values_supported": [
        "RS512"
    ],
    "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],   "backchannelprivate_token_delivery_modes_supported": [key_jwt"
    ],
"poll"   ],
  "token_endpoint_auth_signing_alg_values_supported": [
        "RS256",
        "RS512"
    ]
}

An example JWKS response:

Code Block

language	js

{
  "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="
    }
  ]
}

...

Versions Compared

Old Version 1

New Version Current

Key

Adapter configuration properties

Client authentication

Client authentication

SSO key rotation impacts BankID adapter

Exposed endpoints

Exposed endpoints

Configuring Ubisecure SSO to use Swedish BankID

Configuring Ubisecure SSO to use Swedish BankID

Obtaining OpenID Connect Provider metadata for

Swedish BankID authentication method configuration

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Adapter configuration properties

Client authentication

Client authentication

SSO key rotation impacts BankID adapter

Exposed endpoints

Exposed endpoints

Configuring Ubisecure SSO to use Swedish BankID

Configuring Ubisecure SSO to use Swedish BankID

Obtaining OpenID Connect Provider metadata for

Swedish BankID authentication method configuration