Certificates & Signing Key¶

Overview¶

JustIAM provides two separate mechanisms for signing tokens and assertions:

Tenant Signing Key — the built-in RSA key pair used to sign OIDC access tokens (and SAML assertions by default). Managed under Security → Signing Key.
Managed Certificates — optional RSA/ECDSA key pairs stored encrypted in the database. Used to override the tenant signing key per application. Managed under Security → Certificates.

Both are accessible from the Security section of the administration sidebar.

Permissions¶

Permission	Grants
`certificates.manage`	Create, rotate and delete signing certificates; rotate and drop the tenant key
`certificates.view`	Read-only — list, view details, assign to applications

Tenant Signing Key¶

The tenant signing key is an RSA key pair used for all OIDC token and SAML assertion signatures unless a per-application certificate is assigned.

UI: Security → Signing Key

The Signing Key page shows:

Current key: Key ID (kid), creation date, active OAuth session count, maximum app token expiry.
Previous key (if a rotation has occurred): Key ID, rotation timestamp, and a safety assessment.

Rotating the key¶

The 3-dot menu on the current key card provides a Rotate action.

POST /api/v1/admin/tenant-key/rotate
Authorization: Bearer <token>

A new RSA key pair is generated. The old key is retained in JWKS so tokens signed before rotation remain valid until they expire.

⚠️ SAML impact — Rotation immediately regenerates the SAML signing certificate. Any SAML application using the tenant default certificate (signing_cert_id not set) will have its IdP metadata updated automatically, but service providers that have the old certificate fingerprint pinned will reject assertions until reconfigured. To avoid disruption, assign a dedicated certificate to each SAML app (see Managed Certificates) before rotating. The rotation dialog shows how many SAML apps are currently exposed.

Dropping the previous key¶

Once all tokens signed with the previous key have expired, you can remove it to clean up the JWKS endpoint.

POST /api/v1/admin/tenant-key/drop-previous
Authorization: Bearer <token>

The Signing Key page shows a safety indicator:

Safe to drop (green): time since rotation > max(token_expiry) across all applications. All access tokens have expired.
Pending (amber): Tokens may still be valid. The page shows the remaining window in seconds and the active session count.

You can force-drop even if the window has not elapsed — active access tokens signed with the previous key will immediately fail validation.

Checking key status¶

GET /api/v1/admin/tenant-key/status
Authorization: Bearer <token>

Returns:

{
  "current_kid": "abc123…",
  "current_key_created_at": "2025-01-15T10:00:00Z",
  "has_prev_key": true,
  "prev_key": {
    "kid": "xyz789…",
    "rotated_at": "2025-06-01T08:00:00Z",
    "safe_to_drop": false,
    "seconds_until_safe": 2847
  },
  "active_sessions": 42,
  "max_token_expiry_secs": 3600,
  "saml_apps_using_default_cert": 3
}

saml_apps_using_default_cert — number of SAML applications using the tenant default certificate. These apps will break immediately on key rotation unless a dedicated certificate is assigned first.

Managed Certificates¶

Managed certificates let you assign a dedicated key pair to a specific OIDC or SAML application, overriding the tenant default.

UI: Security → Certificates → + Generate Certificate

Fill in:

Field	Default	Description
Name	—	Display label (required)
Common Name (CN)	same as Name	X.509 subject CN
Subject Alt Names	—	Optional DNS SANs, comma-separated
Validity	365 days	Certificate lifetime
Algorithm	RSA 4096	`rsa2048`, `rsa4096`, `ecdsa-p256`, or `ecdsa-p384`

Alternatively, upload your own PEM-encoded private key and certificate.

API:

POST /api/v1/admin/certificates
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "SAML Signing Cert",
  "common_name": "justiam.example.com",
  "validity_days": 730,
  "key_algorithm": "ecdsa-p256"
}

Response includes id, name, cert_pem, and expires_at. The private key is never returned.

Assigning a certificate to an application¶

In the OIDC or SAML application form, open the Signing Certificate dropdown and select the certificate. Applications without a dedicated certificate fall back to the tenant signing key.

Terraform¶

resource "justiam_certificate" "saml" {
  name          = "SAML Signing Cert"
  key_algorithm = "ecdsa-p256"
  validity_days = 730
}

resource "justiam_saml_config" "myapp" {
  app_id          = justiam_application.myapp.id
  signing_cert_id = justiam_certificate.saml.id
}