IT Administrator Setup Guide

Enterprise Single Sign-On Configuration for Email Alerts
Organization: Sedgwick
Tenant ID: sedgwick
Environment: PROD
Base URL: https://scms.emailprioritization.com

Required Permissions Overview

Before proceeding with setup, review the permissions that Email Alerts requires to function properly. This will help you assess compatibility with your organization's security policies.

⚠ī¸ Important: Email Alerts operates entirely on behalf of individual users using delegated permissions. The application does not have or require application-level access to your organization's data.

Microsoft Graph API Permissions (Outlook Integration)

Email Alerts uses delegated permissions which allow the app to act on behalf of signed-in users. The app cannot access other users' data.

Permission Purpose Default Consent
offline_access Maintain access to data (enables refresh tokens for continuous monitoring) 👤 User can consent
User.Read Read user profile information (name, email) 👤 User can consent
Mail.Read Read emails for sentiment analysis 👤 User can consent*
Mail.ReadWrite Tag/categorize emails based on sentiment scores 👤 User can consent*
Mail.Send Send reply emails on behalf of the user (optional) 👤 User can consent*
MailboxSettings.Read Read mailbox settings and office hours (optional) 👤 User can consent
Team.ReadBasic.All List Microsoft Teams for notifications (optional) 👤 User can consent
Channel.ReadBasic.All List channels in Teams (optional) 👤 User can consent
Directory.Read.All Read all directory data (users, groups, organizational structure) 🔒 Admin consent always required
Organizational Features:
The permission highlighted in yellow provides organizational insights but typically requires admin approval:
  • Directory.Read.All: Displays full organizational structure including supervisor/manager relationships, reporting structures, and group memberships in the admin panel
Note: The application will function normally without this admin-consent permission, but organizational structure features in the admin panel will be limited.
⚠ī¸ Important - Organization Consent Policies:
*While these delegated permissions typically allow user consent, many organizations override this default behavior for security reasons:
  • Restricted Policy: Organization may require admin consent for ALL applications
  • Mail Permissions: Many organizations specifically require admin approval for Mail.* permissions due to their sensitive nature
  • Publisher Verification: Unverified publishers may require admin consent regardless of permission type
Check your policy: Microsoft Entra ID → Enterprise applications → Consent and permissions → User consent settings
💡 For Enterprise Deployments: We recommend having an administrator grant consent on behalf of all users during initial setup. This provides a smoother user experience and ensures consistent access across your organization.

Grant Admin Consent for Microsoft Graph

As an administrator, you can grant consent for all Microsoft Graph permissions on behalf of your entire organization. This eliminates the need for individual users to approve permissions.

Grant Admin Consent
⚠ī¸ Important: When prompted, you MUST check the box "Consent on behalf of your organization" before clicking Accept. If you don't check this box, consent will only be granted for your account, not the entire organization.
📝 Note on Application Architecture:
Your SAML Enterprise Application handles user authentication (login). When users first add email accounts, Microsoft automatically creates a separate OAuth application (named "Email Alerts - [YourTenant]") in your Enterprise Applications list for Microsoft Graph API access. This automatic creation is normal and expected behavior for multi-tenant applications.

Role-Based Access Control (RBAC)

Once users are authenticated via SSO, their permissions within Email Alerts are determined by their assigned role:

Role Key Permissions Typical Users
Global Admin
  • Create global rules and templates
  • User management
  • Role assignment
  • System configuration
  • View all analytics
 IT administrators, System owners
Regional Admin
  • Choose from allowed templates, view analytics
  • Configure integrations
  • Monitor system usage
 Team leads, Managers
Restricted User
(default for enterprise)
  • Cannot modify rules
  • View own emails/analytics
  • Apply approved templates only
  • Limited configuration options
 General employees
Security Best Practices:
  • ✅ All OAuth tokens are encrypted using AWS KMS
  • ✅ Webhook payloads are validated with signatures
  • ✅ Rate limiting prevents abuse (5 notifications/hour per user)
  • ✅ No passwords are stored - only OAuth tokens
  • ✅ Multi-tenant architecture ensures data isolation
  • ✅ Regular security audits and penetration testing

Quick Start - SSO Configuration

✅ SAML Configuration Complete

Single Sign-On has been successfully configured for Sedgwick.

Go to Login Page

🔐 Service Provider (Email Alerts) Configuration

These are Email Alerts's SAML settings that were provided to your Identity Provider:

SP Entity ID:
https://scms.emailprioritization.com
Assertion Consumer Service (ACS) URL:
https://scms.emailprioritization.com/saml/acs
Single Sign-On URL:
https://scms.emailprioritization.com/saml/sso
Single Logout Service (SLS) URL:
https://scms.emailprioritization.com/saml/sls
đŸ“Ĩ SP Metadata XML:

Download Email Alerts's SAML metadata for verification or re-import into your IdP

Download SP Metadata (XML)

đŸĸ Identity Provider (IdP) Configuration

Configuration received from your Identity Provider (Azure AD, Okta, etc.):

IdP Entity ID:
https://sts.windows.net/c2133cc5-d9c2-4b6d-8b3b-dce7e1b4ac91/
IdP Single Sign-On URL:
https://login.microsoftonline.com/c2133cc5-d9c2-4b6d-8b3b-dce7e1b4ac91/saml2
IdP Single Logout URL:
https://login.microsoftonline.com/c2133cc5-d9c2-4b6d-8b3b-dce7e1b4ac91/saml2
X.509 Certificate Fingerprint (SHA256):
8E:C4:A5:5B:98:20:7A:61:45:DB:CB:D8:DE:01:BA:D5:1A:F1:6F:58:F6:4D:E4:96:AF:BB:09:B6:05:E1:DE:F9

Certificate length: 1008 characters

đŸ“Ĩ IdP Metadata URL:

Access your Identity Provider's SAML metadata for verification

https://login.microsoftonline.com/c2133cc5-d9c2-4b6d-8b3b-dce7e1b4ac91/federationmetadata/2007-06/federationmetadata.xml?appid=3a822313-a5a5-45fd-bd1f-8fb16b447489
View IdP Metadata XML

📋 Configuration Audit

Configured At: 2025-10-02T17:03:58.719172+00:00
Configured From IP: 143.109.113.144, 170.85.102.125
ℹī¸ Configuration is Locked

For security reasons, SAML configuration cannot be changed once set. If you need to modify the configuration, please contact support.

SCIM User Provisioning

Automatically manage user accounts with SCIM 2.0. Use the same Enterprise Application for both SAML SSO and SCIM provisioning.

💡 Single Application Setup

You'll configure SCIM provisioning in the same Enterprise Application used for SAML SSO. This ensures consistent group assignments and simplified management.

SCIM Base URL:
https://scms.emailprioritization.com/scim/v2
Secret Token:
Checking token status...
Supported Operations:
  • Create User
  • Update User (including role changes)
  • Deactivate User
  • Group membership sync for role mapping

Setup Instructions for Microsoft Entra ID

Configure Provisioning in Your Enterprise Application

  1. Sign in to the Azure Portal
  2. Navigate to Microsoft Entra ID → Enterprise Applications
  3. Open your existing Email Alerts Enterprise Application (the same one used for SAML SSO)
  4. Go to the Provisioning tab in the left menu
  5. Click on + New configuration
  6. Under Admin Credentials:
    • Tenant URL: https://scms.emailprioritization.com/scim/v2
    • Secret Token: Use the token generated above
  7. Click Test Connection to verify
  8. Click Create if all goes well
  9. Under Settings, ensure:
    • Scope: "Sync only assigned users and groups" (recommended)
    • Provisioning Status: Will be set to "On" when you start provisioning

Configure Attribute Mappings

  1. Under Mappings, you'll see two sections:
    • Provision Microsoft Entra ID Users - For user synchronization
    • Provision Microsoft Entra ID Groups - For group synchronization (optional)
  2. Click "Provision Microsoft Entra ID Users"
  3. Review the default mappings (these are usually pre-configured correctly):
    Email Alerts Attribute ← Microsoft Entra ID Attribute
    userName ← userPrincipalName
    active ← Switch([IsSoftDeleted], , "False", "True", "True", "False")
    displayName ← displayName
    title ← jobTitle
    emails[type eq "work"].value ← mail
    preferredLanguage ← preferredLanguage
    name.givenName ← givenName
    name.familyName ← surname

    Note: Additional attributes may be shown. The most important ones for Email Alerts are userName, active, displayName, and emails.

  4. The Source Object should be set to "User" and Target Object will be automatically set to "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  5. Click Save
  6. Note: Group provisioning is handled separately. Email Alerts uses group names for role mapping, not group provisioning.

Assign Users and Groups

Assign the groups to your Enterprise Application for automatic role assignment:

  1. Go to Users and groups in your Enterprise Application
  2. Click Add user/group
  3. Create and assign these Microsoft Entra ID groups with EXACT names for automatic role mapping:
    ⚠ī¸ Important: Use these exact group names for automatic mapping:
    • Email Alerts-GlobalAdmins → Automatically maps to Global Admin role
    • Email Alerts-RegionalAdmins → Automatically maps to Regional Admin role
    • Email Alerts-Restricted → Automatically maps to Restricted User role

    Note: Groups with these exact names will be automatically mapped when provisioned via SCIM. Groups with different names will need manual mapping in the section below.

  4. These same groups control both SSO access and SCIM provisioning

Users not in any assigned group will receive the default role configured for your tenant.

Start Provisioning

  1. Go back to the Provisioning tab
  2. Under Settings, toggle Provisioning Status to On
  3. Click Save at the top of the page
  4. Microsoft Entra ID will start an initial sync cycle (this may take a few minutes)
  5. Monitor the Provisioning logs in the left menu for any errors
  6. Users will be synchronized automatically based on your group assignments
✅ Testing Your Configuration

After starting provisioning:

  • Check the admin panel at /admin/users to see provisioned users
  • Verify user roles are correctly assigned based on group membership
  • Test user login via SAML SSO
  • Monitor provisioning logs in Azure Portal for any sync issues

Email Domain Policy

Users in your organization can only add email accounts from these domains:

  • sedgwick.com

Group to Role Mapping

Configure how Microsoft Entra ID groups map to Email Alerts roles. This determines user permissions based on their group membership.

ℹī¸ How Group Mapping Works:
  • Users are assigned roles based on their Microsoft Entra ID group membership
  • If a user belongs to multiple groups, they receive the highest privilege role
  • Changes to group membership are reflected when users are provisioned or synced
ℹī¸ Authentication Required

You must be signed in as an administrator to configure group mappings.

Sign In with SSO
📍 Finding Group Object IDs:
  1. Go to Microsoft Entra ID admin center
  2. Navigate to Groups → All groups
  3. Click on your group (e.g., "Email Alerts-Admins")
  4. In the Properties section, copy the Object ID
  5. Add the mapping above using this Object ID

Microsoft Teams Integration

Enable real-time email alerts directly in Microsoft Teams. Users get notifications when angry emails are detected, helping teams respond quickly to customer issues.

✅ Automated Setup

The Azure Bot is automatically created and configured by Email Alerts. Just download the Teams app package below and upload it to your organization's Teams.

Step 1: Download & Upload Teams App

Download Custom Teams Manifest

Download a pre-configured Teams app package customized for Sedgwick:

Teams App Package:
đŸ“Ļ Download Teams App Package

This package contains the manifest and icons configured for your organization.

Upload to Teams

For Production (Teams Admin Center):

  1. Go to Microsoft Teams Admin Center
  2. Navigate to Teams apps → Manage apps
  3. Click Upload → Upload an app to your org's app catalog
  4. Select the downloaded angeralert-teams-sedgwick.zip file
  5. Click Publish to make it available to your organization

For Testing (Sideloading):

  1. Open Microsoft Teams
  2. Click Apps in the left sidebar
  3. Click Manage your apps → Upload an app
  4. Select Upload a custom app
  5. Choose the downloaded zip file
💡 Tip: Sideloading is great for testing. For organization-wide deployment, use Teams Admin Center.

Step 2: User Setup

For End Users: Once the app is available, users follow these simple steps:

Install & Link Account

  1. Open Microsoft Teams (desktop, web, or mobile)
  2. Click Apps in the left sidebar
  3. Search for "Email Alerts"
  4. Click on the app and select Add
  5. The bot will send a welcome message with a "Link Account" button
  6. Click Link Account to connect your Email Alerts account (OAuth)
  7. Complete the authorization (automatic if already logged in)
  8. Done! You'll now receive email alerts in Teams
✅ That's it! Users will automatically receive notifications for angry emails based on their Email Alerts rules.

Features Available

✅ What Users Get:
  • Automated Welcome: Bot greets users and provides account linking
  • Real-time Notifications: Get alerts for angry emails in Teams chat
  • Rich Cards: View email preview with sentiment scores
  • Quick Actions: Mark as responded, dismiss, or open in Outlook
  • Dashboard Access: Open Email Alerts dashboard directly from Teams
⚠ī¸ Current Limitations:
  • Personal Chats Only: Notifications sent to personal chat (channel support requires additional permissions)
  • Bot Commands: Interactive commands not yet available

Troubleshooting

Common Issues and Solutions

🔴 No welcome message from bot:
  • Remove and re-add the app to trigger the welcome message
  • Check that the app was uploaded successfully
  • Wait 1-2 minutes for bot to initialize
🔴 "App ID already exists" error when uploading:
  • The app was already uploaded - search for "Email Alerts" in Manage apps
  • Delete the old version first if you need to re-upload
🔴 App not appearing for users:
  • Wait 5-10 minutes for propagation
  • Check Teams admin center shows app as "Allowed"
  • Have users refresh Teams (Ctrl+R or Cmd+R)
🔴 OAuth/account linking fails:
  • Verify user has an active Email Alerts account
  • Try the "Link Account" button again
  • Check browser allows popups from Teams
🔴 Notifications not being received:
  • Verify account was successfully linked (check Settings → Integrations in Email Alerts dashboard)
  • Check anger threshold settings (default: 7.0)
  • Ensure email monitoring is active
  • Test with a known angry email sample
📚 Additional Resources:

Testing & Diagnostics

Test SAML Authentication

After completing the setup, test the SSO flow:

  1. Open an incognito/private browser window
  2. Navigate to your tenant URL: https://scms.emailprioritization.com
  3. You'll see the enterprise login page for Sedgwick
  4. Click "Sign in with Sedgwick SSO"
  5. You should be redirected to your identity provider (Microsoft Entra ID, Okta, etc.)
  6. Sign in with your corporate credentials
  7. After successful authentication, you'll be returned to Email Alerts dashboard
💡 Tip: If you don't see the enterprise login page, make sure you're accessing the correct tenant subdomain URL (https://scms.emailprioritization.com), not the main Email Alerts domain.
Download SP Metadata
Common SAML Issues:
  • Error: Invalid SAML Response - Check that the certificate is correctly configured
  • Error: User not found - Ensure the email attribute is correctly mapped
  • Error: No permissions - Verify group claims are configured and user is in appropriate groups

Troubleshooting Microsoft Graph Permissions

🔍 Common Permission Issues:
  • "Need admin approval" error when adding email accounts:
    • This occurs when users try to add email accounts but Directory.Read.All permission requires admin consent
    • Solution: Admin must grant consent via the button in the Required Permissions tab
    • When granting consent, admin MUST check "Consent on behalf of your organization" checkbox
  • Users still blocked after admin grants consent:
    • The admin may have granted personal consent only (didn't check the organization checkbox)
    • Solution: Admin should revoke their personal consent at myapps.microsoft.com, then re-grant with the checkbox checked
    • Alternatively, use a different admin account that hasn't consented yet
  • Finding the OAuth Enterprise Application:
    • Look for "Email Alerts Staging - Sedgwick" in your Enterprise Applications list
    • This app is automatically created by Microsoft when the first user attempts to consent
    • This is separate from your SAML Enterprise Application and is normal
💡 Quick Diagnostic Steps:
  1. Verify SAML SSO works (user can log in)
  2. Check if admin consent has been granted (see Required Permissions tab)
  3. Test adding an email account with a regular user
  4. If blocked, have admin grant consent with organization checkbox checked
  5. Users may need to sign out and back in for changes to take effect

Support & Next Steps

After Successful Configuration

  1. Send the SAML configuration details to Email Alerts support
  2. We'll complete the tenant configuration on our end
  3. Test with a pilot group of users
  4. Roll out to all users in your organization

Need Help?

Contact our enterprise support team:

Security Note: All authentication data is encrypted in transit and at rest. Email Alerts never stores your identity provider passwords. We only receive and validate SAML assertions from your IdP.