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:

*) 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

Adapter configuration properties

The following configuration properties can be set using the configuration prefix:

ubisecure:
  sso:
    bankid:
      sweden:

Note that these parameters can be also supplied via the command line. See Spring Boot, Externalized configuration for more details.

Example User Certificate Policy

PKI Policy configuration file with Test BankID Root CA certificate as trust anchor and attributes user_certificate_cn and user_certificate_issuer_cn.

<Policy xmlns="http://ubisecure.com/schema/certagent.xsd">
  <PKI>
    <!-- CN=Test BankID Root CA v1 Test,OU=BankID Member Banks CA,O=Finansiell ID-Teknik BID AB -->
    <Trust>
MIIF0jCCA7qgAwIBAgIISpGbuE9LL/0wDQYJKoZIhvcNAQENBQAwbTEkMCIGA1UE
CgwbRmluYW5zaWVsbCBJRC1UZWtuaWsgQklEIEFCMR8wHQYDVQQLDBZCYW5rSUQg
TWVtYmVyIEJhbmtzIENBMSQwIgYDVQQDDBtUZXN0IEJhbmtJRCBSb290IENBIHYx
IFRlc3QwHhcNMTEwOTIyMTQwMTMzWhcNMzQxMjMxMTQwMTMzWjBtMSQwIgYDVQQK
DBtGaW5hbnNpZWxsIElELVRla25payBCSUQgQUIxHzAdBgNVBAsMFkJhbmtJRCBN
ZW1iZXIgQmFua3MgQ0ExJDAiBgNVBAMMG1Rlc3QgQmFua0lEIFJvb3QgQ0EgdjEg
VGVzdDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANPXoOB9BQOW8i2C
Kk7U/d8rFNB0ktVlcgBSh8CKvnTsW3i+NrAM5LY9jgAO9vkHT3bl3nK626zePhmh
dhVXMKAanbcF/NJ/oSF+DKCGx/VgPmCCqVyTMLjID/59diiLg3xNH3NaaBM69qnw
5yOCYkB2wXxcATLO0eTxvL0vdKGJ2HU2AcEtaMMxrScuNCztPuwjYNP0KrYI+y/J
Gkf2dBhomAhDLdQSSW3zXqYgbQvJ8La2ECgo3rGQQRZG9/5MZ5dOWtpAx0ybeCbh
CPO8XIBCHrPZxv60gZK1CTwlZUoMTBSivv+vmFrH8JdmUnOP9e/wNhuM9/fQ0h5t
4BGXoz8M5nxdH6uNJG5SpdxaXYflezBb7YdjgNiF9Yqo3DYTRrZT7dyRLYqlmKQh
T1pqEov1tkXktQF8r1QJkTJO3x1QEzMNCnHyN8iDOqENSE4nhkzU9ESbXNOhFpnc
XJqoFwvbeAJpV7fVwn+Jumyc/zsD9t+1Vo1lM95q1geVPfnA5z7NZ+uaayJx4DhL
MvufDI17fqgiWHe+BMA/vGd8OjFK3JUmCV+7QeG/Z3JWbzU0GeDljqO+H4CQ0+LO
4E4JGEZtxfUu4/XuOkCqiZ4/shoPOOxaXcZlBEMHsDzei0tNSKIxB+PoDTje/BQC
lunVZvjcG2ehpeF540EXgzzECaNLAgMBAAGjdjB0MB0GA1UdDgQWBBRK96NqCNoI
OBcZUyjI2qbWNNhaujAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFEr3o2oI
2gg4FxlTKMjaptY02Fq6MBEGA1UdIAQKMAgwBgYEKgMEBTAOBgNVHQ8BAf8EBAMC
AQYwDQYJKoZIhvcNAQENBQADggIBAJVcP9Sm2tukKW0Qx8EZG9gdXfCmNMrHXF3g
via5zpuSMl9wdXHd1FPdGFshRZJ2sW4mb9vRI81vBIXMFVtLZFzeGHoKyz1g8hfj
uuLKpItw0OwVNdvSRq/TKKxjVKpvt50Eydgnz4Q59YkFlGVyi7+z74mGfvN06Ssj
2WIRtr3UD+IC6Tie6Lm/zuZs4gu0ZP/fddKh7gC3syHLNXQmN+9Y0wkdO7H98K/9
uuIrxWtSOFVatxesw7XJRnq+uYI0IdP8xP8U4S680rTse7nsTguQxzRs2vOyoaXm
Fdf7XQ03btd15Z4yJlEfs9/4ohgafMs49PMkACqyX45/4WBygO0QwMGVIUnKNFBt
/I+0T2SkWFa2JdcRCSTObb7tesoeTIPgI9UcrMvNOG3gxGpB/H5/s7jTV0AOoDgM
hOxieGgyTsZ3oP0k6bc47FJ4nE+vifAluyeXioB5JaN2kvm8eqfzC05zSF40V9GA
zElVDbsBPR/2CE6CMyR+eqip4gDSZ6mnZYPeBecEXU4Xu+RAgqYxjKosfxOpMZsN
+2BSm5QSRLhHacPQTnoQxujnGuUzh5TdAbWqmS0cKEZJ+CACmVLyOphdRoeEQCqQ
8DYAyOtq2S4+hAJW+2Xq4NCdvmjm99r2RFkibSlLtqctj1JyzUC6huUiQXx9KZ8n
FA0TsFHG
    </Trust>
  </PKI>
  <Subject KeyInfoConfirmationData="true"/>
  <Attributes>
    <Add name="user_certificate_cn">
      <Attribute source="subject" oid="2.5.4.3" />
    </Add>
    <Add name="user_certificate_issuer_cn">
      <Attribute source="issuer" oid="2.5.4.3" />
    </Add>
  </Attributes>
</Policy>

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:

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

/device/authorize

/device/token

/device/.well-known/oauth2-configuration

/v3/api-docs

/swagger-ui/

/actuator/health

/actuator/info

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:

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