Trusted Issuer Registry

The Trusted Issuer Registry enables enterprise architects and security administrators to configure and manage external JWT trust anchors within cidaas.

In distributed microservices, partner ecosystems, and multi-cloud architectures, services frequently receive JSON Web Tokens (JWT) minted by external identity providers or partner security token services (STS). The Trusted Issuer Registry provides a centralized CRUD API and registry allowing cidaas to validate external tokens, check issuer claims, and retrieve public signing keys dynamically.

---

Prerequisites

Before registering trusted issuers, ensure you have:

1. An administrator account with the Tenant Admin or Security Admin role.
2. A client application authorized with the following administration scopes:
   • cidaas:trusted_issuers_read
   • cidaas:trusted_issuers_write
3. The external identity provider's canonical issuer URL (iss) and public JWKS endpoint (jwks_uri) or X.509 certificate.

---

Management API & Procedure

1. Register a Trusted Issuer

To establish an external trust anchor, send a POST request to the Trusted Issuer endpoint:

curl -X POST "https://your-tenant.cidaas.de/auth-srv/trusted-issuers" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer": "https://identity.partner-enterprise.com",
    "name": "Partner Enterprise IdP",
    "description": "Production trust anchor for B2B API federation",
    "jwks_uri": "https://identity.partner-enterprise.com/.well-known/jwks.json",
    "allowed_audiences": [
      "https://api.your-tenant.cidaas.de"
    ],
    "enabled": true
  }'

Request Parameters

Parameter	Type	Required	Description
issuer	string	Yes	Canonical issuer URL matching the iss claim in inbound JWTs. Must be an absolute HTTPS URI.
name	string	Yes	Human-readable identifier for the trusted issuer.
jwks_uri	string	Conditional	HTTPS URL to the external provider's JSON Web Key Set. Required unless static keys are provided.
allowed_audiences	array	Yes	Array of valid aud claims accepted when evaluating tokens from this issuer.
enabled	boolean	No	Administrative toggle to activate or suspend trust evaluation (default: true).

2. Retrieve Trusted Issuers

List all configured trust anchors:

curl -X GET "https://your-tenant.cidaas.de/auth-srv/trusted-issuers" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"

3. Update a Trusted Issuer

Update configuration or rotation settings:

curl -X PUT "https://your-tenant.cidaas.de/auth-srv/trusted-issuers/ISSUER_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner Enterprise IdP (Updated)",
    "enabled": true,
    "jwks_uri": "https://identity.partner-enterprise.com/.well-known/jwks.json"
  }'

4. Delete a Trust Anchor

Remove a trust anchor when a partnership or integration is sunset:

curl -X DELETE "https://your-tenant.cidaas.de/auth-srv/trusted-issuers/ISSUER_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"

---

Token Validation Lifecycle

When an external token is presented to cidaas (such as during Token Exchange or federation gateways):

1. Issuer Matching: The engine checks the token's iss claim against the Trusted Issuer Registry.
2. Key Retrieval: cidaas fetches or uses cached keys from the verified jwks_uri.
3. Cryptographic Verification: Signature, expiration (exp), and audience (aud) claims are strictly validated.
4. Subject Mapping: The external subject (sub) is linked or verified according to federation policies.

---

Troubleshooting & Remediation

Issue	HTTP Status	Remediation
untrusted_issuer	400 / 401	The iss claim in the presented token is not registered or is currently disabled in the Trusted Issuer Registry.
jwks_fetch_failed	400 / 422	The remote jwks_uri could not be resolved or returned non-JSON keys. Check DNS and HTTPS certificate validity on the remote endpoint.
audience_mismatch	401	The token's aud claim does not match any entry in the issuer's allowed_audiences list.