Certificate Rotation¶

AgentCube uses RSA signing keys for Oracle token exchange in SSO mode. These keys and certificates require periodic rotation.

AgentCube Signing Key¶

The signing key is used to create JWT assertions for Oracle token exchange. The certificate has a finite validity period (default 5 years / 1825 days).

When to Rotate¶

• Before the certificate expires
• If the private key is compromised
• Per your organization's security policy

Rotation Procedure¶

1. Generate a new key pair:

   openssl genrsa -out agentcube-signing-new.pem 2048
   openssl req -new -x509 \
     -key agentcube-signing-new.pem \
     -out agentcube-signing-new.cer \
     -days 1825 \
     -subj "/CN=AgentCube MCP/O={organization_name}"
   

2. Import the new certificate to OCI Identity Domain:

   • Go to Security → Trusted partner certificates → Import certificate
   • Upload the new certificate with a new alias (e.g., agentcube-mcp-2)

3. Update environment variables:

   • Set AGENTCUBE_SIGNING_KEY_BASE64 to the base64-encoded new private key
   • Set AGENTCUBE_SIGNING_KID to the new certificate alias

4. Restart the container to pick up the new configuration

5. Verify — test an SSO login and tool call to confirm the new key works

6. Remove the old certificate from OCI trusted partner certificates (after confirming the new key works)

Identity Provider Signing Keys¶

If your identity provider (Entra, Okta, etc.) rotates its signing keys, AgentCube typically handles this automatically through OIDC discovery. No manual action is required unless your IdP requires it.