Prerequisites

Install Ubisecure SSO

You can find instructions on how to install Ubisecure SSO in Installation - SSO.

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 Mobile - 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 Authentication Adapter

Installing

The Swedish BankID authentication adapter 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 application 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 application is currently deployed to the same node as Ubisecure SSO, it is suggested to secure the application using HTTPS in order to avoid leaking of sensitive information. This is especially suggested step that allows moving adapters to different servers than Ubisecure SSO. You can refer to Spring Boot Server SSL configuration instructions for more details.

Application 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 application, 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 certificates
ubisecure.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 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 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
`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 application 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

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 for more details.

Example configuration using external directory

As documented in Spring Boot External Configuration guide, one easy way to configure the application 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 application can be deployed and executed as a standalone executable as defined in Installing Spring Boot applications.

The application package includes the default Spring Boot launch script which means that on Unix based systems, you can run the application 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
`/oidc/bc-authorize`	yes	OpenID Connect CIBA backchannel authentication endpoint
`/oidc/token`	yes	OpenID Connect token endpoint with additional CIBA parameters
`/oidc/.well-known/openid-configuration`	no	OpenID Provider configuration metadata endpoint
`/oidc/jwks`	no	Exposes JWKs provided by the service
`/v2/api-docs`	no	Swagger 2.0 schema of the API
`/swagger-ui.html`	no	Swagger UI to explore the API
`/actuator/health`	no	For health checks. This only checks that the application is up and running. No external requests are made. Health check of the BankID provider is not included
`/actuator/info`	no	For application version information

Troubleshooting

Refer to this chapter for detailed information how to troubleshoot the application.

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 Ubisecure Backchannel Authentication Adapter for more details on how to configure Swedish BankID as an external authentication method to Ubisecure SSO.

Obtaining OpenID Connect Provider metadata for SSO Backchannel Authentication Adapter method configuration

The BankID service application exposes OpenID Connect Provider metadata in two forms

Well-known OpenID Connect Provider configuration
JWKS used to sign granted ID tokens

Assuming that the application is deployed to localhost for Ubisecure SSO to access, the endpoints can be accessed as follows:

Endpoint	Description
`http(s)://localhost:<port>/oidc/.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",
  "backchannel_authentication_endpoint": "http://localhost:8082/oidc/bc-authorize",
  "token_endpoint": "http://localhost:8082/oidc/token",
  "jwks_uri": "http://localhost:8082/oidc/jwks",
  "response_types_supported": [
    "id_token"
  ],
  "scopes_supported": [
    "openid"
  ],
  "id_token_signing_alg_values_supported": [
    "RS512"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ]
}

An example JWKS response:

{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "token-signing-key",
      "e": "AQAB",
      "n": "AMiqPLgjEKAvUBO6jBhq5RJgk1uCj8mWyNF-MhQipP-wb9LMehqw95VNZg3gJZs9fkrGjxWHDkNoM4H3WZT9997dlyOFJvdgtZh3iMtX-Y1356QjckpsH_AiUfvsp6CBh4OwRxHslwJfL8eV5ceYGbpn72pbOjJA5ZK6vJs82kZqvMqvrPIHSCvmoyR3x71ZmkYExE_XkuORsvmLsRIZOQJCRr1QQLK33rAfk9WWKtEzmh_0NAg5JUgtMVOW8upk_oZ-RU2gn0Bx1JqXVIcWBzguTYL-zk52V55UhsAb02rlezMjU4BY8Peiuge5_ZtnK_wiIUSuUzbjv9iGhIduYxk="
    }
  ]
}

Browser not supported