Setting Up Single Sign-On (SSO)

Overview

Single Sign-On (SSO) enables your team to access Revuloop using your organization's identity provider, streamlining authentication and enhancing security. This guide walks you through setting up Microsoft Entra ID SSO for your Revuloop organization.

Key Benefits:

• Centralized user authentication and access control
• Enhanced security with your existing identity policies
• Streamlined user onboarding and offboarding
• Reduced password fatigue for team members

Requirements:

• Business plan subscription
• Microsoft Entra ID tenant
• Admin access to both Revuloop and Microsoft Entra
• Organization owner or admin role in Revuloop

Part 1: Microsoft Entra ID Configuration

Step 1: Create Enterprise Application

1. Sign in to the Azure Portal (portal.azure.com)
2. Navigate to Azure Active Directory
3. Select Enterprise Applications from the left sidebar
4. Click New application
5. Choose Create your own application
6. Enter application name: "Revuloop SSO"
7. Select "Integrate any other application you don't find in the gallery (Non-gallery)"
8. Click Create

Step 2: Configure OAuth 2.0 / OpenID Connect

1. In your new application, go to Overview
2. Click Set up single sign on
3. Select OAuth 2.0 / OpenID Connect as the method
4. Note the following values (you'll need them for Revuloop):
   • Tenant ID: Found in Azure AD Overview → Tenant information
   • Application (client) ID: Found in app registration Overview
   • Client Secret: You'll create this in the next step

Step 3: Create Client Secret

1. In your application, go to Certificates & secrets
2. Click New client secret
3. Enter a description: "Revuloop SSO Secret"
4. Choose expiration period (recommended: 24 months)
5. Click Add
6. IMPORTANT: Copy the secret Value immediately (you won't be able to see it again)
7. Store it securely: you'll need it for Revuloop configuration

Step 4: Configure Redirect URI

1. Go to Authentication in your application
2. Click Add a platform
3. Select Web
4. Add redirect URI: `https://app.revuloop.com/api/auth/callback/microsoft-entra`
5. For localhost testing, also add: `http://localhost:3000/api/auth/callback/microsoft-entra`
6. Click Configure

Step 5: Set API Permissions

Your application needs these Microsoft Graph permissions:

Required Permissions:

• `User.Read` - Read user profile
• `email` - Read user email address
• `openid` - OpenID Connect sign-in
• `profile` - Read user profile

For Group Sync (Optional but Recommended):

• `Group.Read.All` - Read all groups
• `User.Read.All` - Read all users' full profiles

To add permissions:

1. Go to API permissions
2. Click Add a permission
3. Select Microsoft Graph
4. Choose Delegated permissions
5. Search for and select each permission above
6. Click Add permissions
7. Click Grant admin consent (requires admin rights)
8. Confirm the consent grant

Part 2: Revuloop Configuration

Step 6: Access SSO Settings

1. Log in to Revuloop as an organization owner or admin
2. Navigate to Organization Settings (click organization name → Settings)
3. Select SSO from the left sidebar
4. You'll see four tabs: Configuration, Enforcement, Group Mappings, User Sync

Note: If you don't see the SSO tab, verify your organization is on the Business plan.

Step 7: Enter Provider Configuration

On the Configuration tab:

1. Provider: Microsoft Entra ID (pre-selected)
2. Tenant ID: Paste the tenant ID from Azure AD
3. Client ID: Paste the application (client) ID from Azure
4. Client Secret: Paste the client secret value you copied earlier
5. Click Save Configuration

Security Note: Client secrets are encrypted when saved and will be partially masked (e.g., `abc***xyz`) when displayed.

Step 8: Test SSO Connection

Before enabling SSO for your organization:

1. Click the Test Connection button
2. Revuloop validates credentials with Microsoft
3. If successful, you'll see: ✓ "Connection successful!"
4. If failed, check:
   • All credentials copied correctly (no extra spaces)
   • API permissions granted with admin consent
   • Redirect URI matches exactly (including https://)
   • Client secret hasn't expired

Step 9: Enable SSO

Once the connection test passes:

1. Toggle the Enable SSO switch to ON
2. Review the confirmation modal
3. Click Confirm
4. SSO is now active for testing

Part 3: Testing SSO Login

Test the Login Flow

1. Open a new incognito/private browser window
2. Go to Revuloop login page
3. Enter your work email address
4. Click Continue
5. If your email domain is recognized, you'll see "Sign in with Microsoft" button
6. Click Sign in with Microsoft
7. Complete Microsoft authentication (if not already signed in)
8. You should be redirected to Revuloop dashboard

Verify User Provisioning

After your first SSO login:

1. Go to Organization → Members
2. Verify your user account appears
3. Check for "SSO Linked" badge next to your name
4. Confirm email and display name are correct

What Happens During First Login (JIT Provisioning):

• Revuloop automatically creates your user account
• Profile populated from Microsoft (name, email)
• SSO link established
• Default member role assigned

Part 4: Group Mappings (Optional)

Map Azure AD groups to Revuloop departments for automatic role assignment.

Step 1: Fetch Groups from Microsoft

1. Go to SSO Settings → Group Mappings tab
2. Click Fetch Groups from Directory
3. Revuloop retrieves all groups from your Azure AD
4. Groups appear in the mapping table

Step 2: Map Groups to Departments

For each Azure AD group:

1. Select the group from the list
2. Choose corresponding Revuloop department
3. Toggle Auto Sync if you want automatic updates
4. Click Save Mapping

Example Mappings:

• Azure AD "Engineering Team" → Revuloop "Engineering Department"
• Azure AD "Sales Team" → Revuloop "Sales Department"
• Azure AD "Marketing" → Revuloop "Marketing Department"

Benefits of Group Mappings

• Automatic department assignment when users log in via SSO
• Easy reorganization - update groups in Azure, sync to Revuloop
• Consistent structure between Azure AD and Revuloop

Common Use Cases

Use Case 1: New Employee Onboarding

Scenario: Your company hires a new team member

Traditional Flow:

1. IT creates Azure AD account
2. Someone manually invites them to Revuloop
3. They create account, set password
4. Admin assigns to correct department

With SSO:

1. IT creates Azure AD account and assigns to group
2. Employee clicks Revuloop link
3. Signs in with work credentials
4. Account auto-created, auto-assigned to department
5. Ready to work immediately

Use Case 2: Department Reorganization

Scenario: Engineering team splits into Frontend and Backend teams

With Group Mappings:

1. IT creates two new Azure AD groups
2. Moves users to appropriate groups
3. Admin maps groups to Revuloop departments
4. Click Sync Users
5. All department assignments update automatically

Use Case 3: Employee Offboarding

Scenario: Team member leaves the company

With SSO:

1. IT disables Azure AD account
2. SSO access to Revuloop immediately revoked
3. User cannot authenticate
4. No manual Revuloop account management needed

Tips and Best Practices

Security Best Practices

• Rotate secrets regularly: Update client secret every 6-12 months
• Use conditional access: Configure in Azure AD for additional security
• Enable MFA: Require multi-factor authentication in Microsoft Entra
• Monitor SSO logs: Review authentication attempts regularly
• Audit group memberships: Ensure users in correct groups

Rollout Strategy

• Start small: Test with IT team or small pilot group
• Communicate early: Announce SSO 2-4 weeks before enforcement
• Provide documentation: Share this guide with your team
• Offer support: Have support team ready for questions
• Use grace period: Give users time to link accounts before enforcement

Maintenance Checklist

Monthly:

• Review SSO login logs for unusual activity
• Update group mappings when org structure changes
• Check for expired or expiring client secrets

Quarterly:

• Test SSO connection to verify functionality
• Review and update API permissions if needed
• Audit user access and department assignments

Annually:

• Rotate client secrets
• Review SSO security policies
• Assess group mapping effectiveness

Troubleshooting

Issue: "Invalid Client Secret"

Symptoms: Error message when saving configuration or testing connection

Common Causes:

• Client secret copied incorrectly
• Client secret has expired
• Wrong secret ID copied instead of secret value

Solutions:

1. Generate a new client secret in Azure portal
2. Copy the Value field (not the Secret ID)
3. Update in Revuloop SSO settings
4. Test connection again

Issue: "Redirect URI Mismatch"

Symptoms: Error after Microsoft authentication, can't redirect back to Revuloop

Common Causes:

• Redirect URI not configured in Azure app
• URI has typo or extra characters
• Using http instead of https

Solutions:

1. Go to Azure app → Authentication
2. Verify redirect URI: `https://app.revuloop.com/api/auth/callback/microsoft-entra`
3. Ensure exact match (no trailing slash)
4. Save changes and test again

Issue: "Insufficient Permissions"

Symptoms: Can't fetch groups, or limited user information available

Common Causes:

• Required API permissions not granted
• Admin consent not provided
• Permissions granted but not saved

Solutions:

1. Go to Azure app → API permissions
2. Verify all required permissions listed
3. Click Grant admin consent for [your organization]
4. Wait a few minutes for changes to propagate
5. Test connection again

Issue: User Can't Sign In with SSO

Symptoms: User gets error when trying to authenticate

Debugging Steps:

1. Verify user exists in Azure AD
2. Check user is assigned to Revuloop enterprise application:
   • Azure app → Users and groups
   • Add user if missing
3. Verify user's email domain matches allowed domains in Revuloop
4. Check SSO is enabled in Revuloop
5. Try testing with a different user

Issue: Groups Not Syncing

Symptoms: Group mappings configured but users not assigned to departments

Common Causes:

• Missing `Group.Read.All` permission
• Auto-sync disabled for mapping
• User not actually in Azure AD group

Solutions:

1. Verify `Group.Read.All` permission granted in Azure
2. Check auto-sync toggle is ON for group mapping
3. Confirm user's group membership in Azure AD
4. Click Sync Users button manually
5. Check sync status in User Sync tab