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:
- Onegini IDP instance must to be running, for the sake of this guide we assume it's available under http://idp-core.dev.onegini.me address
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.