KeyStore Handling#

The Skalio ID service uses asynchronous cryptography to sign JSON Web Tokens, whose signature can be verified by services without access to the secret. The private key necessary for the signature creation is stored in a keystore implemented by the database.

The keystore supports ECDSA and RSA keys. Necessary keys are automatically generated at application startup. Existing keys from external parties (such as Google or Apple) can be imported. Own keys are automatically rotated, whereby new keys are created and the old keys are marked as inactive.

An operator can interact with the keystore using the Skalio ID shell.

Key ID#

Each key has a unique key ID: The kid JWT header claim identifies the key that was used to sign it.

Key Alias#

Each service that Skalio ID provides authorization services for requires its own keypair, identified by a service-specific alias:

Service	Alias
Skalio ID	com.skalio.id
Sign in with Google	oidc.google.spaces
Sign in with Apple	oidc.apple.spaces

skalio-id> dbkeystore list
List of all keys managed by the database

Active | Alias                          | KeyId                | Type | Pri | Pub | Created at           | Expires at
-------------------------------------------------------------------------------------------------------------------------------
  X    | com.skalio.id                  | qysxg8fqxoolf54r     | EC   |  X  |  X  | 2023-06-29T13:10:09  | 2023-08-13T13:10:09
  X    | oidc.google.spaces             | 58828694b81e2a5fd... | RSA  |  X  |     | 2023-07-27T09:33:26  | --not set--
-------------------------------------------------------------------------------------------------------------------------------

Key Rotation#

Skalio ID automatically rotates the keys it uses to sign ID tokens from time to time. As part of this process, a new private/public keypair is generated with the same key alias but a unique key ID. The new key is marked active, while all previous keys of the same alias are marked as inactive.

Inactive keys are kept for a while to allow signature verification of older ID tokens, until they are automatically expired.

Key rotation can be executed manually as well. This may be helpful to isolate an exposed private key.

skalio-id> dbkeystore rotate
Key rotation

This command creates a new key in the database-managed keystore. The new key is
automatically activated, replacing the previous active key for the same alias.
Future cryptographic operations will use the newly created key. While the alias
remains the same, the key-ID changes.
The previous active key remains in the database until it expires. While it is no
longer used to sign tokens, it can still verify existing tokens.

While it is safe to run this command at any time, note that automatic key rotation
is implemented using a scheduled job (see `scheduler info` for details).

Select key alias > com.skalio.id
Confirm (y/N)? y
Successfully rotated key. New key: KeyPair{keyId='-sljj.vz7jdrl27e', alias='com.skalio.id'}
skalio-id> dbkeystore list
List of all keys managed by the database

Active | Alias                          | KeyId                | Type | Pri | Pub | Created at           | Expires at
-------------------------------------------------------------------------------------------------------------------------------
       | com.skalio.id                  | qysxg8fqxoolf54r     | EC   |  X  |  X  | 2023-06-29T13:10:09  | 2023-08-13T13:10:09
  X    | com.skalio.id                  | -sljj.vz7jdrl27e     | EC   |  X  |  X  | 2023-07-27T12:01:53  | 2023-09-10T12:01:53
  X    | oidc.google.spaces             | 58828694b81e2a5fd... | RSA  |  X  |     | 2023-07-27T09:33:26  | --not set--
-------------------------------------------------------------------------------------------------------------------------------

Keypair Creation#

The service will automatically ensure that for all configured key-aliases an active, not-expired keypair exists. The operator is not required to create keys manually.

Importing private keys#

External parties such as Apple and Google provide private keys during the onboarding of Open ID Connect. These keys are necessary when interacting with these parties:

• Google: registering an OIDC RISC endpoint
  • RSA private key, in a JSON-document, containing keyId
• Apple: calculating the OIDC Client Secret
  • ECDSA private/public keypair, in a .P8 file
  • Note: the keyId must be copied from the Apple developer console

The keys can be imported into the keystore. Note: imported keys are not rotated and don't expire!

skalio-id> dbkeystore import
KeyStore import tool

You can import private keys from different sources into the database-powered keystore.
The following sources are supported:
- a Java KeyStore file
- a PKCS#8 .p8 file, containing a PEM encoded private key
- a JSON file, containing a PEM encoded private key
Apple typically issues keys in .p8 files. Google typically issues keys in JSON files.

Select import source > json

Importing a Json file
Typically these files are issued by Google's Cloud Console and contain a RSA private key.

Select file > /etc/skalio-id/novospace-test-58828694b81e.json
Select algorithm [RSA] >
Key ID (from JSON): 58828694b81e2a5fd9f05c7d1eb30ff312d0b815
Successfully read the private key!

Enter required alias of the key entry > oidc.google.spaces

Key alias : oidc.google.spaces
Key ID    : 58828694b81e2a5fd9f05c7d1eb30ff312d0b815
Format    : PKCS#8
Algorithm : RSA
Import key into keystore (y/N)? y
Success! Key has been imported.