Authentication & SSO

Supported Identity Providers

Junet supports two major identity providers:

1. Google Workspace - For organizations using Google services
2. Microsoft Entra ID - For organizations using Microsoft 365 / Azure

Configuring Google Workspace SSO

Prerequisites

• Google Workspace admin account
• Domain verified in Google Workspace
• Users must have Google Workspace accounts

Step 1: Access Google Cloud Console

1. Go to Google Cloud Console
2. Sign in with your Google Workspace admin account
3. Select your project or create a new one

Step 2: Enable Required APIs

1. Navigate to APIs & Services → Library
2. Enable the following APIs:
   • Google+ API (for user profile)
   • Admin SDK API (for group sync)
   • People API (for user information)

Step 3: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials

2. Click "Create Credentials" → "OAuth client ID"

3. Configure the consent screen if prompted:

   • User Type: Internal (for Workspace) or External
   • Application Name: "Junet"
   • Scopes: Add required scopes (email, profile, groups)

4. Application Type: Web application

5. Name: "Junet SSO"

6. Authorized JavaScript origins:

   • https://your-junet-domain.com
   • Add your production URL

7. Authorized redirect URIs:

   • https://your-junet-domain.com/api/auth/callback/google
   • This is where Google redirects after authentication

8. Click "Create"

9. Save the credentials:

   • Client ID
   • Client Secret

Step 4: Configure in Junet

1. Navigate to Junet Admin Panel

   • Admin → Application Settings → Authentication

2. Select "Google Workspace"

3. Enter Configuration:

   • Client ID: Paste from Google Cloud Console
   • Client Secret: Paste from Google Cloud Console
   • Domain: Your Google Workspace domain (e.g., company.com)

4. Enable Group Sync (Optional):

   • Toggle "Sync Groups from Google Workspace"
   • This allows automatic group import and synchronization

5. Click "Save Configuration"

6. Test the Connection:

   • Click "Test SSO Connection"
   • You should be redirected to Google login
   • Verify successful authentication

Google Workspace Permissions

Junet requires the following OAuth scopes:

• https://www.googleapis.com/auth/userinfo.email - Read user email
• https://www.googleapis.com/auth/userinfo.profile - Read user profile
• https://www.googleapis.com/auth/admin.directory.group.readonly - Read groups (for group sync)
• https://www.googleapis.com/auth/admin.directory.user.readonly - Read user directory (for group membership)

Configuring Microsoft Entra ID (Azure AD) SSO

Prerequisites

• Microsoft Entra ID (Azure AD) tenant
• Global Administrator or Application Administrator role
• Users must have Entra ID accounts

Step 1: Register Application in Entra ID

1. Go to Azure Portal

2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

3. Select App registrations → New registration

4. Register Application:

   • Name: "Junet SSO"
   • Supported account types:
     • "Accounts in this organizational directory only" (Single tenant)
   • Redirect URI:
     • Platform: Web
     • URI: https://your-junet-domain.com/api/auth/callback/entra

5. Click "Register"

6. Save the Application Details:

   • Application (client) ID - You'll need this
   • Directory (tenant) ID - You'll need this

Step 2: Create Client Secret

1. In your app registration, go to Certificates & secrets
2. Click "New client secret"
3. Description: "Junet SSO Secret"
4. Expires: Choose duration (24 months recommended)
5. Click "Add"
6. Copy the secret value immediately - It won't be shown again!

Step 3: Configure API Permissions

This is crucial for Junet to access user and group information.

1. Go to API permissions in your app registration

2. Click "Add a permission" → "Microsoft Graph"

3. Add the following permissions:

Permission 1: User.Read (Delegated)

• Type: Delegated
• Permission: User.Read
• Description: Sign in and read user profile
• Admin Consent Required: No
• Purpose: Allows users to sign in and Junet to read their profile

Permission 2: User.Read.All (Application)

• Type: Application
• Permission: User.Read.All
• Description: Read all users' full profiles
• Admin Consent Required: Yes
• Purpose: Allows Junet to read user directory for group membership and user provisioning

How to add:

1. Click "Add a permission"
2. Select "Microsoft Graph"
3. Choose "Application permissions"
4. Search for "User.Read.All"
5. Check the box
6. Click "Add permissions"

Permission 3: Group.Read.All (Application)

• Type: Application
• Permission: Group.Read.All
• Description: Read all groups
• Admin Consent Required: Yes
• Purpose: Allows Junet to read group information and membership for automatic group synchronization

How to add:

1. Click "Add a permission"
2. Select "Microsoft Graph"
3. Choose "Application permissions"
4. Search for "Group.Read.All"
5. Check the box
6. Click "Add permissions"

Step 4: Grant Admin Consent

After adding all permissions:

1. Click "Grant admin consent for [Your Organization]"
2. Confirm by clicking "Yes"
3. Wait for the consent to be granted
4. Verify all permissions show "Granted for Default Directory" in green

Permission Summary:

Step 5: Configure in Junet

1. Navigate to Junet Admin Panel

   • Admin → Application Settings → Authentication

2. Select "Microsoft Entra ID"

3. Enter Configuration:

   • Application (Client) ID: From Step 1
   • Directory (Tenant) ID: From Step 1
   • Client Secret: From Step 2
   • Tenant Domain: Your organization's domain (e.g., company.com)

4. Enable Group Sync (Optional):

   • Toggle "Sync Groups from Entra ID"
   • This allows automatic group import and synchronization
   • Requires Group.Read.All permission

5. Click "Save Configuration"

6. Test the Connection:

   • Click "Test SSO Connection"
   • You should be redirected to Microsoft login
   • Verify successful authentication
   • Check that user information is retrieved correctly

Entra ID Permissions Explained

Why these specific permissions?

User.Read (Delegated):

• Allows individual users to sign in
• Reads basic profile (name, email)
• No admin consent needed
• User consents on first login

User.Read.All (Application):

• Required for automatic user provisioning
• Allows Junet to read all user profiles in your directory
• Needed to verify group membership
• Required for Just-in-Time (JIT) provisioning
• Requires admin consent

Group.Read.All (Application):

• Required for group synchronization
• Allows Junet to read group information
• Enables automatic group import from Entra ID
• Keeps group membership up-to-date
• Required for automatic permission management
• Requires admin consent

SSO Login Flow

How Users Sign In

1. User navigates to Junet
2. Clicks "Sign in with [Google/Microsoft]"
3. Redirected to Identity Provider:
   • Google Workspace login page
   • Microsoft Entra ID login page
4. User enters credentials (if not already signed in)
5. Identity Provider verifies user
6. User redirected back to Junet
7. Junet creates or updates user account:
   • Profile information synced
   • Group memberships synced (if enabled)
   • Permissions applied based on groups
8. User accesses Junet chat interface

First-Time Login

When a user logs in for the first time via SSO:

1. Account Auto-Creation:

   • User account created automatically in Junet
   • Profile populated from IDP (name, email, photo)
   • No manual user creation needed

2. Group Assignment:

   • If group sync is enabled:
     • User's IDP groups are checked
     • Matching Junet groups are assigned
     • Permissions applied immediately

3. Welcome Experience:

   • User sees welcome message
   • Guided through available agents
   • Can start chatting immediately

Group Synchronization

When SSO is enabled with group sync, Junet automatically:

What Gets Synced

From Google Workspace:

• All groups the user belongs to
• Group names and descriptions
• Nested group membership
• Updates every 15 minutes

From Entra ID:

• Security groups
• Microsoft 365 groups
• Nested group membership
• Group metadata
• Updates every 15 minutes

How to Use Synced Groups

1. Import Groups:

   • Admin Panel → User Management → Groups
   • Click "Import Group from IDP"
   • Select groups to import
   • Configure Junet-specific permissions

2. Automatic Membership:

   • When users sign in, their group memberships sync automatically
   • Changes in IDP reflect in Junet within 15 minutes
   • No manual user assignment needed

3. Manage Permissions:

   • Configure agent access per group
   • Configure connection access per group
   • Users inherit permissions from all their groups

Troubleshooting

Google Workspace SSO Issues

Error: "redirect_uri_mismatch"

Cause: Redirect URI in Google Cloud Console doesn't match Junet's callback URL

Solution:

1. Go to Google Cloud Console → Credentials
2. Edit OAuth 2.0 Client ID
3. Add exact redirect URI: https://your-domain.com/api/auth/callback/google
4. Include both HTTP and HTTPS if testing locally

Error: "access_denied"

Cause: User doesn't have permission or app needs verification

Solution:

1. Verify user is in your Google Workspace domain
2. Check OAuth consent screen configuration
3. Ensure app is set to "Internal" for Workspace users
4. Complete app verification if using "External"

Groups Not Syncing

Cause: Missing Admin SDK API permissions

Solution:

1. Enable Admin SDK API in Google Cloud Console
2. Ensure service account has domain-wide delegation
3. Grant required scopes in Workspace Admin console

Entra ID SSO Issues

Error: "invalid_client"

Cause: Client ID or Client Secret is incorrect

Solution:

1. Verify Client ID in Junet matches Azure App Registration
2. Check Client Secret hasn't expired
3. Generate new secret if needed
4. Update Junet configuration

Error: "unauthorized_client"

Cause: Redirect URI mismatch or app not authorized

Solution:

1. Check redirect URI in Azure App Registration
2. Verify it matches: https://your-domain.com/api/auth/callback/entra
3. Ensure URL is exact (including https, no trailing slash)

Error: "AADSTS65001: The user or administrator has not consented"

Cause: Required permissions not granted by admin

Solution:

1. Go to Azure Portal → App registrations
2. Select your Junet app
3. Go to API permissions
4. Click "Grant admin consent for [Organization]"
5. Confirm the action

Groups Not Syncing

Cause: Group.Read.All permission not granted or not consented

Solution:

1. Verify Group.Read.All permission is added
2. Ensure it's an Application permission (not Delegated)
3. Click "Grant admin consent"
4. Wait a few minutes for consent to propagate
5. Test connection in Junet

Users Can't Sign In

Cause: Various possible issues

Solution Checklist:

• ✅ Verify users exist in Entra ID
• ✅ Check users are not blocked
• ✅ Verify all permissions are granted
• ✅ Check redirect URI is correct
• ✅ Test with admin account first
• ✅ Review Azure AD sign-in logs

Testing SSO Configuration

Step-by-step testing:

1. Test with Admin Account First:

   • Reduces permission issues
   • Confirms basic flow works
   • Can troubleshoot easier

2. Check Network Tab:

   • Open browser DevTools
   • Monitor network requests
   • Look for 401/403 errors
   • Check redirect chains

3. Review Logs:

   • Google: Check Admin console logs
   • Azure: Check Entra ID sign-in logs

4. Test Different Users:

   • Test with regular user (non-admin)
   • Test with user in different groups
   • Verify permissions are correct