The Zendesk integration configures 1Kosmos as a SAML 2.0 identity provider, enabling biometric authentication for support agents, administrators, and optionally end users through the 1Kosmos mobile app.
Integration type
SSO
Updated
Overview
1Kosmos integrates with Zendesk as a SAML 2.0 identity provider, enabling support agents, administrators, and optionally end users (customers) to authenticate biometrically through the 1Kosmos mobile app. Zendesk supports multiple simultaneous SAML configurations and allows separate authentication policies for team members and end users.
The SAML configuration is performed in the Zendesk Admin Center under Account → Security → Single sign-on → Create SSO configuration → SAML. Zendesk accepts the IdP SSO URL, X.509 certificate fingerprint or full certificate, and optional logout URL. The Zendesk SP values are ACS URL https://[subdomain].zendesk.com/access/saml and Entity ID https://[subdomain].zendesk.com.
Zendesk's SAML implementation uses email addresses as user identifiers. All users who authenticate via 1Kosmos must have Zendesk accounts with email addresses that match their 1Kosmos records. Zendesk also provides a bypass URL (https://[subdomain].zendesk.com/access/normal) for admin access if SSO is misconfigured.
Prerequisites
Active 1Kosmos tenant: Administrator access to the AdminX portal. Contact 1kosmos.com/contact if not yet provisioned.
Zendesk administrator access: Admin access to the Zendesk Admin Center including Account → Security settings.
Agent and admin accounts provisioned: Support agents and administrators must have existing Zendesk accounts before SSO is enforced. End users can be auto-provisioned on first SSO login.
1Kosmos mobile app installed: Users must have the app on iOS or Android with biometrics enrolled before testing.
Configuration values
Values to collect from 1Kosmos AdminX (IdP) for Zendesk:
Field | Where to find it |
|---|---|
SAML SSO URL | AdminX → Settings → IdP Configuration → Single SignOn Service URL |
Certificate (SHA256 fingerprint or PEM) | AdminX → Settings → IdP Configuration → View Certificate. Zendesk accepts fingerprint or full certificate. |
Fixed Zendesk SP values to enter in AdminX:
Field | Value |
|---|---|
SP Entity ID | https://[subdomain].zendesk.com |
ACS URL | https://[subdomain].zendesk.com/access/saml |
NameID Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
Integration steps
Step 1: Add Zendesk as a SAML application in AdminX
Log in to the AdminX portal and navigate to Applications → Add Application.
Select SAML 2.0 Generic and click Add integration. Enter "Zendesk" as the Application Name and https://[subdomain].zendesk.com as the Application Access URL.
Set NameID Format to
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressand NameID Value to email. Add claims for email, first name (name), and last name (organizationif applicable). Enable Assertion signing.Enter
https://[subdomain].zendesk.comas the SP Entity ID andhttps://[subdomain].zendesk.com/access/samlas the ACS URL. Click Save.
Step 2: Create the SAML SSO configuration in Zendesk
Log in to Zendesk and navigate to Admin Center (the grid icon at the top right) → Account → Security → Single sign-on.
Click Create SSO configuration and select SAML.
Enter a recognizable Configuration Name (e.g., "1Kosmos Biometric SSO").
In the SAML SSO URL field, paste the 1Kosmos SSO Login URL.
In the Certificate fingerprint field, paste the SHA256 fingerprint of the 1Kosmos signing certificate.
Optionally enter a Remote Logout URL. Click Save.
Step 3: Assign the SAML configuration to team members
Return to Account → Security. Select Team member authentication.
Select External Authentication and choose the 1Kosmos SAML configuration. Select how members sign in (SSO only, or both SSO and password). Click Save.
Repeat for End user authentication if you also want to enable SSO for end-user customers.
Step 4: Test the integration
Open an incognito browser and navigate to
https://[subdomain].zendesk.com. Select the SSO sign-in option.Confirm you are redirected to 1Kosmos. Authenticate biometrically. Confirm you are logged in to Zendesk as an agent or admin.
Attribute mappings
Source (1Kosmos) | Target (Zendesk) | Description |
|---|---|---|
user.email | email / NameID | Must match the Zendesk agent or user account email |
user.firstName | name (first name portion) | Used for agent display name in Zendesk |
Integration notes
Zendesk allows up to two SAML and two JWT SSO configurations simultaneously, which enables organizations to configure different authentication paths for different user groups.
The bypass URL at https://[subdomain].zendesk.com/access/normal provides a password-based login path for administrators if SSO is misconfigured, ensuring continued access to the Zendesk account. Zendesk recommends keeping this option available during initial SSO testing before enforcing SSO-only authentication.
Email addresses used in Zendesk must be verified by the identity provider; unverified email addresses in the SAML assertion can result in unauthorized access risks.
