Signing and encryption

Signed JWTs (JWS) are crucial to the OpenID Connect specification in order to ensure the authenticity and integrity of data exchanged between parties.

Encrypted JWTs (JWE) are also used to encrypt sensitive data when applicable. Cryptographic keys used for this purpose are published in the JWKs endpoint as JWKs. Note that these keys may change over time.

When integrating BankID over OpenID Connect you must always validate Tokens that are issued. You should also strongly consider encrypting sensitive data using encrypted request objects.

Validation of Signed Tokens

Following well established OpenID Connect standards, BankID will sign all Tokens issued:

• ID Tokens
• Access Tokens
• Refresh Tokens
• Userinfo response Token

You must validate JWT signatures and ensure that the signing key certificate was issued by the officially published root certificate.

Keys used for signing are all marked with "use": "sig".

Steps to validate a signed JWT Token

The steps required to securely validate a JWS Token (like ID Token):

1. Extract the key information from the JWS Token header: kid, alg 
2. Retrieve all JWK entries that BankID exposes from the JWKs endpoint.
3. Keys used for signing can be filtered by the use attribute on each JWK. This value should be sig.
4. Find the key used to sign the JWS Token by matching the kid, alg from (1) with the JWK entries.
5. Extract the public key and certificate chain (x5c) from the JWK entry.
6. Validate the origin of the key by verifying it's complete certificate chain (x5c) with our published root certificate.
7. Validate the JWS token using the key.

Note: Using a secure and community provided library to validate JWS tokens is highly recommended.

Signed Authorization Requests

BankID OIDC can support signing incoming Authorization Requests:

• request authorize parameter
• private_key_jwt client_assertion object

To support this, a jwks_uri must be registered for the given merchant (OIDC Client), so BankID can retrieve validation keys. 

Contact us for more information.

Encrypted Authorization Requests 

BankID supports encryption of incoming Authorization Requests through:

• request authorize parameter 
• login_hint encryption (deprecated)

This can be useful in order to ensure personal information is not leaked in the browser history or URL (for example through login_hint).

The login_hint encryption is deprecated as it is being replaced by the encrypted request parameter.

Keys used for encryption in JWKs are all marked with "use": "enc".

Encrypted request parameter (recommended)

Steps to encrypt a request object

1. Generate a random content encryption key.
2. Encrypt the content encryption key using the appropriate public key from our JWKs endpoint.
3. Encrypt the request object using the content encryption key.
4. Create the JWT with the encrypted content and key.
5. Send the encrypted JWT as value in the request parameter in the Authorization Request.

Note: Using a secure and community provided library for your chosen platform is highly recommended.

Encrypted login hint (deprecated)

The encrypted login_hint should be formatted as a JWE Compact Serialization. The ciphertext is the encrypted plaintext login_hint.

A typical login hint:

login_hint=BID:14025800177

 will using the encryption key in the JWK example, be:

The header part of the JWE object is in this case:

{
  "epk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "cJmWMkkqyVP6-lW2kxhHITdnh6Du2CsRIYg0ckyWuWA",
    "y": "Til4N0YF5aR6rIQjGF68qddCf_p2nVbB3TLce6l3qVY"
  },
  "kid": "encryptkey",
  "enc": "A128GCM",
  "alg": "ECDH-ES"
}

BankID OIDC provider will use the kid value to extract the correct key for decryption. If the kid value is not set, the decryption will fail.

The message to be encrypted is not JSON, it is simply:

BID:14025800177