Single Sign-On (SSO)
Unthread supports Single Sign-On (SSO) to allow your team to log in using your existing identity provider (Google, Okta, Microsoft Entra ID, etc.).
We support two protocols:
-
OIDC (OpenID Connect): Strongly Recommended. It is more secure, easier to set up, and modern.
-
SAML 2.0: Supported for legacy requirements.
⚡️ Configuration Cheat Sheet
Regardless of which provider you use, you will need these values during setup.
Callback / Redirect / ACS URL:
https://{tenant-name}.unthread.io/__/auth/handler
Entity ID / Audience URI:
unthread
🔵 Google Workspace
Method A: OIDC (Recommended)
-
Go to the Google Cloud Console (console.cloud.google.com).
-
Create a New Project (e.g., "Internal-SSO").
- Tip: Use a new project rather than an existing external one to ensure proper internal security controls.
-
Configure Consent Screen:
-
Navigate to APIs & Services > OAuth consent screen.
-
Select Internal (This ensures only your employees can login).
-
Fill in the App Name ("Unthread") and User Support Email.
-
Click Save.
-
-
Create Credentials:
-
Navigate to APIs & Services > Credentials.
-
Click + CREATE CREDENTIALS > OAuth client ID.
-
Application type: Select Web application.
-
Authorized redirect URI: Paste the Callback URL from the Cheat Sheet above.
-
Click Create.
-
-
Send to Unthread:
-
Client ID
-
Client Secret
-
Method B: SAML (Legacy)
-
Go to the Google Admin Console (admin.google.com).
-
Navigate to Apps > Web and mobile apps.
-
Click Add App > Add custom SAML app.
-
Google IdP Details: Click Download Metadata (you will send this file to us). Click Continue.
-
Service Provider Details:
-
ACS URL: Paste the Callback URL from the Cheat Sheet above.
-
Entity ID: Paste the Entity ID (unthread).
-
Name ID: Select Basic Information > Primary Email.
-
Name ID Format: EMAIL (or UNSPECIFIED).
-
-
Attribute Mapping: Map Primary Email to email, First Name to firstName, and Last Name to lastName.
-
Enable App: By default, the app is OFF. Click on the app > User access > turn ON for everyone.
⚫ Okta
Method A: OIDC (Recommended)
-
Log in to your Okta Admin Console.
-
Go to Applications > Applications.
-
Click Create App Integration.
-
Select OIDC - OpenID Connect as the Sign-in method.
-
Select Web Application as the Application type. Click Next.
-
General Settings:
-
App integration name: Unthread.
-
Sign-in redirect URIs: Paste the Callback URL from the Cheat Sheet above.
-
Assignments: Select "Allow everyone in your organization to access" (or assign specific groups).
-
Click Save.
-
-
Send to Unthread:
-
Client ID (Found on the General tab).
-
Client Secret (Found on the General tab).
-
Okta Domain / Issuer: Usually https://{your-org}.okta.com.
-
Method B: SAML (Legacy)
-
Log in to your Okta Admin Console.
-
Go to Applications > Applications.
-
Click Create App Integration.
-
Select SAML 2.0. Click Next.
-
General Settings: Name the app "Unthread". Click Next.
-
Configure SAML:
-
Single sign on URL: Paste the Callback URL from the Cheat Sheet above.
-
Audience URI (SP Entity ID): Paste the Entity ID (unthread).
-
Name ID format: EmailAddress.
-
Application username: Email.
-
-
Attribute Statements:
-
Name: email | Value: user.email
-
Name: firstName | Value: user.firstName
-
Name: lastName | Value: user.lastName
-
-
Click Next and Finish.
-
Send to Unthread:
-
Go to the Sign On tab of your new app.
-
Click Identity Provider metadata (blue link) to download the XML file. Send us this file.
-
🟦 Microsoft Entra ID (Azure AD)
Required API Permissions
Your Azure AD app registration needs the following Microsoft Graph Application permissions (not Delegated). Grant admin consent after adding them.
User.Read.All - Look up Entra users by email address.
Group.Read.All - List and search Entra groups.
GroupMember.ReadWrite.All - Add and remove users from Entra groups.
Method A: OIDC (Recommended)
-
Log in to the Microsoft Entra admin center (entra.microsoft.com).
-
Go to Identity > Applications > App registrations.
-
Click New registration.
-
Register an application:
-
Name: Unthread.
-
Supported account types: Single tenant (Accounts in this organizational directory only).
-
Redirect URI (Platform): Select Single Page Application.
-
Redirect URI (URL): Paste the Callback URL from the Cheat Sheet above.
-
Add another Redirect URI (Web): https://auth.unthread.io/__/auth/handler
-
Click Register.
-
-
Create Secret:
-
In the sidebar, click Certificates & secrets.
-
Click New client secret. Give it a description and expiry. Click Add.
-
Important: Copy the Value immediately (you won't see it again).
-
-
Send to Unthread:
-
Application (client) ID (Found on the Overview page).
-
Directory (tenant) ID (Found on the Overview page).
-
Client Secret Value (The string you just copied).
-
Method B: SAML (Legacy)
-
Log in to the Microsoft Entra admin center (entra.microsoft.com).
-
Go to Identity > Applications > Enterprise applications.
-
Click New application > Create your own application.
-
Name it "Unthread" and select Integrate any other application you don't find in the gallery (Non-gallery). Click Create.
-
In the sidebar, select Single sign-on > SAML.
-
Basic SAML Configuration (Edit):
-
Identifier (Entity ID): Paste the Entity ID (unthread).
-
Reply URL (Assertion Consumer Service URL): Paste the Callback URL from the Cheat Sheet above.
-
Click Save.
-
-
Attributes & Claims (Edit):
- Ensure Unique User Identifier is mapped to user.userprincipalname or user.mail.
-
Send to Unthread:
-
Under SAML Certificates, find Federation Metadata XML.
-
Click Download. Send us this file.
-
JumpCloud SSO
1. Create the OIDC App in JumpCloud
- Log in to the JumpCloud Admin Portal.
- Go to User Authentication > SSO Applications (or Access > SSO Applications).
- Click + Add New Application.
- Search for OIDC or select Custom Application.
- Choose Manage Single Sign-On (SSO) and select Configure SSO with OIDC, then click next.
- Enter a Display Label (application name) and click next or configure application
2. Configure SSO Settings
- Navigate to the SSO tab of the new application.
- Enter your application's Redirect URI: https://unthread.io/_/auth/handler.
- Enter the application's Login URL: https//insert your company name.unthread.io/login
- Select the appropriate Client Authentication Type of Client Secret Basic.
- Under Standard Scopes, select Email and Profile
3. Activate and Copy Credentials
- Click Activate or Save to create the application.
- Copy and securely store the generated Client ID and Client Secret.
- Note your JumpCloud Issuer URL (
https://oauth.id.jumpcloud.com) and add it to the issuer URL field in the SSO OIDC protocol in the Unthread platform under Security --> Single Sign On
4. Complete Setup in Your Application and Assign Users
- Paste the Client ID, Client Secret, and OIDC/Issuer endpoints into the SSO OIDC protocol in the Unthread platform under Security --> Single Sign On.
- Return to JumpCloud, open the application's User Groups tab, and assign the appropriate user groups that need access.