Documentation

Microsoft Entra ID SSO Integration

Enable Single Sign-On with Microsoft Entra ID (formerly Azure Active Directory) so your users can sign in to Topus with their existing corporate Microsoft account — no separate password required.

What you'll need

1 Register the application in Entra ID

Sign in to the Microsoft Entra admin center as a Global Administrator, then navigate to Identity → Applications → App registrations → New registration and fill in:

2 Capture the Tenant ID and Client ID

From the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID. You will paste both into Topus later.

3 Create a client secret

Open Certificates & secrets → Client secrets → New client secret. Set a description and an expiry (24 months recommended — set a calendar reminder to rotate before then), then copy the secret Value immediately — Microsoft shows it only once.

4 Grant API permissions

Under API permissions, ensure Microsoft Graph → User.Read is listed (added by default). If your tenant requires admin consent, click Grant admin consent. That is all Topus needs — it only reads the signed-in user's basic profile to provision their account. No mailbox, calendar, files or directory access.

5 Enable SSO in Topus

Sign in to Topus as an Administrator and open Administration → Settings → Authentication → SSO (Microsoft Entra ID) → Configure. Enable Microsoft SSO login, paste the Tenant ID, Client ID and secret Value, confirm the redirect URI matches step 1 exactly, and save. The change takes effect immediately — no restart required.

6 Verify it works

In a private browser window, open your Topus login page. You should see a Sign in with Microsoft button. Click it, sign in with a corporate account, and you will land on the Topus dashboard.

First sign-in (Just-In-Time provisioning)

• Email matches an existing Topus account — the account is linked to the Microsoft identity; roles and permissions are preserved.
• No account exists — one is created automatically from the Entra ID email and display name, starting with no roles. An administrator assigns roles before the user can access protected features.
• SSO users skip the OTP step — Microsoft has already authenticated them, including any MFA or Conditional Access policies you enforce.

Troubleshooting

Rotating the client secret

Microsoft requires secrets to expire. Rotate without downtime: create a new secret in Entra ID while the old one is still active, paste the new value into Topus and save, verify sign-in works, then delete the old secret in Entra ID.

Security notes

• The client secret is encrypted at rest inside your Topus database.
• The OAuth state parameter is bound to the user's browser via a short-lived, http-only cookie — protecting against CSRF.
• Sign-in tokens are passed back via the URL fragment so they never appear in server access logs.
• Topus requests only the minimum User.Read permission needed to identify the signed-in user.
• SSO-only mode (disabling local passwords entirely) is available — contact support to plan it safely so your admin team is never locked out.

Email Integration (Microsoft Outlook)

Topus delivers notifications, scheduled digests and report emails through your own Microsoft 365 / Exchange Online tenant using the Microsoft Graph API — no third-party mail provider, no separate mail server to run.

How it works

Topus authenticates to Microsoft Entra ID as an application (client-credentials flow) and sends mail from a mailbox you designate — typically a shared mailbox such as noreply@yourcompany.com. Messages originate from your own tenant, follow your compliance and retention policies, and appear in the sender mailbox's sent items like any corporate mail.

What you'll need

1 Register an application in Entra ID

In the Microsoft Entra admin center, go to Identity → Applications → App registrations → New registration and create an app named Topus — Mail (single tenant). No redirect URI is needed for this integration.

2 Grant the Mail.Send application permission

Open API permissions → Add a permission → Microsoft Graph → Application permissions, select Mail.Send, then click Grant admin consent for your tenant.

3 Create a client secret

Under Certificates & secrets → New client secret, create a secret (24 months recommended) and copy the Value immediately — Microsoft shows it only once. Also note the Application (client) ID and Directory (tenant) ID from the app's Overview page.

4 Configure the integration in Topus

Sign in to Topus as an Administrator and open Administration → Integrations → Microsoft Outlook. Fill in:

5 Send a test email

Use the Send test email action on the integration page. If it arrives, you're done — notifications, scheduled digests and report emails will now flow through your tenant.

What Topus sends

• Operational notices — for example SOC notices when a penetration test engagement is scheduled or ends (administrators can toggle these).
• SLA escalations — notifications to owners as findings approach or breach their SLA thresholds.
• Scheduled digests — recurring email summaries with configurable filters and recipients.
• Report distribution — branded PDF reports delivered to stakeholders on schedule.

Troubleshooting

Security notes

• The client secret is stored encrypted in your Topus database and never shown again after saving.
• Mail flows directly between your Topus server and Microsoft Graph over HTTPS — no intermediary service.
• Scope the Mail.Send permission to the sender mailbox with an Application Access Policy for least privilege.
• Rotate the client secret before it expires, the same way you rotate the SSO secret.