The Google Workspace integration replaces password login with biometric authentication via SAML 2.0, redirecting users to verify with the 1Kosmos mobile app
Integration type
API
Updated
Overview
1Kosmos integrates with Google Workspace as a SAML 2.0 identity provider, allowing users to sign in to Gmail, Google Drive, and other Workspace applications using passwordless authentication via the 1Kosmos mobile app. Supported biometric options include Touch ID, Face ID, and liveness-checked LiveID.
Admin access to Google Cloud Platform, the Google Admin Console, and the 1Kosmos AdminX portal are all required to complete this integration.
When a user enters their Google Workspace email address, they are redirected to the 1Kosmos AdminX portal to complete biometric authentication before being returned to their Workspace session.
Prerequisites
Active 1Kosmos tenant: Community administrator access to the AdminX portal. Contact 1kosmos.com/contact if your tenant is not yet provisioned.
Google Cloud Platform access: Ability to create projects and service accounts in GCP.
Google Admin Console access: Super Administrator rights, including access to Security → API controls for domain-wide delegation.
Service account with domain-wide delegation: Created in GCP and authorized in the Google Admin Console before beginning the AdminX setup. Full steps are in the integration steps below.
1Kosmos mobile app installed: Users must have the app on iOS or Android with biometrics enrolled before testing.
Configuration values
Values to collect from GCP after service account creation:
Service Account Email | Found in GCP → IAM & Admin → Service Accounts → [account] → Details |
Service Account Unique ID | Found in the same screen; used for domain-wide delegation |
Service Account Private Key | Downloaded as a JSON file from GCP → Service Accounts → Keys → Add Key |
Values to collect from AdminX after the one-click setup:
Integration steps
Step 1: Create a service account in Google Cloud Platform
Log in to console.cloud.google.com. Create a new project by clicking the project dropdown → New Project.
Enter a project name and organization, then click Create.
Once the project is active, navigate to All Products → IAM & Admin → Service Accounts and click Create Service Account.
Enter a name and description and click Done.
In the service account list, open the new account and copy the Email and Unique ID values for use in later steps.
Step 2: Grant domain-wide delegation
Log in to the Google Admin Console at admin.google.com.
Navigate to Security → API controls → Manage Domain Wide Delegation.
Click Add new. Enter the service account Unique ID as the Client ID.
Set the OAuth Scope to
https://apps-apis.google.com/a/feeds/domain/.Click Authorize.
Step 3: Generate a private key for the service account
Return to GCP and navigate to IAM & Admin → Service Accounts.
Open the service account and click the Keys tab. Click Add Key → Create new key, select JSON, and click Create.
The private key file downloads to your computer automatically.
Open the file and keep it ready for the AdminX setup step.
Step 4: Run the one-click integration in AdminX
Log in to the AdminX portal and navigate to Applications → Add Application.
Locate the Google Workspace SAML option under Pre-built integrations and click Add integration.
Enter the following values:
Application Name | Your chosen name |
Google Workspace Domain | yourdomain.org (no http:// or https://) |
Service Account Email | Copied from GCP service account details |
Admin Email | Your GCP project admin Gmail address |
Service Account Private Key | Paste the private_key value from the downloaded JSON file |
Click Connect. AdminX automatically generates the SAML SSO profile in your Google Workspace domain.
Step 5: Export the IdP signing certificate from AdminX
In the AdminX portal, navigate to Settings → IdP Configuration.
Copy the certificate details from the Signing Certificate section and save the content as a .cert file on your computer. This file is uploaded to Google Admin Console in the next step.
Step 6: Upload the signing certificate in Google Admin Console
Log in to admin.google.com. Navigate to Security → Settings → Set up single sign-on (SSO) with a third party IdP.
In the SSO profile for your organization section, click the Edit icon next to the 1Kosmos IdP entry.
In the Verification Certificate section, click Upload Certificate, select the .cert file exported from AdminX, and click Save.
Step 7: Test the integration
Navigate to mail.google.com.
Enter a Workspace user email address and click Next. You will be redirected to the 1Kosmos AdminX login screen displaying a QR code.
Open the 1Kosmos mobile app, tap Scan QR, scan the code, and complete biometric authentication.
Confirm you are logged into Google Workspace after successful authentication.
Test with a single user before enabling for the full organization.
Integration notes
The OAuth scope https://apps-apis.google.com/a/feeds/domain/ is required for the service account to modify organization-level SSO settings during the one-click setup. If the Connect step fails, confirm that domain-wide delegation was saved correctly for the service account Unique ID, not the Client ID field from the OAuth app registration. The signing certificate exported from AdminX must be uploaded to Google Admin Console to complete the trust relationship — the integration will fail if this step is skipped.
