Microsoft 365
Connect a client's Microsoft 365 with an app registration, so the agent can look into users, sign-ins, licences, groups, mailboxes and devices.
Connect a client's Microsoft 365 so the agent can see what really happened to a user: whether their account is blocked, their recent sign-ins and why they failed, their licences, groups, mailbox settings and devices.
You connect it with an app registration that you make in the client's Microsoft Entra admin centre. What the agent can read depends on the permissions you give that app. The agent checks its permissions before it looks at anything.
The agent only reads. If the fix is a change in Microsoft 365, such as unblocking a sign-in, it proposes it, and nothing happens until a person approves it. See Changes below.
Make the app registration#
- 1
In the Microsoft Entra admin centre (entra.microsoft.com), signed in as an admin of the client's organisation, go to Identity › Applications › App registrations and click New registration.
- 2
Give it a name, such as Cerberius Agents. Under Supported account types, choose Accounts in this organizational directory only. Leave Redirect URI empty. Click Register.
- 3
On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID.
- 4
Go to Certificates & secrets › Client secrets and click New client secret. Copy its Value straight away: Microsoft shows it only once. Note when it expires.
- 5
Go to API permissions › Add a permission › Microsoft Graph › Application permissions, and add the permissions you want. See Which permissions below.
- 6
Click Grant admin consent for your organisation, and confirm. The permissions only work after this.
- 7
Here, go to Settings › Microsoft 365 and Google. Click Connect an account (or Connect another, if Google Workspace is already there), and choose Microsoft 365.
- 8
Under App registration, fill in the two IDs and the client secret. Click Save, then Check connection.
Which permissions#
Use Application permissions, not delegated ones: the agent works as the app, not as a person. Application permissions apply to the whole organisation.
To read:
| Permission | What the agent can then see |
|---|---|
User.Read.All | Users: whether the account is enabled, its details and manager. |
Group.Read.All | Groups and their members. |
AuditLog.Read.All | Sign-in logs (why a sign-in failed) and audit logs. Sign-in logs need Microsoft Entra ID P1 or P2. |
UserAuthenticationMethod.Read.All | Users' sign-in methods, such as MFA phones and apps. |
MailboxSettings.Read | Mailbox settings, such as automatic replies. |
Directory.Read.All | The rest of the directory, such as licences and devices. |
DeviceManagementManagedDevices.Read.All | Devices managed by Intune. |
Reports.Read.All | Usage reports. |
To let the agent propose changes, add the matching write permissions, for example:
| Permission | Changes it allows |
|---|---|
User.EnableDisableAccount.All | Block or unblock a user's sign-in. |
User.ReadWrite.All | Create a user, change a user's details. |
GroupMember.ReadWrite.All | Add someone to a group, or remove them. |
LicenseAssignment.ReadWrite.All | Assign or remove licences. |
UserAuthenticationMethod.ReadWrite.All | Remove a lost phone from a user's sign-in methods. |
MailboxSettings.ReadWrite | Change mailbox settings. |
Your choice: any Microsoft Graph application permission works, and the agent can use what you grant. Set it up step by step, in the App registration row, lists the common ones. Give only what your team is happy for the agent to read and propose.
The settings#
| Setting | What it is |
|---|---|
| Directory (tenant) ID | On the app's Overview page. You can also type the organisation's domain, such as contoso.onmicrosoft.com. |
| Application (client) ID | Also on the app's Overview page. |
| Client secret | The secret's Value. Once saved, it is never shown again, here or through our API. Type a new one to replace it, for example when it expires. |
| Save | Saves the IDs, and the secret if you typed one. |
| Check connection | Shows once everything is saved. It signs in as the app and lists the organisation's name and the app's permissions. If Microsoft refuses, it says why, for example an expired secret. |
How the agent uses it#
- At the start of each investigation, Cerberius Agents signs in as the app and gives the agent a pass that lasts about an hour. The agent never sees the client secret.
- The agent can only read. It can't send anything that changes Microsoft 365.
- What it reads, such as a sign-in that failed, can appear in its findings as evidence. Secrets and tokens are removed first.
Changes#
To let the agent propose Microsoft 365 changes, switch on Microsoft 365 changes under Settings › Approved changes. See Allowing changes.
The agent then puts the exact requests in a change for an approver. When it's approved:
- Cerberius Agents reads everything the change edits or removes. If one can't be read, for example because of a wrong user, nothing runs.
- It sends the requests in order, and stops at the first one Microsoft refuses. The ticket says what was done.
- The agent checks the result and drafts the reply to the requester.
Some changes are never made, even if the app's permissions allow them: changes to apps and their permissions, admin roles, conditional access and other policies, and the organisation itself. Domains can change, such as adding or verifying a domain, if the app's permissions allow it.
New accounts: the agent never writes a password. Cerberius Agents gives the new account a long random first password, which must be changed at the first sign-in, and nobody sees it. Reset it in the Microsoft 365 admin centre to give the person their first password.
With your own runner#
When the agent runs on your own runner, the client secret is kept by you, like your other keys. The directory and client IDs stay in these settings.
- Choose how the secret is kept: Scrambled for your runner (type it here, with the two IDs;
your browser scrambles it so only your runner can unscramble it) or In your store (named
microsoft365-secret; Settings › Agent › Where your keys are kept shows its exact name). Then click Save. See Two ways to keep your keys. - Your runner signs in as the app for each investigation, and gives the agent the same hour-long pass. The agent still never sees the secret.
- Check connection is made by your runner.
- Approved changes are made by your runner, with the same checks as above. It makes nothing until
its own rules allow it: add a
microsoft365section to them (see Microsoft 365, Google and domains). - Your runner sends the secret only to Microsoft's sign-in page, and the pass only to Microsoft Graph, whatever it is asked.
- It needs version 0.8.0 or later. An older runner tells the agent to update it.