Connectors

The saved links that pull data from your other systems into Aegis and push Aegis notifications out to the tools your team already watches.

A connector is a stored configuration that joins Aegis to an external system — a mail server, a chat workspace, a cloud-security platform, an issue tracker, a directory. Once saved and tested, Aegis pulls that system's data in on a schedule, files it against your risks and incidents, and posts alerts into the channel your team already reads.

Who uses it

Every page under /connectors runs a role check on the server before it renders anything — the catalogue, each connector's page and the sync settings alike. Admin and Manager can configure, test, sync, schedule and delete any connector. Contributor and Viewer are redirected to the /unauthorized page, so there is no read-only view for lower roles — not even a list of which systems are connected. If you hold Manager and the sidebar entry is missing, the connectors module is not switched on for your organisation. Six tiles also depend on your licence tier: they still appear, marked Premium, but are dimmed and cannot be opened.

What's on this screen

With a sufficient role, /connectors opens with the title Connectors over the line “Configure integrations with external services for notifications and webhooks.”, and one button on the right: Sync Settings. Below sits the catalogue — twenty connector tiles, three to a row on a wide display, one on a phone. There is no filter bar and no search box, so you scan the grid.

Every tile carries the same four things: an icon top-left; a coloured dot and a status word top-right; the connector name in bold — SMTP, Microsoft Teams, AWS Security Hub, Slack, Jira and Active Directory / LDAP among them — over a one-line description and the prompt Configure →. The whole tile is the link. A tile your licence does not cover is dimmed, shows an amber Premium tag in place of the status dot, and reads Upgrade to unlock →.

Under the grid, a Security Note box states that credentials are encrypted at rest, are reachable only by Manager and Admin roles, and are never shown again after saving. If the live connection state cannot be loaded, an amber banner opens above the grid and the full catalogue still renders beneath it. The dot and word on each tile tell you where that connector stands:

The connector lifecycle

Each connector asks for different credentials, but they move through the same four stages.

1. Open a tile, fill in the credentials, and save. The values are stored encrypted; the page then confirms a configuration exists, but never shows a saved secret again.
2. Select Test Connection. Aegis calls the service live: a pass turns the tile Connected, a failure shows the error the service returned. Connectors that use OAuth (an authorisation handshake where you grant access in the other system rather than typing a password into Aegis) are proved by completing that authorisation instead. There is no separate activate step.
3. Connectors that pull data then run on the schedules set under Sync Settings, or on demand from there. Push-based connectors such as Slack and Teams have nothing to pull; they fire when an Aegis event occurs.
4. Watch the status dot. A tile that moves to Error means the most recent run failed — open its page for the detail, the audit log for the history.

Set up outbound email (SMTP)

SMTP (Simple Mail Transfer Protocol — the standard for sending email) tells Aegis which mail server to send every notification through, so most organisations configure it first. Select the SMTP tile. Under the breadcrumb Connectors / SMTP and the heading SMTP Configuration sits a Status: line, if a configuration exists, and a form in three boxes.

1. In Server Settings, enter the SMTP Host and Port. Both are required; leaving either blank stops the save with “SMTP host is required” or “SMTP port is required”. The form opens on Encryption: STARTTLS with port 587 pre-filled, which suits most providers; None and SSL/TLS are the other choices.
2. In Authentication, enter the Username and Password of the mailbox Aegis sends as. On an existing configuration the password field shows dots and the hint “Leave blank to keep existing password”, so you can change the host without retyping the secret.
3. In Sender Settings, enter the From Address recipients will see — required — and, optionally, a From Name such as Aegis GRC.
4. Select Save Configuration. The button changes to Saving..., then a green line confirms “Configuration saved successfully.” and the Status: line updates. A rejected save shows “Failed to save configuration” with the reason.
5. Select Test Connection — it only appears once a configuration is saved. The result follows: Connection successful in green, or Connection failed in red with the message the mail server returned. A pass moves the tile to Connected.

To rotate the mailbox password later, type the new value into Password and save again. Delete Configuration, bottom left once a configuration exists, removes the whole thing — it asks “Are you sure you want to delete this connector configuration?” first, then returns you to the catalogue.

Set up chat notifications (Slack)

The Slack connector posts Aegis notifications — critical incident alerts, new high-severity risks, policy approval requests and compliance status updates — into a channel you choose, and answers /aegis status, /aegis risks, /aegis incidents and /aegis help from inside Slack. It uses an OAuth install rather than a saved password, so there is an extra authorisation step. The page stacks a Configuration box, a Connection Status panel and — once connected — a Test Notifications box over three reference sections. Work through Setup Instructions in Slack first: it gives the redirect, slash-command and events URLs for your own Aegis address.

1. In Configuration, paste the Client ID, Client Secret and Signing Secret from your Slack app, and set a Default Channel such as #security-alerts. The boxes above the fields — Required Slack App Scopes and Slash Command Setup — list what the Slack app needs. Select Save Configuration; the Connection Status panel then reads Authorization Required.
2. Select Authorize with Slack. Your browser leaves Aegis for Slack's install flow, where you pick the workspace and grant the scopes. On your return the panel reads Connected to Slack and offers Test Connection and Re-authorize.
3. Select Test Connection. A pass fills the panel in with the Team, the Bot account, the Default Channel and whether a Webhook is Configured. Those details are read back from Slack by the test itself, so the panel stays bare until you run one.
4. A Test Notifications box sits below the panel while the connection is good. Select Send Test Message; a browser alert reports either “Test message sent successfully!” or the error Slack returned. Check the channel to confirm it arrived.

Connect Microsoft 365 (SharePoint and Microsoft Defender XDR)

Two connectors sign in to Microsoft with OAuth: SharePoint Connector syncs documents from SharePoint and OneDrive into the Evidence Locker, and Microsoft Defender XDR Connector brings Defender incidents into the security signal inbox for review (see Incidents). Both use an app registration in your own Microsoft Entra ID tenant, so part of the setup happens in the Azure portal. Each page opens with Setup Instructions that show the exact redirect URI for your Aegis address.

1. In the Azure portal, create an app registration (or reuse one for both connectors) and add a client secret. Copy the secret straight away — Microsoft shows it only once.
2. Under API permissions, add the delegated Microsoft Graph permissions and grant admin consent. SharePoint needs Files.Read.All and Sites.Read.All; Microsoft Defender XDR needs SecurityAlert.Read.All, SecurityIncident.Read.All and User.Read. A connection authorised before SecurityIncident.Read.All was added keeps syncing single alerts, and its sync result asks you to select Re-authorize so Defender's grouped incidents come through instead.
3. Under Authentication, add a platform of type Web — not Single-page application or Mobile and desktop — and register the redirect URI from the connector's Setup Instructions. It must match character for character, scheme and path included, with no trailing slash: https://<your-domain>/api/connectors/sharepoint/callback for SharePoint and https://<your-domain>/api/connectors/azure/callback for Microsoft Defender XDR. One app registration serving both connectors needs both URIs.
4. Back in Aegis, enter the Client ID, Client Secret and Tenant ID and select Save Configuration.
5. Select Authorize with Microsoft, sign in and accept the consent screen. On your return the panel reads Connected to SharePoint or Connected to Azure Security API; select Test Connection to confirm.

If Microsoft stops you with “You can't sign in” instead, the code on that screen tells you what to fix:

• AADSTS50011 (the redirect URI does not match) or AADSTS900971 (no reply address provided) — the redirect URI is not registered on the app, is registered under the wrong platform, or differs by a character. Fix it under Authentication as in step 3; the change takes effect within a few minutes.
• AADSTS650053 (a scope does not exist) — the app asked for a permission Microsoft Graph does not have. Check the permission list in step 2.
• AADSTS65001 or a request for admin approval — consent has not been granted. Ask a Global or Privileged Role Administrator to select Grant admin consent under API permissions.
• Sign-in works but the wrong directory appears — the Tenant ID or Client ID in Aegis points at a different app registration than the one you edited. Compare it with the Application (client) ID on the app's overview.

Choose what SharePoint imports

Once SharePoint is connected, the page shows Evidence sources: “Only these folders are imported into the Evidence Locker, by Sync Now, schedules and the API.” Until you add one, the panel reads No evidence source yet. Nothing is imported until you add a folder., and Sync Now stays disabled with a note that it imports configured evidence sources only.

1. Select Add source. Pick a Site, then a Library, then browse to the Folder (Up one level goes back). Tick Include subfolders to take the whole tree.
2. Select Preview files. Aegis lists the files with their count and total size, and marks any the Evidence Locker would refuse as not accepted by the Evidence Locker.
3. Optionally fill in Name (optional), then select Save source. A personal OneDrive (My OneDrive (personal)) is saved only after you tick the confirmation that its files may be imported as evidence.
4. Each saved source has its own Sync, Enable or Disable, and Remove buttons. Sync Now imports every enabled source.

Imported files land in the locker as drafts that still need a person's approval (see Evidence). They are recorded as uploaded by the SharePoint connector, so the admin who connected or synced the connector may approve them.

Sync an Entra ID connection

The Microsoft Entra ID connector takes read-only snapshots of your directory, which Aegis evaluates about every 30 minutes. Each connection row has a Sync now button for people who may configure connectors, so you can test a connection without waiting. The button reads Syncing… while the run lasts, and repeated clicks do not queue extra runs. When it ends, the row shows the new status, last sync time, any error and the evidence it recorded; a longer run says The sync is still running. Reload the page later to see the result.

Under Segregation of duties, two lists — Developer group patterns and Production access group patterns — define a conflict: a user in a group matching each list is counted as an SoD violation from the next sync. Each list takes 1 to 20 patterns of at most 64 characters, one per line; tabs separate patterns like new lines, so a row pasted from a spreadsheet works. Save patterns checks the lists first and names the list and line that break a rule, and a refusal from the server says why (for example a missing permission or an expired session) instead of a generic error.

Schedule the syncs

A connector that pulls data needs a schedule, or it only ever runs when you trigger it by hand. Sync Settings in the catalogue header opens /connectors/sync, which has two tabs, Schedules and Webhooks. No figure in this chapter shows it.

1. Select Sync Settings. The page opens on the Schedules tab, headed Sync Schedules. With nothing set up you get the empty state No sync schedules and a Create Schedule button in the panel.
2. Select Add Schedule. A Create Schedule form asks for the Connector, a Cron Expression — the hint reads “Format: minute hour day-of-month month day-of-week”, and anything other than five parts is refused — an optional Sync Type, Max Retries, Retry Delay (seconds) and a tick box for Enable schedule immediately.
3. Select Create Schedule. The row joins the table under Connector, Schedule, Status, Last Run, Next Run and Actions, with a status of Pending, Running, Success, Failed or Disabled.
4. Use the icon buttons under Actions: Sync now, Enable schedule or Disable schedule, Edit schedule and Delete Schedule. Deleting asks “Are you sure you want to delete this sync schedule? This action cannot be undone.” first.

For SharePoint, Sync Type (Optional) is either Evidence (selected folders) — tick one or more of the Evidence sources set up on the connector page — or Questionnaires. An evidence schedule without a source is refused with Select at least one evidence source, and a source removed later is dropped from the schedule when you edit it. A schedule created before this choice existed (the old “All Documents” or “Policies Only” types) now fails and asks you to edit it, choose Evidence and select the source folders.

The Webhooks tab is reference material rather than a form. Webhook Endpoints lists the inbound addresses Aegis exposes so an external service can push an event in and trigger a sync at once — GitHub, Azure Event Grid, SharePoint, CrowdStrike and a Generic endpoint — each with its URL, expected format, headers and a Copy URL button. A Webhook Security note adds the condition: signature verification applies only once you set a webhook secret in that connector's settings.

Tips and limits

• Each connector type holds one configuration for the organisation. The exceptions are Active Directory / LDAP and Leen, which keep a list of connections under one tile; for a second destination elsewhere, add the generic webhook connector as an extra route.
• Credentials are never returned to the page or to the API once saved. If you suspect one has been exposed, delete the configuration and set it up again — that clears every stored setting for that connector.
• A connector that ran for weeks and now shows Error has usually lost its credential — a rotated password, a revoked or expired token. Open its page, enter the new value, save and test again; an OAuth connector needs Re-authorize instead.
• A healthy connector is not on its own enough for someone to receive a notification. Messages are sent per recipient, and only when that person has the channel switched on in their own notification preferences; quiet hours and a digest setting hold a message back.
• Connector saves, tests and sync runs are written to the audit log.

Where this connects

Connectors feed signals to Anomalies, findings to Risks and Incidents, documents to Evidence, training results to Security awareness and directory data to HR, alongside Entra ID single sign-on. Inbound endpoints are covered in Webhooks, outbound actions in Workflows, notification preferences in Settings and the role limits above in What each role can do.