Skip to main content
Version: Latest (4.0.3)

SAML Integration

cidaas 4.x supports both SAML 2.0 roles. Which one you set up depends on the direction of trust:

RoleMeaningWhere to configureFull guide
cidaas as IdPUsers authenticate in cidaas; an external app (Service Provider) trusts cidaas and receives a signed SAML assertionIntegrations → Applications — create a SAML_SP applicationSAML SP Integration
cidaas as SPUsers authenticate at an external SAML IdP; cidaas consumes the assertion and creates/links the local userProviders → Identity Providers — add a SAML providerSAML 2.0 Single Sign-On

cidaas as Identity Provider (IdP)​

Users log in to cidaas SSO; the external application (the Service Provider) trusts cidaas and receives user identity via a signed — and optionally encrypted — SAML assertion. In Trustdesk this is modeled as a SAML_SP application: you register the external SP and cidaas handles issuing assertions.

Prerequisites​

  • Admin access to Trustdesk with app-create permissions (APP_CREATE, APP_MANAGER, or an equivalent role in CIDAAS_ADMINS).
  • The external SP's SAML metadata (XML), ready to paste in (up to 256 KB).
  • Any custom scopes you want the app to allow, created in advance.

Setup steps in cidaas​

  1. In Trustdesk, go to Integrations → Applications → + Create Application and choose the SAML Identity Provider template (creates a SAML_SP app).
  2. Complete the wizard: Basic information → OAuth settings → SAML configuration (paste the SP's metadata XML, set the NameID format, and optionally enable signing/encryption) → Attribute mapping → Review.
  3. After creation, use the app's SAML Metadata card to review or update the configuration (metadata, signing, encryption, attribute mapping) at any time.

→ For the full field-by-field wizard reference, see SAML SP Integration.

Runtime endpoints (cidaas IdP)​

The SP consumes these from cidaas. {{domain}} is your cidaas base domain and {{client_id}} is the SAML_SP app's client ID:

PurposeURL pattern
IdP metadata{{domain}}/saml-srv/idp/metadata/{{client_id}}
IdP-initiated login{{domain}}/saml-srv/idp/login/{{client_id}}
IdP logout{{domain}}/saml-srv/idp/logout/{{client_id}}

The IdP metadata URL and the signing/encryption certificates are shown read-only on the SAML Metadata card — share them with the SP administrator.

Setup in the external system​

Screens differ by product, but the flow is usually:

  1. Create a new SSO / SAML provider (name it e.g. "cidaas"). If only predefined vendors are listed and cidaas is missing, choose Custom SAML 2.0.
  2. Set the SAML SSO URL and issuer (entityID) from the cidaas IdP metadata ({{domain}}/saml-srv/idp/metadata/{{client_id}}).
  3. Copy the signing certificate from the cidaas SAML Metadata card into the external system.
  4. If the SP encrypts assertions, share its public certificate back so cidaas can encrypt (configure it under encryption in the SAML configuration step).

SAML attribute mapping​

Attribute mapping controls how cidaas user fields are emitted as SAML attributes so the SP can provision or match users. Each entry maps:

  • Field Key (field_key) — the cidaas user field.
  • External Key (external_key) — the SAML attribute name / URN the SP expects.
  • Data Type (data_type) — the SAML data type (e.g. string).
  • Optional Default — a fallback value.

Example mappings:

cidaas field key (field_key)SAML attribute (external_key)Data type
emailEmailstring
given_nameFirstNamestring
family_nameLastNamestring

Prefer a persistent identifier (such as sub) as the NameID when the SP supports it. Avoid using email as NameID if a changed email address should not create a new user in the SP.

Troubleshooting (cidaas as IdP)​

  • cidaas error page "An error occurred" — check query parameters such as error_code=AUTH10009; usually a missing or wrong redirect/ACS URL for the SP.
  • Parsing error / missing attribute after login — usually an incorrect SAML attribute mapping (e.g. a missing email/Email attribute).

cidaas as Service Provider (SP)​

Users authenticate at an external SAML IdP (e.g. corporate AD FS, Entra ID, or another SAML IdP). cidaas trusts that IdP, consumes the assertion, and creates or links the local user.

Setup steps in cidaas​

  1. Open Trustdesk and go to Providers → Identity Providers.
  2. Click + Add provider and select SAML as the standard type.
  3. Import the external IdP's metadata — paste the XML or provide a metadata URL to fetch it — or fill in the individual fields (SSO URL, entity ID, signing certificate).
  4. Configure attribute mapping and the user_id_attribute (which SAML attribute uniquely identifies the user for matching — often the NameID or a unique claim).
  5. Save the configuration, then enable the provider on the relevant applications under Integrations → Applications.

Runtime endpoints (cidaas SP)​

The external IdP uses these. {{provider}} is the SAML provider name you created:

PurposeURL pattern
SP metadata (for the IdP){{domain}}/saml-srv/sp/metadata/{{provider}}
Assertion Consumer Service (ACS){{domain}}/saml-srv/sp/acs/{{provider}}
Single Logout callback{{domain}}/saml-srv/sp/logout_callback/{{provider}}

cidaas generates its own SP signing/encryption certificates automatically; retrieve them from the provider configuration and share the public certificate with the IdP if it encrypts assertions.

Attribute mapping (SP)​

When cidaas is the SP, mapping defines how attributes received from the IdP become cidaas user attributes, using the same attribute_mapping structure:

  • external_key — the attribute name as it appears in the IdP's assertion.
  • field_key — the corresponding cidaas user field.
  • data_type — the SAML data type of the incoming attribute.
  • user_id_attribute (on the provider) — the attribute used to uniquely match/create the user.

→ For metadata, bindings (HTTP-POST vs HTTP-Redirect), signing, and encryption details, see SAML 2.0 Single Sign-On.

Next steps​