Keys and secrets

Learn which keys your project signs with, rotate or disable a key without breaking your services, and see how AuthFI stores secrets.

Every project has its own signing keys. No key is shared between projects, and a private key never leaves the key service. Other parts of AuthFI ask the key service to sign, and receive a signature.

This page explains the keys a project has, what a rotation does to tokens already issued, and how secrets are kept. You manage both in KMS & Vault in the AuthFI console.

The keys a project has

A project signs four kinds of thing, each with its own key.

In the console, open KMS & Vault and the Keys tab. The keys are listed in two blocks, Token signing and Trust anchors. Each row shows the key ID, what the key signs, its algorithm, its status, its origin, when it was created, and when it was last rotated.

The public keys are published as a JSON Web Key Set (JWKS) at https://acme.authfi.io/.well-known/jwks.json. The Overview tab shows your project's JWKS URL under Signing now, with a button to copy it. Each token names the key that signed it in the kid header, so a service can pick the right key from the set.

Rotate a key

Rotation replaces a token-signing key with a new one. You rotate a key yourself, on your own schedule.

1. In the console, open KMS & Vault and the Keys tab.
2. In the Token signing block, choose Rotate on the key's row.
3. Confirm with Rotate.

The console confirms the rotation and names the key that signs now.

What happens after a rotation

The old key stays published for 24 hours, so the two keys overlap.

Nobody is signed out. A token signed before the rotation is good until it expires, and every token expires within 24 hours.

What your services must do

A service that verifies tokens keeps working through a rotation when it follows three rules.

• Find the key by kid. Never pin one key, and never assume the first key in the set.
• Fetch the key set again when you meet a kid you do not know, then cache it. Do not fetch on every request.
• Cache for hours, not days. If a token names a key you cannot find, fetch once more before you reject the token.

Disable a key

Disabling removes a key from the published set at once. Tokens it signed stop verifying as soon as verifiers fetch the set again, within 10 minutes for AuthFI's own services. Use it when a key may have been exposed.

On the Keys tab, choose Disable on the key's row, then confirm with Disable. The key signs nothing new from that moment. A disabled key is kept, and is never destroyed.

Generate a key

On the Keys tab, choose Generate a key.

Use RS256 for tokens issued to people and applications, and Ed25519 for agent tokens. For SSH CA and x509 CA, the algorithm is set for you.

Choose Generate. The dialog confirms with Key generated, and the key appears on the Keys tab.

How secrets are kept

A secret is a value AuthFI must keep to work for you. Examples are the client secret of a sign-in connection, the token for a provisioning target, and a credential for a log destination.

Because the project's identity is sealed inside each secret, a secret moved to another customer's row cannot be opened.

See and delete secrets

In the console, open KMS & Vault and the Vault tab. The tab lists each secret by name, with what it feeds, its origin and when it was sealed. It never shows a value.

A secret arrives in the vault as a side effect of another task, such as adding a connection that needs a credential. To remove a secret, choose Delete on its row and confirm with Delete (not recoverable).

Secrets AuthFI generates

A client secret or a token that AuthFI creates for you is shown once, and AuthFI keeps only a hash of it. The hash is enough to check the secret, and not enough to recover it. If you lose the secret, create a new one.

A webhook signing secret is also shown once, and is kept sealed, because AuthFI signs with it.

Next steps