Version: 4.0.5

Application types

For full Trustdesk setup and REST APIs, see App management and the Trustdesk Admin Hub.

cidaas supports several application types (client_type), each designed for specific use cases and platforms. The type you choose determines:

Which OAuth2 flows are available (if any)
How redirect URIs are validated
Security requirements and best practices
User experience patterns and hosted login page capabilities

Valid values defined in the app configuration model: SINGLE_PAGE, REGULAR_WEB, NON_INTERACTIVE, ANDROID, IOS, WINDOWS_MOBILE, HYBRID_APP, DESKTOP, DEVICE, THIRD_PARTY, and SAML_SP.

info

SAML Application Type vs SAML Login Provider

SAML_SP is an application type that represents an external SAML Service Provider — cidaas acts as its SAML 2.0 Identity Provider (IdP), configured via the Trustdesk SAML Identity Provider creation wizard under Integrations → SAML Identity Provider. See SAML SP Integration.

This is separate from enabling SAML as a login provider (SAML IDP Providers) on an OAuth application — configure that under Providers → Identity Providers. See SAML 2.0 Single Sign-On.

Decision Tree: Choosing the Right Application Type

Quick Links: Mobile & Client Integrations

🤖 Android SDK Integration

App Links: Digital Asset Links (assetlinks.json)
Biometrics: Passkeys & FIDO2 authentication
SDK Guide: Step-by-step Android SDK setup

🍎 iOS SDK Integration

Universal Links: apple-app-site-association
Biometrics: Face ID, Touch ID & Passkeys
SDK Guide: Step-by-step Swift/iOS SDK setup

🛡️ Native Client Best Practices

Token Storage: Encrypted keystore / keychain
Security: PKCE validation & Custom Chrome Tabs
Session Handling: Token refresh & lifecycle

Overview

Application type (`client_type`)	Primary use case	Client model	Recommended OAuth flow	Trustdesk Location
Single Page Application (SPA) `SINGLE_PAGE`	Modern browser-based apps (React, Vue, Angular)	Public client	Authorization Code + PKCE	Integrations → Applications
Regular Web App `REGULAR_WEB`	Traditional server-rendered web applications	Confidential client	Authorization Code (with client secret)	Integrations → Applications
Android `ANDROID`	Native Android mobile applications	Public client	Authorization Code + PKCE	Integrations → Applications
iOS `IOS`	Native iOS mobile applications	Public client	Authorization Code + PKCE	Integrations → Applications
Windows Mobile `WINDOWS_MOBILE`	Native Windows mobile applications	Public client	Authorization Code + PKCE	Integrations → Applications
Hybrid App `HYBRID_APP`	Cross-platform apps (React Native, Flutter, Ionic)	Public client	Authorization Code + PKCE	Integrations → Applications
Desktop `DESKTOP`	Native desktop applications (Windows, macOS, Linux)	Public client	Authorization Code + PKCE	Integrations → Applications
Non-Interactive Client `NON_INTERACTIVE`	Backend services, machine-to-machine APIs	Confidential client	Client Credentials Flow	Integrations → Applications
Device `DEVICE`	Smart TVs, IoT, limited-input devices	Public client	Device Code Flow (RFC 8628)	Integrations → Applications
Third Party `THIRD_PARTY`	Untrusted external OAuth clients (deprecated for new apps)	Public client	Authorization Code + PKCE	Integrations → Applications
SAML Identity Provider registration `SAML_SP`	External SAML Service Provider where cidaas is IdP	SAML IdP Assertion	SAML 2.0 Web Browser SSO	Integrations → SAML Identity Provider

info

SAML IdP Configuration Scope

When configuring a SAML_SP application, Trustdesk automatically hides inapplicable OAuth2/OIDC settings (such as grant types, response types, PKCE, token lifetimes, and client secrets) because authentication is negotiated strictly via SAML 2.0 assertions rather than OAuth token endpoints.

warning

Deprecation Notice (THIRD_PARTY)

THIRD_PARTY remains supported for existing integrations but is deprecated for new applications. Prefer explicit OAuth types (SINGLE_PAGE, REGULAR_WEB, or native types) where possible.

Web Applications

Single Page Application (SPA) vs Regular Web App

The table below outlines the core architectural and security differences between browser-rendered SPAs and server-rendered web applications:

Dimension	Single Page Application (`SINGLE_PAGE`)	Regular Web App (`REGULAR_WEB`)
Architecture	Client-side JavaScript frameworks (React, Vue, Angular, Svelte)	Server-side rendering (Node.js, Java Spring, ASP.NET, PHP, Python/Django)
Rendering Model	Dynamic DOM updates in browser; API-driven	Server builds HTML; full-page reloads on navigation
Security Model	Public Client — source code is accessible in browser; cannot securely store client secrets	Confidential Client — server environment is secure; can safely store client secrets
Recommended OAuth Flow	Authorization Code Flow with PKCE (`S256`)	Authorization Code Flow (with client secret authentication)
Client Authentication	`none` (No client secret)	`client_secret_post`, `client_secret_basic`, or `private_key_jwt`
Redirect URI Scheme	`https://` (Strict browser origins)	`https://` (Backend callback endpoints)
Token Handling	Ephemeral memory storage or Web Worker (avoid localStorage where XSS is possible)	Stored securely in encrypted HTTP-only session cookies on backend

Key Capabilities Matrix for Web Applications

Capability / Setting	`SINGLE_PAGE`	`REGULAR_WEB`
PKCE Required	Yes (`S256` mandatory)	Optional (recommended)
Client Secret Issued	No (Not generated)	Yes
Allowed Web Origins (CORS)	Configurable (Strict origin matching)	Not applicable
Token Introspection via Secret	No	Yes
Session Transfer / SSO	Yes	Yes

Native & Mobile Applications

Native and mobile applications run on user devices where application binaries can be disassembled, decompiled, or intercepted.

Choosing Among Mobile & Desktop Types

ANDROID: Select when deploying a native Android app using Android Studio / Kotlin / Java or integrating the Android cidaas SDK. Enforces custom schemes or verified Android App Links.
IOS: Select when deploying a native iOS/iPadOS app using Xcode / Swift / Objective-C or integrating the iOS cidaas SDK. Enforces custom schemes or Universal Links (apple-app-site-association).
HYBRID_APP: Select for cross-platform frameworks such as React Native, Flutter, Ionic, or Capacitor where web runtime wrappers run natively.
DESKTOP: Select for native desktop apps (Electron, WPF, macOS Cocoa, Tauri, Qt). Supports loopback redirects (http://127.0.0.1:<port>) or custom protocol handlers.
WINDOWS_MOBILE: Legacy client type reserved for backwards compatibility.

Redirect URI & Security Matrix for Native Apps

Application Type	Redirect URI Patterns	PKCE Enforcement	Deep Link Validation
`ANDROID`	Custom URI scheme (e.g. `myapp://callback`) or HTTPS App Link	Mandatory (`S256`)	Android Digital Asset Links (`.well-known/assetlinks.json`)
`IOS`	Custom URI scheme (e.g. `myapp://callback`) or HTTPS Universal Link	Mandatory (`S256`)	Apple App Site Association (`.well-known/apple-app-site-association`)
`HYBRID_APP`	Custom URI scheme or App Links / Universal Links	Mandatory (`S256`)	Supported on both platforms
`DESKTOP`	Loopback (`http://127.0.0.1:port/callback`) or custom URI scheme	Mandatory (`S256`)	OS protocol handler registration
`WINDOWS_MOBILE`	Custom URI scheme	Mandatory (`S256`)	Standard redirect validation

Deep Linking & Mobile Association Files

To support modern, secure browser redirects (Universal Links on iOS and App Links on Android) without browser popups or intermediate prompts, cidaas automatically generates and hosts the required platform association files at standard .well-known endpoints.

Trustdesk Configuration Requirements

When creating or editing an IOS or ANDROID application in Trustdesk (Integrations → Applications), provide the platform-specific identity details:

Field in Trustdesk	Android App (`ANDROID`)	iOS App (`IOS`)	Description / Source
Package Name / Bundle ID	`package_name` (e.g., `com.example.myapp`)	`bundle_id` (e.g., `com.example.myapp`)	Unique app identifier defined in your `build.gradle` or Xcode target settings.
Key Hash / Team ID	`key_hash` (SHA-256 fingerprint)	`team_id` (Apple Developer Team ID)	For Android: 20-byte SHA-256 certificate fingerprint. For iOS: 10-character alphanumeric Team ID from Apple Developer portal.

warning

Mandatory Fields for Mobile Verification

Association files will only be generated for applications where both fields are provided:

Android: Both Package Name and Key Hash must be configured.
iOS: Both Team ID and Bundle ID must be configured.

tip

Multi-App Aggregation

When multiple iOS or Android applications are registered in the same tenant, cidaas automatically merges their configuration entries into the respective .well-known endpoints without overwriting existing apps.

Published Endpoints and Response Format

Once saved in Trustdesk, cidaas serves the association documents dynamically across all custom and standard tenant domains.

1. iOS — `GET /.well-known/apple-app-site-association`

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=900

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "9JA6MVXXXX.com.example.myapp",
        "paths": [
          "/ios/com.example.myapp/*"
        ]
      }
    ]
  },
  "activitycontinuation": {
    "apps": [
      "9JA6MVXXXX.com.example.myapp"
    ]
  },
  "webcredentials": {
    "apps": [
      "9JA6MVXXXX.com.example.myapp"
    ]
  }
}

2. Android — `GET /.well-known/assetlinks.json`

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=900

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
      ]
    }
  }
]

Verification & Troubleshooting

You can verify that your tenant endpoints are live immediately using curl:

# Verify Apple App Site Association
curl -i https://<your-tenant-domain>/.well-known/apple-app-site-association

# Verify Android Asset Links
curl -i https://<your-tenant-domain>/.well-known/assetlinks.json

info

Cache Behavior

Responses from /.well-known/apple-app-site-association and /.well-known/assetlinks.json include Cache-Control: public, max-age=900 (15 minutes). When updating credentials or package names in Trustdesk, allow up to 15 minutes for intermediate CDN/proxy caches to refresh.

note

Related Mobile SDK & Integration Documentation

For full implementation guides across mobile platforms and SDKs, see:

Example Redirect URIs

Android: com.myapp://oauth/callback
iOS: myapp://oauth/callback
Desktop: http://127.0.0.1:52134/callback
Windows Mobile: ms-app://oauth/callback

Machine-to-Machine & Service Clients

Non-Interactive Client (`NON_INTERACTIVE`)

Purpose: Machine-to-machine (M2M) communication, backend microservices, background jobs, and API-to-API communication.

Attribute	Specification
User Interface	❌ None (no hosted login or consent UI)
Security Model	Confidential Client — backend securely stores client credentials
Recommended Flow	Client Credentials Flow (`grant_type=client_credentials`)
Redirect URIs	❌ Not applicable (cleared on save)
Token Claims	Issued based on client allowed scopes (`scopes.allowed_scopes`)

Typical Use Cases:

Daemon services and microservices authenticating to APIs
Automated background sync jobs
Cron tasks accessing backend endpoints

info

Non-Interactive Scope Constraints

Non-interactive clients do not support user authentication flows, token conditions, or hosted page layouts since there is no user interaction.

Special Purpose & Legacy Clients

Device (Limited Input Devices) (`DEVICE`)

Purpose: Appliances and devices with limited input capabilities (Smart TVs, gaming consoles, IoT devices, network printers).

Attribute	Specification
Recommended Flow	Device Code Flow (RFC 8628 - `grant_type=urn:ietf:params:oauth:grant-type:device_code`)
Authentication Device	User authenticates on a secondary device (smartphone / laptop)
User Experience	Displays QR code or URL + 8-character verification code

Authentication Sequence:

Device requests device authorization (POST /authz-srv/device/code).
Device presents verification URL and user_code (or QR code).
User navigates to URL on mobile device/laptop and authenticates.
Device polls token endpoint (POST /token-srv/token) until user completes login.
Device receives access token upon successful user approval.

Third Party (`THIRD_PARTY`)

Purpose: External, untrusted OAuth clients where user consent to requested scopes must be explicitly enforced.

warning

Deprecated Application Type

THIRD_PARTY is supported for backwards compatibility but is deprecated for new applications. Use explicit client types (SINGLE_PAGE, REGULAR_WEB, or native types) and configure scope consent in Trustdesk instead.

SAML Identity Provider Registration (`SAML_SP`)

Purpose: Register an external Service Provider (SP) application in cidaas so cidaas can act as its SAML 2.0 Identity Provider (IdP).

Configured via the Trustdesk SAML Identity Provider creation wizard under Integrations → SAML Identity Provider. See SAML SP Integration for the step-by-step guide.
Not an OAuth2 client: grant_types and response_types are omitted.
Endpoints are negotiated via standard SAML 2.0 metadata XML exchange.

OAuth Flow Selection Matrix

The matrix below summarizes the recommended OAuth2/OIDC flows, client secret requirements, and user interaction modes by application type:

Application type (`client_type`)	Recommended OAuth Flow	Primary Grant Type	Client Secret Required?	Interactive User Login?
Single Page App `SINGLE_PAGE`	Authorization Code + PKCE	`authorization_code`	❌ No	✅ Yes
Regular Web App `REGULAR_WEB`	Authorization Code	`authorization_code`	✅ Yes	✅ Yes
Android / iOS / Native	Authorization Code + PKCE	`authorization_code`	❌ No	✅ Yes
Non-Interactive `NON_INTERACTIVE`	Client Credentials	`client_credentials`	✅ Yes	❌ No
Device `DEVICE`	Device Code (RFC 8628)	`urn:ietf:params:oauth:grant-type:device_code`	❌ No	✅ Yes
Third Party `THIRD_PARTY`	Authorization Code + PKCE	`authorization_code`	❌ No	✅ Yes
SAML Identity Provider `SAML_SP`	SAML 2.0 Web Browser SSO	— (SAML Assertions)	Depends on SAML setup	✅ Yes

Trustdesk Feature Availability Matrix

Trustdesk Section	Interactive OAuth Apps (SPA, Web, Native, Device)	Non-Interactive (M2M)	SAML SP Registration (`SAML_SP`)
Branding & Hosted Pages	✅ Supported	❌ Inapplicable	Partial (Layout styling)
OAuth2 / OIDC Settings	✅ Supported	Partial (No redirect URIs)	❌ Inapplicable
Authentication & MFA	✅ Supported	❌ Inapplicable	SAML IdP Settings
Registration & Field Setup	✅ Supported	❌ Inapplicable	Partial
Scope Management	✅ Supported	✅ Supported	Partial
Token Lifetimes	✅ Supported	✅ Supported	❌ Inapplicable
Signing Key Rotation	✅ Supported	✅ Supported	✅ Supported

For full section mapping, see Configuration sections in App Management.

Decision Tree: Choosing the Right Application Type​

Quick Links: Mobile & Client Integrations​

Overview​

Web Applications​

Single Page Application (SPA) vs Regular Web App​

Key Capabilities Matrix for Web Applications​

Native & Mobile Applications​

Choosing Among Mobile & Desktop Types​

Redirect URI & Security Matrix for Native Apps​

Deep Linking & Mobile Association Files​

Trustdesk Configuration Requirements​

Published Endpoints and Response Format​

1. iOS — GET /.well-known/apple-app-site-association​

2. Android — GET /.well-known/assetlinks.json​

Verification & Troubleshooting​

Example Redirect URIs​

Machine-to-Machine & Service Clients​

Non-Interactive Client (NON_INTERACTIVE)​

Special Purpose & Legacy Clients​

Device (Limited Input Devices) (DEVICE)​

Third Party (THIRD_PARTY)​

SAML Identity Provider Registration (SAML_SP)​

OAuth Flow Selection Matrix​

Trustdesk Feature Availability Matrix​

Decision Tree: Choosing the Right Application Type

Quick Links: Mobile & Client Integrations

Overview

Web Applications

Single Page Application (SPA) vs Regular Web App

Key Capabilities Matrix for Web Applications

Native & Mobile Applications

Choosing Among Mobile & Desktop Types

Redirect URI & Security Matrix for Native Apps

Deep Linking & Mobile Association Files

Trustdesk Configuration Requirements

Published Endpoints and Response Format

1. iOS — `GET /.well-known/apple-app-site-association`

2. Android — `GET /.well-known/assetlinks.json`

Verification & Troubleshooting

Example Redirect URIs

Machine-to-Machine & Service Clients

Non-Interactive Client (`NON_INTERACTIVE`)

Special Purpose & Legacy Clients

Device (Limited Input Devices) (`DEVICE`)

Third Party (`THIRD_PARTY`)

SAML Identity Provider Registration (`SAML_SP`)

OAuth Flow Selection Matrix

Trustdesk Feature Availability Matrix