Skip to main content
Version: Latest (4.0.6)

Resource Indicators & Protected Resource Metadata

In distributed microservice architectures, clients frequently need to communicate with multiple downstream resource servers (APIs). By default, standard OAuth 2.0 access tokens can have broad audiences, meaning a token intended for one API might be accepted by another if audience validation is permissive.

cidaas supports Resource Indicators for OAuth 2.0 (RFC 8707) and OAuth 2.0 Protected Resource Metadata. Clients can request access tokens cryptographically scoped to specific API resource servers, and resource servers can declare their configuration and authorization server discovery metadata.

Key Benefits​

CapabilityBenefit
Audience Isolation (RFC 8707)Prevents token re-use across distinct API domains by strictly constraining the access token's aud (audience) claim to the requested target resource URI.
Protected Resource MetadataStandardized endpoint (/.well-known/oauth-protected-resource) allowing clients to dynamically discover which authorization servers protect an API and which scopes are supported.
Automatic Discovery via 401 ChallengeResource servers return WWW-Authenticate response headers containing the resource_metadata link, allowing API clients to locate metadata and request targeted tokens automatically without hardcoded URLs.
Trust Desk Resource ManagementOperators can manage and catalog API resources directly from Trust Desk under Access Control → Resources.

How It Works​

1. Requesting Tokens with Resource Indicators (RFC 8707)​

When requesting authorization or issuing tokens via cidaas, clients include one or more resource parameters specifying the canonical URI of the target resource server.

Token Endpoint Request (M2M / Client Credentials)​

To obtain an access token restricted to a specific protected resource:

curl -X POST "https://{your-subdomain}.cidaas.de/token-srv/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "resource=https://api.example.com" \
  -d "scope=read write"

Authorization Code & PKCE Flows​

In interactive authorization flows, include resource as a query parameter in your authorization request:

https://{your-subdomain}.cidaas.de/authz-srv/authrequest/authz?
  client_id=your_client_id&
  response_type=code&
  redirect_uri=https://app.example.com/callback&
  resource=https://api.example.com&
  scope=openid profile read&
  state=xyz123

When exchanging the authorization code at /token-srv/token, repeat the identical resource parameter to verify the targeted audience.

Resulting Access Token Claims​

The generated JWT access token contains the target resource URI in its aud claim:

{
  "iss": "https://{your-subdomain}.cidaas.de",
  "sub": "12345-67890-abcdef",
  "aud": "https://api.example.com",
  "client_id": "your_client_id",
  "scopes": ["read", "write"],
  "iat": 1727611200,
  "exp": 1727614800
}

If multiple resource parameters were requested, aud contains an array of the authorized resource URIs.

2. Protected Resource Metadata Endpoint​

Resource servers publish metadata at the well-known location /.well-known/oauth-protected-resource. This allows API consumers to discover the authorization server and required scopes without manual coordination.

Example Response (GET /.well-known/oauth-protected-resource)​

{
  "resource": "https://api.example.com",
  "authorization_servers": [
    "https://{your-subdomain}.cidaas.de"
  ],
  "scopes_supported": [
    "read",
    "write"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://docs.example.com/api"
}
ParameterTypeDescription
resourcestring (URI)The canonical resource identifier of the protected resource server.
authorization_serversstring arrayIssuer URLs of the OAuth 2.0 authorization servers trusted to issue tokens for this resource.
scopes_supportedstring arrayOptional list of scopes recognized by this resource server.
bearer_methods_supportedstring arraySupported transmission methods for bearer tokens (e.g. header).
resource_documentationstring (URL)Link to human-readable API documentation.

3. Handling 401 Unauthorized Challenges​

When an API client attempts to access a protected endpoint without an access token (or with an access token lacking the correct audience), the resource server responds with HTTP 401 Unauthorized and a WWW-Authenticate header containing the location of its metadata:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"
Content-Type: application/json

{
  "error": "unauthorized",
  "error_description": "Full authentication is required to access this resource"
}

The client extracts resource_metadata, requests the metadata document, and automatically negotiates an access token with cidaas using the declared resource and authorization_servers.

4. Managing Resources in Trust Desk​

Operators can configure and monitor protected resources in Trust Desk:

  1. Navigate to Access Control → Resources.
  2. Click Add Resource to register a new API resource URI.
  3. Configure the resource's supported scopes and associated client applications.
  4. Save the configuration to enforce audience verification across token issuance endpoints.