Dynamic Client Registration (DCR) Policy
Dynamic Client Registration (DCR) lets OAuth clients register themselves with
cidaas (RFC 7591) instead of an administrator creating every application in
Trustdesk. The tenant DCR policy (policyType=dcr) is the single place that
controls:
- Whether open (unauthenticated) registration is allowed
- Which client settings registered apps may use (ceilings)
- Which values fill fields the registration document cannot carry (defaults)
- How long client secrets live for confidential registrations (secrets)
- How many DCR-created apps the tenant may hold (limits)
When DCR is enabled for the tenant, registration with an Initial Access Token (IAT) is always available. Open registration remains optional and is off by default.
Use case: Onboard partner tools or MCP hosts that must create OAuth clients under shared tenant rules, without creating each application manually and without handing out full app-management credentials.
When a registration request arrives, cidaas evaluates:
- Is DCR enabled for the tenant?
- Is the caller allowed to register — a valid IAT, or open registration enabled with no Bearer token?
- Do the requested client settings fit the ceilings?
- Which defaults, secrets, and limits apply?
If every check passes, cidaas creates the application and returns the registered client metadata (including a registration access token for later management under RFC 7592).
DCR must be enabled for your tenant. Contact cidaas support if it is not available
yet. When DCR is disabled, DCR policy APIs return 404 (APP10161), and
registration endpoints are not available.
Prerequisites
Before configuring the DCR policy, ensure you have:
- DCR enabled for your tenant.
- An administrator account with the
ADMINorSECONDARY_ADMINrole, and thecidaas:apps_read(view) andcidaas:apps_write(save) scopes. - Access to Trustdesk for your tenant (or the App Management Policies API).
- Agreement on which scopes, grant types, response types, auth methods, redirect URI rules, and token lifetimes registered clients may use.
- A decision on open registration (usually leave it off and use Initial Access Tokens for controlled onboarding).
Configuration Steps
Step 1: Open the DCR policy
- Sign in to Trustdesk as an administrator.
- Navigate to Integrations → App Management Policies.
- Open the DCR policy. When DCR is enabled, cidaas can create a default policy
for your tenant (
nameis alwaysdefault). There is nothing to create by hand.
The DCR policy cannot be deleted. To stop DCR, turn the feature off for the tenant or tighten ceilings / disable open registration as needed.
The seeded policy starts with these values:
| Setting | Seeded default |
|---|---|
| Open registration | Off |
| IAT registration | On whenever DCR is enabled (not a separate policy toggle) |
| Allowed scopes / grant types / response types / auth methods | Empty (nothing allowed until you fill them) |
| Max redirect URIs | 10 (platform max you may set: 50) |
| Redirect URI allow rules | Empty (https plus loopback rules apply) |
| Max token / refresh token lifetime | 15 minutes / 30 days |
| Token / refresh token / authorization code lifetime (defaults) | 15 minutes / 30 days / 2 minutes |
| Secret expires in | 0 (never) |
| Max clients per tenant | 0 (unlimited) |
| Public client refresh tokens | Unset (treated as none — public clients do not keep refresh_token) |
Step 2: Choose how callers may register
Open registration
Open registration allows a caller to register without an Authorization header (anonymous DCR).
| Setting | Typical seeded default | Meaning |
|---|---|---|
| Open registration enabled | Off | Anonymous registration is refused |
Leave open registration off unless you intentionally allow anyone who can reach the registration endpoint to create clients. Prefer IATs for controlled onboarding.
Open registration is rate-limited per client IP (default tiers: 10 / 5 seconds,
30 / 1 minute, 100 / 5 minutes). Exceeding the limit returns 429 (APP10201).
Requests that send a Bearer token are not counted against this limiter.
Enabling open registration exposes client creation to unauthenticated callers (subject to your ceilings and rate limits). Use it only when that risk is accepted.
Initial Access Token registration
When DCR is enabled, callers may register with
Authorization: Bearer <initial-access-token>. Mint and manage IATs via
/apps-srv/dcr/initial-access-tokens (scopes cidaas:dcr_iat_write /
cidaas:dcr_iat_read).
The DCR policy does not turn IAT registration on or off separately — it follows the tenant DCR feature. Basic credentials are not accepted for registration.
Step 3: Configure ceilings
Ceilings limit what a dynamically registered client may request. Empty allow-lists mean nothing in that category is allowed until you add values (not “allow all”). Until scopes, grants, response types, and auth methods are filled, most real registrations will fail or register with empty capabilities.
How a value outside the ceilings is treated:
| Setting outside the ceiling | Result |
|---|---|
| Grant type, response type, or auth method | The registration is refused (invalid_client_metadata) |
| Redirect URI, or more redirect URIs than Max redirect URIs | The registration is refused (invalid_redirect_uri) |
| Scope | The scope is removed; registration continues with the remaining scopes |
refresh_token on a public client (auth method none) | The grant is removed, unless Public client refresh tokens allows it |
| Setting | Typical seeded default | Meaning |
|---|---|---|
| Allowed scopes | Empty | Exact scope names only (no wildcards). Omitting scope in the document applies the full allow-list as the server default |
| Allowed grant types | Empty | Grant types the client may use |
| Allowed response types | Empty | Response types the client may use |
| Allowed auth methods | Empty | Token endpoint auth methods (for example none, client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth) |
| Max redirect URIs | 10 | Cap on redirect URI count (0 applies the platform default of 10; maximum configurable value is 50) |
| Redirect URI allow rules | Empty | Optional glob patterns over scheme://host:port/path; empty allows https (and loopback rules) |
| Max token lifetime | 15 minutes (900 s) | Cap on access token lifetime (0 = tenant default as both default and cap) |
| Max refresh token lifetime | 30 days | Cap on refresh token lifetime (0 = tenant default as both default and cap) |
| Public client refresh tokens | Unset → none | none drops refresh_token for public clients; dpopOnly keeps it only when DPoP-bound access tokens apply; allowed keeps it |
Configure allow-lists to match the clients you intend to admit (for example
openid, email, profile, authorization_code, refresh_token, code, and
none or private_key_jwt).
Step 4: Configure defaults
Defaults fill settings a registration document cannot carry. Lifetime defaults must not exceed the matching ceiling.
| Setting | Typical seeded default | Meaning |
|---|---|---|
| Token lifetime | 15 minutes | Applied when the document does not set it |
| Refresh token lifetime | 30 days | Applied when the document does not set it |
| Authorization code lifetime | 2 minutes | Applied for interactive flows |
| Hosted pages layout ID | Empty | Tenant default layout when empty |
| User setup ID | Empty | Tenant default user setup when empty |
| Verification options / template group / group verification / group selection IDs | Empty | Tenant defaults when empty; applied to interactive clients |
| DPoP-bound access tokens | Off | Applied only when the document omits dpop_bound_access_tokens; a present member wins in either direction |
Step 5: Configure secrets
For confidential clients that receive a client secret at registration:
| Setting | Typical seeded default | Meaning |
|---|---|---|
| Secret expires in | 0 (never) | 0 = no expiry; otherwise seconds until expiry (maximum 1 year / 31536000) |
Step 6: Configure limits
| Setting | Typical seeded default | Meaning |
|---|---|---|
| Max clients per tenant | 0 (unlimited) | Cap on total DCR-registered applications in the tenant |
When the cap is reached, further registrations are refused until apps are removed or the limit is raised.
Step 7: Save
- Review open registration, ceilings, defaults, secrets, and limits.
- Click Save.
A saved policy applies to the next registration. Existing registered apps keep the settings they were created with unless you update those apps separately (Trustdesk or RFC 7592 client management).
How registration uses the policy
Register a client (RFC 7591)
POST /apps-srv/dcr/clients
| Mode | Authorization | When allowed |
|---|---|---|
| IAT | Authorization: Bearer <iat> | DCR feature enabled and IAT still valid |
| Open | No Authorization header | Open registration enabled on the policy |
Typical flow:
- Caller sends client metadata (redirect URIs, grant types, and so on).
- cidaas authorizes the mode, applies ceilings / defaults / secrets / limits, and creates the app.
- The 201 response includes the registered client fields and a
registration_access_tokenfor later management.
Do not send HTTP Basic credentials on registration — they are refused.
Manage a registered client (RFC 7592)
After registration, the client may manage itself with the registration access token:
| Action | Method | Path |
|---|---|---|
| Read | GET | /apps-srv/dcr/clients/{client_id} |
| Replace | PUT | /apps-srv/dcr/clients/{client_id} |
| Delete | DELETE | /apps-srv/dcr/clients/{client_id} |
These calls authenticate with the registration access token (not an IAT). Full request and response details belong with the DCR registration API documentation;
Managing the policy via API
The DCR policy uses the same App Management Policies routes as CIMD, with
policyType=dcr (or type=dcr on list):
| Action | Method | Path |
|---|---|---|
| List / seed default | GET | /apps-srv/app-management-policies?type=dcr |
| Get by id | GET | /apps-srv/app-management-policies/{id} |
| Create or replace | PUT | /apps-srv/app-management-policies |
| Patch | PATCH | /apps-srv/app-management-policies/{id} |
Requires cidaas:apps_read / cidaas:apps_write and role ADMIN or
SECONDARY_ADMIN.
Notable behaviour:
- List with DCR disabled returns an empty list (200).
- Get / save with DCR disabled returns 404 (
APP10161). - PUT upserts: creates (201) if missing, replaces (200) if present.
- Policy
namemust bedefault(400APP10163otherwise). - DELETE is always refused for DCR (400
APP10162). - Developer-portal style fields (
groupIds, top-levelallowedScopes) are not allowed on a DCR policy. - Other validation failures return 400 (
APP10164) — for example defaults above ceilings, negative limits, orsecrets.expiresInSecondsoutside0–31536000.
Verification
- Open the DCR policy in Trustdesk and confirm open registration, ceilings, defaults, secrets, and limits match what you saved.
- Confirm allow-lists are filled for the clients you intend to admit.
- With open registration off, confirm an unauthenticated register call is
refused (
APP10197/ access denied). - Mint an IAT via
/apps-srv/dcr/initial-access-tokens, register a client with that Bearer token, and confirm success when metadata fits the ceilings. - Confirm registration fails when a requested grant, auth method, or redirect URI is outside the ceilings, or when max clients per tenant is exceeded.
- Confirm scopes outside the allow-list are dropped rather than refusing the whole registration (unless no usable scopes remain for your use case).
Troubleshooting
| Symptom | Root cause | Remediation |
|---|---|---|
DCR policy missing / APIs return 404 APP10161 | DCR is not enabled for the tenant | Contact cidaas support to enable DCR |
List returns empty with type=dcr | DCR feature off | Enable DCR; list seeds the default when the feature is on |
Save returns 400 APP10163 | name is not default | Use name: default |
Save returns 400 APP10164 | Invalid ceilings, defaults, secrets, or limits | Fix values (for example defaults above ceilings, negative limits, secret expiry out of range, unknown auth method) |
Delete returns 400 APP10162 | DCR policy is not deletable | Disable the feature or adjust policy settings instead |
Unauthenticated register refused (APP10197) | Open registration is off | Send an IAT, or enable open registration only if intended |
Register with Basic auth refused (APP10191) | Basic credentials are not accepted for DCR | Use an IAT Bearer token, or open registration with no Authorization header |
IAT register refused (APP10193 / APP10194 / APP10195) | IAT missing, expired, or exhausted | Mint a new IAT or use a still-valid token |
Open register rate-limited (APP10201) | Too many anonymous registrations from the same IP | Retry later or use IAT registration |
| Registration refused for metadata | Outside ceilings (grants, response types, redirects, auth method, lifetimes) | Widen ceilings or change the registration document |
| Tokens / scopes unexpected after register | Scopes outside the allow-list were removed | Add the scopes to Allowed scopes |
| Public client has no refresh token | Public client refresh tokens mode is none (or unset) | Set dpopOnly or allowed, or use a confidential auth method |
| Register refused for quota | maxClientsPerTenant reached | Remove unused DCR apps or raise the limit |
| Tokens / setup IDs unexpected | Defaults or empty IDs falling back to tenant defaults | Set explicit defaults on the DCR policy |
RFC 7592 management unauthorized (APP10200) | Registration access token missing or invalid | Use the registration_access_token from the original register response |
Explore related topics
- App management — registering and configuring applications
- Client ID Metadata Document (CIMD) — admit clients that use an HTTPS metadata URL as
client_id - DCR Policy API — OpenAPI for list, get, put, patch, and delete
- Standards & Security Extensions — choosing OAuth extensions
Contact cidaas support or [email protected].