Configure JWT Keys

The Onegini IDP has a built in mechanism for generating RSA key pairs which are used for signing and encryption in OpenID Connect (OIDC) related flows. The initial keys are being generated during application startup in case ones haven't been generated yet. The Onegini IDP is also providing means for performing key rotation. This guide will walk you though the process of rotating signing and encryption keys as well as adjusting their algorithms.

What is required?

To successfully complete this topic guide you need to ensure following prerequisites:

Rotating JWT keys

The JWT key management page can be found in the Onegini IDP's admin console under System -> JWT Key Configuration tab. The configuration page consists of the following fields:

Key Use Field Required Example value Details
JWKS URI Read-only http://idp-core.dev.onegini.me/oidc/.well-known/jwks.json Location in which public OpenID Provider (OP) can find the public JWKs
Signing Algorithm Yes RS256: RSASSA-PKCS1-v1_5 using SHA-256 (default) The algorithm used for generating digital signature when PrivateKey JWT client authentication is used
Signing Next key Read-only db5aac2e-504b-4845-8900-4d64d2afd3ad Identifier of the Next key
Signing Current key Read-only 59b04937-7a12-4ff7-9d27-67b55637da9f Identifier of the Current key. This is the key identifier KID that should be used when validating the PrivateKey JWT signature by the OP.
Signing Previous key Read-only a1328084-d75d-4ea7-a734-fe5257a5faff Identifier of the Previous key. This field is empty upon initial creation of the keys.
Encryption Algorithm Yes RSA_OAEP_256: RSAES using Optimal Asymmetric Encryption Padding (OAEP) with SHA-256 (default) The algorithm that should be used by the OP for encrypting the id token and user-info
Encryption Next key Read-only 32ead22b-dd56-4907-9de3-6e2c769bb5c1 Identifier of the Next key
Encryption Current key Read-only 9f1849e4-d894-448d-90f2-82bbe770ee49 Identifier of the Current key. This is the key identifier KID that should be picked by the OP for encryption.
Encryption Previous key Read-only f3d933e3-b3e1-424c-82e0-3b5366c5cf2c Identifier of the Previous key. This field is empty upon initial creation of the keys.

The Next key and Current key for signing and encryption are generated during initial application startup.

For the security reasons it is advised to periodically change (rotate) the keys. To ensure that the OpenID Provider (OP) is able to communicate with the Onegini IDP playing the role of the Relaying Party (RP), the Onegini IDP provides the following key rotation mechanism: upon clicking Rotate Keys button, the Current key becomes the Previous key, the Next key becomes the Current key and the Next key is generated. The mechanism works in a same way for both signing and encryption keys.

When modifying the algorithm, it requires the change of the underlying keys. As part of the change, the keys are rotated in a slightly different way: the Current key becomes the Previous key and two new keys are generated - the Current key and the Next key.

Currently, the Onegini IDP supports only keys from RSA family, the key length can be configured globally via the following property:

IDP_RSA_KEY_LENGTH=2048

The default RSA key length is 2048 bits.