SAML Certificate Rotation

Certificate Management

POST /api/organizations/:org_slug/services/:service_slug/saml/certificate

Generate a new self-signed X.509 certificate and RSA key pair for signing SAML assertions. The private key is encrypted before storage.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "public_key": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----",
  "valid_from": "2025-01-15T10:30:00Z",
  "valid_until": "2028-01-15T10:30:00Z",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "lifecycle_status": "healthy",
  "expires_in_seconds": 94608000,
  "published_previous_certificates": []
}

Response Fields:

• public_key (string): X.509 certificate in PEM format
• valid_from (string): Certificate validity start date (ISO 8601)
• valid_until (string): Certificate expiration date (ISO 8601, 3 years from creation)
• is_active (boolean): Whether this is the active signing certificate
• created_at (string): Certificate creation timestamp (ISO 8601)
• lifecycle_status (string): healthy, expiring_soon, expired, or not_yet_valid
• expires_in_seconds (number): Signed time remaining until certificate expiry
• published_previous_certificates (array): Verification-only certificates still published in metadata, including each certificate’s publish_until

Error Responses:

• 400 Bad Request: SAML must be enabled before generating certificate

  {
    "error": "SAML must be enabled before generating certificate"
  }
  

• 403 Forbidden: Organization not active, or user lacks permissions
• 500 Internal Server Error: Encryption service not available or certificate generation failed

Important Notes:

• Certificate is valid for 3 years from creation
• Private key is encrypted using AES-GCM before database storage
• Generating a new certificate makes it the sole active signing key
• The prior active certificate can remain verification-only in metadata for up to seven days; metadata publishes no more than two previous certificates
• The public certificate must be provided to the Service Provider during SAML setup
• New assertions are signed only by the active key

Certificate replacement:

Generating a certificate starts a bounded rollover window: the prior active certificate becomes verification-only and remains in IdP metadata for up to seven days or until it expires. AuthOS publishes the active certificate first and at most two eligible previous certificates. Coordinate the Service Provider metadata refresh and verify the integration during that window. External rotation and emergency-compromise evidence is still incomplete.

GET /api/organizations/:org_slug/services/:service_slug/saml/certificate

Retrieve the currently active SAML signing certificate for a service.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "public_key": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----",
  "valid_from": "2025-01-15T10:30:00Z",
  "valid_until": "2028-01-15T10:30:00Z",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "lifecycle_status": "healthy",
  "expires_in_seconds": 94608000,
  "published_previous_certificates": [
    {
      "public_key": "-----BEGIN CERTIFICATE-----\nMIID...previous...\n-----END CERTIFICATE-----",
      "valid_from": "2024-01-15T10:30:00Z",
      "valid_until": "2027-01-15T10:30:00Z",
      "publish_until": "2025-01-22T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Error Responses:

• 404 Not Found: No active SAML certificate exists

  {
    "error": "No active SAML certificate found"
  }
  

DELETE /api/organizations/:org_slug/services/:service_slug/saml/certificate/overlap

Immediately retire every previous verification-only certificate from metadata without changing the active signing key. Use this after a suspected compromise or after every Service Provider is known to trust the active certificate.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

curl -X DELETE https://sso.example.com/api/organizations/acme-corp/services/main-app/saml/certificate/overlap \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "success": true,
  "retired_certificates": 1
}

This operation is intentionally immediate. Service Providers that have not loaded the active certificate may reject newly signed assertions afterward.