[Beta] Spotlight.ai Outlook Connector Setup

This guide walks you through configuring the Spotlight.ai Outlook Connector so it only accesses specific users’ mailboxes (instead of your entire organization).

Overview

To securely configure the connector, you will:

  1. Modify a PowerShell script to reflect your environmental preferences
  2. Run the PowerShell script as a Microsoft Entra Global Administrator
  3. Add users to the security group created by the PowerShell script
  4. Have a Teams Meeting to complete the setup steps with Spotlight.ai

Step 1: Modify the following PowerShell script

  1. Create a local PowerShell script. It takes a parameter for your domain. If desired, you can adjust the $ServiceAccountUpn to name the service account something other than svc-spotlightai@yourdomain.com.
# ============================================================
# Spotlight.ai Outlook Access Setup
# Run as Global Admin / Exchange Admin
# ============================================================

param(
    [Parameter(Mandatory)]
    [string]$TenantDomain,

    [string]$ServiceAccountUpn = "svc-spotlightai@$TenantDomain",
    [string]$ExistingUserId,

    [string]$GroupName = "Spotlight.ai Outlook Access",
    [string]$GroupAlias = "SpotlightaiOutlookAccess",
    [string]$ExistingGroupId
)

$appId = "c432a077-80d1-4481-9b10-c39d59c71c60"
$ErrorActionPreference = "Stop"

# ------------------------------------------------------------
# Helpers
# ------------------------------------------------------------

function Write-Step($msg) { Write-Host "`n==> $msg" -ForegroundColor Cyan }
function Write-Done($msg) { Write-Host "    $msg" -ForegroundColor Green }
function Write-Warn($msg) { Write-Host "    WARNING: $msg" -ForegroundColor Yellow }

# ------------------------------------------------------------
# Install / import required modules
# ------------------------------------------------------------

Write-Step "Checking required modules..."

foreach ($mod in @("Microsoft.Graph", "ExchangeOnlineManagement")) {
    if (-not (Get-Module -ListAvailable -Name $mod)) {
        Write-Host "    Installing $mod..."
        Install-Module $mod -Scope CurrentUser -Force
    }
    Import-Module $mod
}

# ------------------------------------------------------------
# Connect
# ------------------------------------------------------------

Write-Step "Connecting to Microsoft Graph and Exchange Online..."
Write-Host "    Two separate login prompts will appear. Both require Global Admin or Exchange Admin."

Connect-MgGraph -Scopes "Group.ReadWrite.All","User.ReadWrite.All","Application.ReadWrite.All","AppRoleAssignment.ReadWrite.All"
Connect-ExchangeOnline

# ------------------------------------------------------------
# Service account
# ------------------------------------------------------------

if ($ExistingUserId) {
    Write-Step "Using existing service account (ID: $ExistingUserId)..."
    $serviceAccount = Get-MgUser -UserId $ExistingUserId
    if (-not $serviceAccount) {
        throw "Could not find user with ID: $ExistingUserId"
    }
    Write-Done "Found service account: $($serviceAccount.UserPrincipalName)"
} else {
    Write-Step "Checking for existing service account ($ServiceAccountUpn)..."
    $serviceAccount = Get-MgUser -Filter "userPrincipalName eq '$ServiceAccountUpn'" -ErrorAction SilentlyContinue

    if ($serviceAccount) {
        Write-Warn "Service account already exists — skipping creation."
    } else {
        $password = -join ((33..126) | Get-Random -Count 32 | ForEach-Object { [char]$_ })

        $passwordProfile = @{
            Password                      = $password
            ForceChangePasswordNextSignIn = $false
        }

        $serviceAccount = New-MgUser `
            -DisplayName "Spotlight.ai Service Account" `
            -UserPrincipalName $ServiceAccountUpn `
            -AccountEnabled:$true `
            -PasswordProfile $passwordProfile `
            -MailNickname "svc-spotlightai"

        Write-Done "Service account created: $ServiceAccountUpn"

        $credFile = Join-Path $env:USERPROFILE "spotlight-service-account-credentials.txt"
        @"
Spotlight.ai Service Account Credentials
Generated: $(Get-Date)

UPN:      $ServiceAccountUpn
Password: $password

IMPORTANT: Store this password securely and delete this file.
You will need it in Step 4 to authenticate with Spotlight.ai.
"@ | Set-Content -Path $credFile

        Write-Done "Credentials saved to: $credFile"
        Write-Warn "Delete this file after storing the password securely."
    }
}

# ------------------------------------------------------------
# Security group
# ------------------------------------------------------------

if ($ExistingGroupId) {
    Write-Step "Using existing security group (ID: $ExistingGroupId)..."
    $group = Get-MgGroup -GroupId $ExistingGroupId
    if (-not $group) {
        throw "Could not find group with ID: $ExistingGroupId"
    }
    Write-Done "Found security group: $($group.DisplayName)"
} else {
    Write-Step "Checking for existing security group ($GroupName)..."
    $group = Get-MgGroup -Filter "displayName eq '$GroupName'" -ErrorAction SilentlyContinue

    if ($group) {
        Write-Warn "Security group already exists (Object ID: $($group.Id)) — skipping creation."
    } else {
        $group = New-MgGroup `
            -DisplayName $GroupName `
            -MailEnabled:$false `
            -SecurityEnabled:$true `
            -MailNickname $GroupAlias

        Write-Done "Security group created: $GroupName (Object ID: $($group.Id))"
    }
}

# ------------------------------------------------------------
# Service principal + admin consent
# ------------------------------------------------------------

Write-Step "Checking for existing service principal (App ID: $appId)..."

$sp = Get-MgServicePrincipal -Filter "appId eq '$appId'" -ErrorAction SilentlyContinue

if ($sp) {
    Write-Warn "Service principal already exists — skipping creation."
} else {
    $sp = New-MgServicePrincipal -AppId $appId
    Write-Done "Service principal created."
}

if (-not $sp) {
    throw "Failed to create or retrieve service principal for App ID: $appId"
}

Write-Step "Granting admin consent for Mail.Read..."

$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"
$mailReadRole = $graphSp.AppRoles | Where-Object { $_.Value -eq "Mail.Read" }

if (-not $mailReadRole) {
    throw "Could not find Mail.Read app role on Microsoft Graph service principal."
}

$existingGrant = Get-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -ErrorAction SilentlyContinue |
    Where-Object { $_.AppRoleId -eq $mailReadRole.Id }

if ($existingGrant) {
    Write-Warn "Mail.Read already consented — skipping."
} else {
    New-MgServicePrincipalAppRoleAssignment `
        -ServicePrincipalId $sp.Id `
        -PrincipalId $sp.Id `
        -ResourceId $graphSp.Id `
        -AppRoleId $mailReadRole.Id | Out-Null

    Write-Done "Admin consent granted for Mail.Read."
}

# ------------------------------------------------------------
# Application access policy
# ------------------------------------------------------------

Write-Step "Checking for existing Application Access Policy..."

$existingPolicy = Get-ApplicationAccessPolicy -ErrorAction SilentlyContinue |
    Where-Object { $_.AppId -eq $appId -and $_.ScopeIdentityObjectId -eq $group.Id }

if ($existingPolicy) {
    Write-Warn "Application Access Policy already exists — skipping."
} else {
    New-ApplicationAccessPolicy `
        -AppId $appId `
        -PolicyScopeGroupId $group.Id `
        -AccessRight RestrictAccess `
        -Description "Spotlight.ai mailbox restriction"

    Write-Done "Application Access Policy created."
}

# ------------------------------------------------------------
# Summary
# ------------------------------------------------------------

Write-Host ""
Write-Host "=================================================" -ForegroundColor Green
Write-Host " SETUP COMPLETE" -ForegroundColor Green
Write-Host "=================================================" -ForegroundColor Green
Write-Host ""
Write-Host "Next steps:"
Write-Host ""
Write-Host "  1. Add approved users to the security group:"
Write-Host "     Entra -> Entra ID -> Groups -> All Groups -> '$($group.DisplayName)' -> Members"
Write-Host ""
Write-Host "  2. Wait 30-60 minutes for the access policy to propagate."
Write-Host ""
Write-Host "  3. Validate access (run for a group member and a non-member):"
Write-Host "     Test-ApplicationAccessPolicy -Identity user@$TenantDomain -AppId $appId"
Write-Host "     Expected: group member => Allowed, non-member => Denied"
Write-Host ""
Write-Host "  4. Sign into Spotlight.ai using the service account:"
Write-Host "     https://app.spotlight.ai/oauth2/authorization/outlook-email"
Write-Host "     Account: $($serviceAccount.UserPrincipalName)"
if (-not $ExistingUserId -and -not $existingUser) {
    Write-Host "     Password: see $credFile"
}
Write-Host ""
Write-Host "  5. Contact Spotlight.ai Support to complete configuration."
Write-Host ""

Step 2: Run the PowerShell script as an Entra Global Administrator

Run the PowerShell script above.

Steps

  1. Run the PowerShell script you created from the content above as an Entra Global Administrator
  2. Later, you will need the password that was generated for the service account

Step 3: Add users to the security group created by the PowerShell script

Only members of this group will have their email read by Spotlight.ai

Steps

  1. Navigate to Entra -> Entra ID -> Groups -> All groups
  2. Click the name of the security group created by the PowerShell script above
  3. Click Members on the left side
  4. Add users whose mailboxes should be read by Spotlight.ai
  5. Very important: wait at least one hour. Microsoft take a long time to propagate this information.

Step 4: Meet with Spotlight.ai to finish the configuration

In an online meeting, you will register the service account as a Spotlight.ai user while Spotlight.ai staff enable your tenant for Email Intelligence.

Steps

  1. Schedule the Teams Meeting with Spotlight.ai
  2. Once the online meeting is going, proceed with the steps below
  3. Ensure you logout from Microsoft Entra. It is very important that the next step be performed using the new service account
  4. Navigate to https://app.spotlight.ai/oauth2/authorization/outlook-email
  5. Login as the service account you created in Step 2. You should be in a logged-in state in Spotlight.ai.
  6. Spotlight.ai staff will
    1. Verify that the user was bound to the service
    2. Elevate the rights of the provisioned service account user to Customer Administrator
    3. Set the flag for your tenant email.outlook.enabled to true
    4. Monitor logs for the initial test
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us