Skip to main content
Version: Latest (4.0.6)

Resource Indicators & Protected Resource Metadata

When clients call more than one API, a broad access token audience is risky: a token meant for one API can be reused against another if audience checks are loose.

cidaas supports Resource Indicators for OAuth 2.0 (RFC 8707) and OAuth 2.0 Protected Resource Metadata. Clients can request access tokens scoped to a specific API resource URI, and resource servers can publish discovery metadata so clients know how to obtain the right token.

Available from cidaas 4.0.6.

When to use this

See Standards & Security Extensions for how resource indicators fit least-privilege token design.

Prerequisites​

Before Resource Indicators take effect:

  1. Instance capability — Resource Indicators must be enabled for your cidaas instance. If you do not see Resource Indicators in Trust Desk, or the resource parameter on authorize/token requests has no effect, contact cidaas support to enable it.
  2. Trust Desk access — You need permission to open Resource Indicators and manage resources (typically an admin or app-manager role).
  3. Scopes — Scopes you assign to a resource must already exist in your instance scope catalog.

Activate: register resources in Trust Desk​

Operators define which API resource URIs clients may target, which scopes apply, and which applications are allowed.

  1. Open Trust Desk and go to Resource Indicators.
  2. Select Add Resource.
  3. Set:
    • Resource URI — Canonical URI of the API (for example https://api.example.com). This is the value clients send as resource and the value that appears in the access token aud claim.
    • Name — Display name for operators (for example Billing API - Production).
    • Supported Scopes — Scopes clients may request when targeting this resource.
    • Allow all clients — When enabled, any client can request this resource. When disabled, only clients with an explicit grant can.
    • Active — Inactive resources are rejected on token requests.
  4. Save the resource.
  5. If Allow all clients is off, open the resource’s Client Grants tab, select Grant Client, choose the application, pick approved scopes (from the resource’s supported scopes), and grant access.

Until the resource is registered (and the client is granted access when required), authorize/token requests that include that resource URI fail validation.

Use: request a scoped access token​

Clients send one or more resource parameters with the resource URI. cidaas validates the URI against your registered resources and client grants, then issues an access token whose aud claim matches the authorized resource URI(s). The ID token audience is not driven by resource.

Token endpoint (for example client credentials)​

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"

Repeat the form field for multiple URIs: resource=https://api.example.com/res1&resource=https://api.example.com/res2.

Authorization code and PKCE​

Include resource on the 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 code at /token-srv/token, send the same resource value(s) again when you want to keep or narrow that audience.

Access token aud​

{
  "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 several resource values were authorized, aud is an array of those URIs.

Resource indicators also apply on token exchange and CIBA when you pass resource on those requests.

Common failures​

SituationWhat to check
resource seems ignoredCapability not enabled for the instance — contact support
Resource unknown or client not allowedResource URI registered and Active; client grant present if Allow all clients is off
Scopes rejected for the resourceRequested scopes intersect the resource’s supported scopes and the client grant

How it fits together​

Protected Resource Metadata​

Resource servers can publish metadata at /.well-known/oauth-protected-resource so clients discover the authorization server and supported scopes without hard-coding every endpoint.

Example response​

{
  "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)Canonical resource identifier of the protected API.
authorization_serversstring arrayIssuer URLs trusted to issue tokens for this resource.
scopes_supportedstring arrayOptional scopes recognized by this resource server.
bearer_methods_supportedstring arrayHow bearer tokens are sent (for example header).
resource_documentationstring (URL)Optional link to API documentation.

401 challenges​

When a client calls a protected API without a suitable token, the resource server can respond with 401 Unauthorized and a WWW-Authenticate header that points at 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 reads resource_metadata, loads the metadata document, then requests a token from cidaas with the declared resource.