Article

    Single Sign-On (SSO)

    7 min read
    Last updated 5 days ago

    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

    1. Go to the Google Cloud Console (console.cloud.google.com).

    2. 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.
    3. 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.

    4. 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.

    5. Send to Unthread:

      • Client ID

      • Client Secret

    Method B: SAML (Legacy)

    1. Go to the Google Admin Console (admin.google.com).

    2. Navigate to Apps > Web and mobile apps.

    3. Click Add App > Add custom SAML app.

    4. Google IdP Details: Click Download Metadata (you will send this file to us). Click Continue.

    5. 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).

    6. Attribute Mapping: Map Primary Email to email, First Name to firstName, and Last Name to lastName.

    7. Enable App: By default, the app is OFF. Click on the app > User access > turn ON for everyone.

    ⚫ Okta

    1. Log in to your Okta Admin Console.

    2. Go to Applications > Applications.

    3. Click Create App Integration.

    4. Select OIDC - OpenID Connect as the Sign-in method.

    5. Select Web Application as the Application type. Click Next.

    6. 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.

    7. 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)

    1. Log in to your Okta Admin Console.

    2. Go to Applications > Applications.

    3. Click Create App Integration.

    4. Select SAML 2.0. Click Next.

    5. General Settings: Name the app "Unthread". Click Next.

    6. 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.

    7. Attribute Statements:

      • Name: email | Value: user.email

      • Name: firstName | Value: user.firstName

      • Name: lastName | Value: user.lastName

    8. Click Next and Finish.

    9. 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.

    1. Log in to the Microsoft Entra admin center (entra.microsoft.com).

    2. Go to Identity > Applications > App registrations.

    3. Click New registration.

    4. 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.

    5. 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).

    6. 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)

    1. Log in to the Microsoft Entra admin center (entra.microsoft.com).

    2. Go to Identity > Applications > Enterprise applications.

    3. Click New application > Create your own application.

    4. Name it "Unthread" and select Integrate any other application you don't find in the gallery (Non-gallery). Click Create.

    5. In the sidebar, select Single sign-on > SAML.

    6. 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.

    7. Attributes & Claims (Edit):

      • Ensure Unique User Identifier is mapped to user.userprincipalname or user.mail.
    8. 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.