Rich Authorization Requests (RFC 9396)

The Rich Authorization Requests (RAR) extension specifies a standardized way for OAuth 2.0 clients to authorize fine-grained transaction details, resource rights, and contextual attributes beyond the coarse boundaries of traditional OAuth scopes.

In cidaas 4.1.0+, RAR enables identity architects and developers to define typed authorization structures (such as Open Banking payment initiations, clinical healthcare record access, or high-value enterprise actions), validate them against structured schemas, and embed the approved details into signed JWT Access Tokens.

---

Prerequisites

Before utilizing Rich Authorization Requests in your client applications:

1. An active cidaas administrator account with access to Trust Desk.
2. A registered OAuth 2.0 application (Confidential or Public) with allowed grant types (authorization_code).
3. An Authorization Detail Type (ADT) registered and enabled in cidaas for your tenant.

---

Configuration Steps

Step 1: Register Authorization Detail Types in Trust Desk

Administrators configure supported authorization structures in Trust Desk:

1. Log in to the cidaas Trust Desk administration portal.
2. Navigate to Settings → Authorization Details (or App Management → Authorization Detail Types).
3. Click Create Detail Type and specify:
   • Type Identifier: A unique string identifying the detail structure (e.g., urn:cidaas:authz:payment_initiation or customer_transfer).
   • Display Name & Description: Human-readable label for consent prompts.
   • JSON Schema Validation: Define permissible fields (e.g. instructedAmount, currency, creditorAccount).
   • Token Embedding: Enable embedding approved details into access tokens.
4. Save the configuration.

Step 2: Request Rich Authorization from the Client

Clients provide the authorization_details parameter as a JSON array encoded in URL format when redirecting to /authz-srv/authz (or directly in the backchannel request via Pushed Authorization Requests (PAR)).

Authorization Request Example

GET /authz-srv/authz?client_id=11111111-2222-3333-4444-555555555555
  &response_type=code
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile
  &authorization_details=%5B%7B%22type%22%3A%22customer_transfer%22%2C%22actions%22%3A%5B%22initiate%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fapi.bank.example.com%2Ftransfers%22%5D%2C%22instructedAmount%22%3A%7B%22amount%22%3A%22250.00%22%2C%22currency%22%3A%22EUR%22%7D%7D%5D
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=xyz123 HTTP/1.1
Host: your-tenant.cidaas.de

Unencoded authorization_details payload:

[
  {
    "type": "customer_transfer",
    "actions": ["initiate"],
    "locations": ["https://api.bank.example.com/transfers"],
    "instructedAmount": {
      "amount": "250.00",
      "currency": "EUR"
    }
  }
]

Step 3: Consent and Verification

When the user is prompted on the hosted login/consent screen, cidaas renders the structured attributes declared in the authorization details alongside requested OAuth scopes. After the user approves the prompt, cidaas issues an authorization code linked to both the approved scopes and the authorization details.

Step 4: Token Exchange

When exchanging the authorization code at /token-srv/token, the client issues a standard token request:

curl -X POST "https://your-tenant.cidaas.de/token-srv/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=11111111-2222-3333-4444-555555555555" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=VERIFIER_STRING"

The returned Access Token JWT includes the granted authorization_details claim:

{
  "iss": "https://your-tenant.cidaas.de",
  "sub": "8dfc4306-9f3b-4a33-95d0-98c8954da2c1",
  "aud": "11111111-2222-3333-4444-555555555555",
  "scope": "openid profile",
  "authorization_details": [
    {
      "type": "customer_transfer",
      "actions": ["initiate"],
      "locations": ["https://api.bank.example.com/transfers"],
      "instructedAmount": {
        "amount": "250.00",
        "currency": "EUR"
      }
    }
  ],
  "exp": 1730638800
}

---

Resource Server Verification

Resource Servers (APIs) validating the incoming Access Token must:

1. Verify the cryptographic signature against the tenant JWKS endpoint (/jwks-srv/jwks).
2. Inspect the authorization_details array for matching type and target locations.
3. Enforce field constraints (e.g., verifying that the transfer amount requested does not exceed the amount authorized in the token).

---

Troubleshooting & Remediation

Error Code	HTTP Status	Problem	Remediation
invalid_request	400	Malformed authorization_details JSON	Ensure authorization_details is a valid JSON array matching RFC 9396 syntax and properly URL-encoded.
invalid_authorization_details	400	Unknown or unauthorized detail type	Verify that the type string matches a registered Authorization Detail Type enabled for your application in Trust Desk.
unauthorized_client	400	Client not permitted to request RAR	Check application permissions in Trust Desk to verify RAR is permitted on the client ID.