Prerequisites
Install Ubisecure SSO
You can find instructions on how to install Ubisecure SSO in Installation - SSO.
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)
Install Java Runtime Environment
You can find instructions on how to install a JRE in Linux single node installation - SSO or Windows single node installation - SSO whichever is you preferred OS.
Obtain BankID related certificates
As discussed in Swedish BankID - SSO before acting as a BankID Relying Party one has to obtain the CA root certificate for communicating with the BankID service provider and the client authentication certificate.
SSO BankID Adapter
Installing
The SSO BankID Adapter, used with Swedish BankID, is a standalone application which is deployed alongside Ubisecure SSO. It can be deployed to the same or different server. Currently, it is suggested that the adapter is deployed into the same server with Ubisecure SSO. Download the JAR file and on Linux for example, place it under
/usr/local/ubisecure/ubilogin-sso-adapters/bankid-sweden
or alternatively, on Windows
C:\Program Files\Ubisecure\ubilogin-sso-adapters\bankid-sweden
Configuration
The application is a Spring Boot application and is bundled with a web server. Therefore it runs out of the box without additional components. The application has two forms of configuration parameters
- Common server related configuration properties
- Application specific configuration properties
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.
Common configuration properties
When deploying the application, in addition to Spring Boot common configuration properties, the following properties can be used to configure the application
Property | Type | Required | Default | Description |
---|---|---|---|---|
port | string | no | 8082 | Shorthand to server.port property defining the port where the application should run |
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:
ubisecure: sso: bankid: sweden:
Remember to create trust and key stores
Before running the adapter, make sure you have generated the relevant trust and key stores storing the relevant keys and configured the relevant properties to point to these files.
ubisecure.sso.oidc.trust-store.path
for OIDC client certificatesubisecure.sso.bankid.sweden.key-store.path
for BankID service provider related certificates
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 e.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 /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 | |
| 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/authorize
and /device/token
endpoints are secured. Currently, only private_key_jwt
method is supported.
OpenID Connect clients are configured using application properties with the following prefix
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. |
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 OAuth 2.0 and OpenID Connect metadata - SSO for more details.
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
As documented in Spring Boot External Configuration guide, one easy way to configure the adapter is to store a file in a directory named config
which is located in the same directory with the application executable. So, as an example one could have a following structure:
. |-- certs | |-- bankid-cacerts | `-- client-trust-store |-- config | `-- application.yml `-- sso-bankid-sweden-authentication-adapter-service-1.0.0.jar
where application.yml
could contain something like:
ubisecure: sso: oidc: trust-store: path: 'file:certs/client-trust-store' password: 'secret' clients: - id: 'ubisecure-sso' key-aliases: - 'WtrEl8hop6_inC1OK6oTgskR668' bankid: sweden: id-token: issuer: 'https://sso-bankid.example.com' signing-key-alias: 'id-token-signing-key' signing-key-password: 'secret' key-store: path: 'file:certs/bankid-cacerts' password: 'secret' authentication-key: alias: 'bankid-auth-key' password: 'secret' server-certificate: alias: 'bankid-server-certificate'
Deployment
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
$ ./sso-bankid-sweden-authentication-adapter-service-<version> <options>
On Windows, please refer to the Spring Boot installation instructions linked above.
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 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 |
Troubleshooting
Refer to this chapter for detailed information how to troubleshoot the adapter.
Enabling debug logs
In case of more detailed debugging is needed, it is possible to enable debug level logs using the following configuration
logging: level: com.ubisecure.sso: debug pattern: console: '%clr(%d{HH:mm:ss.SSS}){faint} %clr(%-5level) %clr(${PID:- }){magenta} %clr(---){faint} %clr(%logger{0}){cyan} %clr(-){faint} %msg %n'
pattern
is optional and is just to tidy 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
- Well-known OpenID Connect Provider configuration
- JWKS used to sign granted ID tokens
Assuming that the adapter is deployed to localhost for Ubisecure SSO to access, the endpoints can be accessed as follows:
Endpoint | Description |
---|---|
http(s)://localhost:<port>/device/.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:
{ "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:
{ "keys": [ { "use": "sig", "kty": "RSA", "kid": "sso-bankid-id-token-signing-key", "e": "AQAB", "n": "AMiqPLgjvUEKABO6jBhq5RJgk1uCj8mWyNF-MhQipP-wb9LMehqw95VNZg3gJZs9fkrGjxWHDkNoM4H3WZT9997dlyOFJvdgtZh3iMtX-Y1356QjckpsH_AiUfvsp6CBh4OwRxHslwJfL8eV5ceYGbpn72pbOjJA5ZK6vJs82kZqvMqvrPIHSCvmoyR3x71ZmkYExE_XkuORsvmLsRIZOQJCRr1QQLK33rAfk9WWKtEzmh_0NAg5JUgtMVOW8upk_oZ-RU2gn0Bx1JqXVIcWBzguTYL-zk52V55UhsAb02rlezMjU4BY8Peiuge5_ZtnK_wiIUSuUzbjv9iGhIduYxk=" } ] }