Secure60 Microsoft 365 Connector

Overview

The Secure60 Microsoft 365 Connector is a lightweight container that collects Microsoft 365 and Microsoft Entra ID (Azure AD) audit and identity telemetry and sends it to Secure60 — either to your Secure60 Collector or directly to the Secure60 ingest endpoint. You deploy it in your own environment, and your Microsoft credentials stay with you: they live in a local .env file and are never stored by Secure60.

It collects from two Microsoft sources so you get both breadth and identity depth:

Key Capabilities

• Two-API collection — the Management Activity API for the broad workload audit feed, plus Microsoft Graph for richer Entra sign-in and identity-risk data.
• App-only authentication — a single-tenant Microsoft app registration using a client secret (or certificate). No user accounts, no interactive login at runtime.
• Common Information Model output — events are normalized into the Secure60 Common Information Model (CIM) before they leave the connector, so Rules and Entity Analysis work out of the box.
• Detection-friendly fields — nested Microsoft structures are flattened into discrete, queryable fields (for example a sign-in’s user agent or an app registration’s changed properties), so you can write precise rules without parsing JSON.
• Reliable, resumable collection — durable checkpoints per source, automatic de-duplication, and back-off on throttling. Restarts resume without gaps.
• Self-contained — ships as a Docker image with a five-line configuration file.

How It Works

• The connector authenticates to Microsoft using your app registration and requests data on a schedule (every five minutes by default).
• It reads the Management Activity API content feed and the relevant Microsoft Graph logs, normalizes each record into the Secure60 CIM, and forwards the events in batches to your chosen destination.
• It keeps a checkpoint for each source so that, after a restart, collection resumes from where it left off — and de-duplicates so repeated records are dropped.
• Where your tenant licence doesn’t include a feed (for example sign-in logs on a Free tenant), that feed is detected and skipped automatically; the rest keep flowing.

Prerequisites

1. A Microsoft 365 / Entra tenant with Unified Audit Logging enabled (Microsoft Purview → Audit → Start recording user and admin activity). This is required for the Management Activity API.
2. A Microsoft app registration (created in the next step) with application permissions and admin consent.
3. A Docker host in your environment to run the connector.
4. A Secure60 destination — either your Secure60 Collector URL, or a Secure60 project ID and ingest token (from the Secure60 portal).

Quick Start

Step 1: Register the Microsoft app

A PowerShell script registers a single-tenant application, assigns the least-privilege permissions, grants admin consent, and creates a client secret — run it once as a Microsoft Global Administrator on a Windows machine with PowerShell.

Download the script:

Invoke-WebRequest -Uri https://www.secure60.io/docs/setup-s60-m365-connector-1.2.ps1 -OutFile setup-s60-m365-connector-1.2.ps1

Or download it from the direct link.

Run it (from the folder you downloaded it to):

Install-Module Microsoft.Graph -Scope CurrentUser   # if not already installed
Unblock-File .\setup-s60-m365-connector-1.2.ps1     # clears the "downloaded file" warning
.\setup-s60-m365-connector-1.2.ps1 -TenantId your-tenant.onmicrosoft.com -WriteEnv

Pass your tenant with -TenantId (your onmicrosoft.com domain or the tenant GUID). This matters if your admin account is a guest in the tenant or also exists as a personal Microsoft account, so sign-in targets the right organization.

Where to find your Tenant ID: in the Microsoft Entra admin center go to Identity → Overview — the Tenant ID (a GUID) and your primary *.onmicrosoft.com domain are both shown there. Either value works for -TenantId.

If you get an execution-policy error, allow scripts for this session only: Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned.

The default sign-in opens your browser. On a server with no browser you can add -UseDeviceCode to sign in from another device — but note that many tenants disable the device-code flow via Conditional Access, so where possible run the script on a machine with a browser.

The script prints — and, with -WriteEnv, saves to .env — three values: TENANT_ID, CLIENT_ID, and CLIENT_SECRET.

After setup, you can revoke the setup tool’s access. Registering the app uses Microsoft’s Microsoft Graph Command Line Tools application — this is only needed for the one-time registration, and you may get a Microsoft sign-in/consent notification for it. The connector runs on its own app registration (the CLIENT_ID/secret above), so once setup is complete you can remove that tool’s access with no impact on the connector: Microsoft Entra admin center → Enterprise applications → “Microsoft Graph Command Line Tools” → remove (or, for a personal account, at account.microsoft.com under Privacy/Apps).

Prefer not to run the script? Follow the Manual Entra Setup guide to register the app and grant consent in the Entra admin center (or with the Azure CLI) instead — it produces exactly the same TENANT_ID / CLIENT_ID / CLIENT_SECRET.

Step 2: Configure the connector

Create a .env file next to the connector with your Microsoft credentials and one Secure60 destination:

# Microsoft app-only credentials (from Step 1)
TENANT_ID=00000000-0000-0000-0000-000000000000
CLIENT_ID=00000000-0000-0000-0000-000000000000
CLIENT_SECRET=your-client-secret

# Secure60 destination — choose ONE:
#   Send to the Secure60 ingest endpoint:
PROJECT_ID=301
TOKEN=your-secure60-ingest-token
#   …or send to your Secure60 Collector instead:
# S60_COLLECTOR_BASE=https://your-collector.internal

This is a complete configuration; every other setting has a sensible default.

Step 3: Run the connector

Save this compose.yaml next to your .env (copy-paste as-is):

services:
  s60-m365-connector:
    image: "secure60/s60-m365-connector:latest"
    container_name: "s60-m365-connector"
    pull_policy: always
    env_file:
      - .env
    volumes:
      - s60-m365-state:/state
    restart: always

volumes:
  s60-m365-state:

Then start it:

docker compose up -d
docker compose logs -f

You should see authentication succeed and lines like Forwarded 17 events -> ingest (HTTP 200). Events appear in your Secure60 project within a few minutes.

Prefer no compose file? Run the image directly:

docker run -d --name s60-m365-connector --restart always \
  --env-file .env -v s60-m365-state:/state \
  secure60/s60-m365-connector:latest

Configuration Reference

A working configuration is just the Microsoft credentials plus one destination. Everything below is optional and shown with its default.

The destination mode is inferred automatically: set PROJECT_ID + TOKEN for ingest, or S60_COLLECTOR_BASE for your collector.

Data Format

Events are sent as flat JSON aligned with the Secure60 CIM. Every event carries vendor, product, app_name=ms365, technology_group=windows, plus normalized fields and the original Microsoft fields (prefixed event_). The type field reflects the entity an event targets — email (Exchange), file (SharePoint / OneDrive) or user (Entra sign-ins and directory changes).

Common fields:

• operation — the normalized activity, e.g. user-login, active-directory-modify, azure-app-create, email-service-modify, user-permission-modify.
• outcome — success or failure.
• user_name — the acting user (UPN).
• ip_src_address — the source IP address (geo-enriched on arrival).
• timestamp — the time the activity occurred at the source.
• event_* — the full Microsoft record, flattened. Nested key/value details become discrete fields you can match on directly, for example event_additionaldetails_user_agent or event_targetresources_0_displayname.

Because the data is normalized to CIM, you can correlate Microsoft 365 activity with other sources and write Rules against these fields immediately.

Best Practices

1. Enable Unified Audit Logging first. The Management Activity feed depends on it, and it can take up to 12 hours to begin producing data after you turn it on.
2. Use least-privilege permissions. Grant only the feeds you need; add the Identity Protection permissions only on P2 tenants.
3. Track secret expiry. Microsoft client secrets expire (24 months maximum). Set a reminder to rotate the secret and update .env before it lapses — an expired secret silently stops collection.
4. Run one connector per tenant. Each instance serves a single Microsoft tenant.
5. Pin the image version (for example secure60/s60-m365-connector:1.1) for reproducible deployments, and upgrade deliberately.
6. Watch the heartbeat. The connector emits a periodic health event; alert on its absence to catch a stalled connector quickly.

Support

For help deploying the Secure60 Microsoft 365 Connector, contact the integrations team at integrations@secure60.io.