> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sophos

> Connect your Sophos Central tenant to Oleria to discover its directory users, administrators, roles, groups, and access tokens, and the tenant's audit activity and threat alerts.

Connect Sophos Central to Oleria to see who can administer your Sophos Central tenant, the roles that grant their access, the directory users and groups, the access tokens the tenant has issued, and what is done with that access. Sophos Central administrators can change endpoint, server, email, and firewall protection across your whole estate, so they're among your most privileged identities. Oleria connects with Sophos Central API credentials, and can also remove and restore administrator access, change an administrator's role, change group memberships, create groups, create and delete directory users, and disable access tokens.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your tenant:

* **Directory users** - every user in the Sophos Central directory, with name, email, manager, creation date, and whether the user was created in Sophos Central or synced from a directory such as Active Directory or Microsoft Entra ID. A directory user who is also a Sophos Central administrator shows their administrator role.
* **Administrators** - every Sophos Central administrator, with their role. An administrator who isn't linked to exactly one directory user appears as their own account. Administrators who hold the predefined **Super Admin** or **Admin** role, or a custom role with administrator permissions, are marked as administrators. Sophos requires multi-factor authentication (MFA) for every administrator, so administrators show MFA as required. Sophos doesn't report which MFA method they use.
* **Partner and enterprise administrators** - administrators who act on your tenant from a Sophos partner or Sophos Central Enterprise account, or from Sophos support, appear when they show up in the tenant's audit log in the last 90 days. They're grouped under **Sophos partner / enterprise administrators (synthesized)**, because Sophos doesn't report their roles on your tenant.
* **Last activity and password changes** - Oleria takes each user's and administrator's last activity, and last password change or reset, from the last 90 days of the tenant's audit log (see [Known limitations](#known-limitations)).
* **Groups** - every directory group, with its description, nested groups, and whether it was created in Sophos Central or synced from a directory.
* **Roles** - every tenant role, including the roles for API credentials, with a summary of the permissions each grants. Roles with administrator permissions are marked as administrator roles.
* **Memberships** - each administrator's role, and which users belong to which groups. Sophos gives each administrator exactly one role.
* **Non-human identities (NHIs):**

  | Identity | Shown as |
  | :- | :- |
  | Linux Sensor access tokens | API token, with its label, type, repository URL, creation date, expiry date, and the user who created it |

  Each access token also appears as a credential with the same ID. A token is active until it expires. When Sophos reports who created a token, and that user is discovered, the user is shown as the token's owner. Sophos doesn't let these tokens call its APIs, so they're shown without API access. Access tokens need a Sophos XDR server licence, and Sophos may also require API credentials with the **Service Principal Super Admin** role to list them.
* **Activity** - events from the tenant's audit log, from the last 90 days:

  * sign-ins, failed sign-ins, and sign-outs;
  * password changes and resets;
  * MFA and single sign-on (SSO) configuration changes;
  * API credentials created or deleted;
  * administrator roles assigned or removed, and roles created or updated;
  * users added to or removed from groups;
  * objects created, updated, or deleted, and policy and setting changes.

  Oleria keeps every other audit event too, under its Sophos name. Events are attributed to the user or administrator whose email matches, and linked to the user or administrator they changed. Events whose actor Oleria can't match aren't attributed to an account. Oleria drops the sign-ins of this integration's own API credentials, and marks other changes those credentials make as Oleria activity.
* **Threat alerts** - Sophos Central alerts, as security notifications on the tenant. Oleria reads them when it syncs new activity, from the last 24 hours.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> This integration covers identities, groups, roles, and activity. It doesn't inventory endpoints, servers, devices, policies, or the Sophos protection agents installed on them, so Oleria doesn't populate resource-level Access Graph or Access Inventory data for Sophos Central.

## Prerequisites

* A Sophos Central tenant. Sophos Central Partner and Sophos Central Enterprise accounts aren't supported. Create the API credentials in the tenant itself.
* A Sophos Central administrator with the **Super Admin** role, to create the API credentials.
* Admin access on the Oleria platform to add a new integration.

Each integration connects one tenant. If you have more than one tenant, add an integration for each. See [Multi-instance support](/integrations/overview.md#multi-instance-support).

> [!WARNING]
>
> To use [remediation actions](#remediation-actions), the API credentials need the **Service Principal Super Admin** role, which can change anything in the tenant. **Service Principal Read-Only** is enough for discovery, except that Sophos may refuse it the access tokens, and every action then fails when Sophos refuses it. Oleria uses the same API credentials for discovery and actions, and Sophos doesn't report which role API credentials hold. Store the client secret securely.

## Create API credentials in Sophos Central

**1. Open API credentials**

Sign in to Sophos Central Admin as a Super Admin and go to **Global Settings** > **API Credentials Management**.

**2. Add a credential**

Select **Add Credential**, and give it a name and description that identify it as Oleria's.

**3. Choose a role**

Choose one of these roles:

* **Service Principal Read-Only**, for discovery only;
* **Service Principal Super Admin**, to also use remediation actions.

**4. Copy the client ID and client secret**

Copy the **Client ID**, then select **Show Client Secret** and copy it. Sophos shows the client secret only once. You enter both in Oleria later.

> [!NOTE]
>
> Sophos Central API credentials expire, and Sophos removes them automatically when they do. Before they expire, renew them in Sophos Central, or create new ones and [edit the integration](#edit-the-integration). Once they're expired or deleted, Oleria's connection check fails until you enter new credentials. Sophos limits each credential to 100 requests per minute across everything that uses it, so give Oleria its own credentials.

## Connect Sophos Central to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations** -> select **Sophos**.

**2. Complete the connection form**

Provide the following:

| Field | Notes |
| :- | :- |
| Client ID | Required. The client ID of the API credentials you created. |
| Client Secret | Required. The client secret shown when you created the API credentials. |

**3. Confirm the connection**

Select **Authenticate**. Before it saves anything, Oleria:

* requests a token for the API credentials from Sophos;
* asks Sophos which tenant the credentials belong to, and its data region. You don't enter them;
* reads the tenant's directory users, administrators and roles, to confirm the credentials can read what Oleria syncs, and to find the tenant's name.

Find the newly connected tenant on the **Connected** tab of your Oleria **Integrations** page.

If **Authenticate** fails, the message says what's wrong:

* **Sophos rejected the API credentials** - check the client ID and client secret. API credentials expire and Sophos removes them, so check that they still exist in **Global Settings** > **API Credentials Management**.
* **partner and Sophos Central Enterprise credentials are not supported yet** - create the API credentials in the tenant's own Sophos Central Admin, in **Global Settings** > **API Credentials Management**.
* **the API credential's role cannot read the directory** - give the API credentials the **Service Principal Read-Only** or **Service Principal Super Admin** role. Sophos also returns this when a licence is missing.
* **the Sophos API did not answer as documented for this tenant's data region** or **sophos whoami returned an unexpected data region host** - Sophos returned a data region Oleria doesn't recognize. Try again in a few minutes, and contact us if it persists.
* **reading Sophos Central** - Sophos didn't respond or was busy. Try again in a few minutes.

## Edit the integration

When you edit the integration, you can change **Client ID** and **Client Secret**, for example after you renew or replace the API credentials.

* Leave **Client Secret** blank to keep the stored secret. If you change **Client ID**, enter that credential's secret too, because each credential has its own secret.

Select **Update** to save. Oleria runs the same checks as **Authenticate**. If the new credentials belong to a different tenant, Oleria refuses them, and the message says **these API credentials belong to a different Sophos Central tenant than the connection**. To connect a different tenant, add a new integration. Oleria checks the tenant again on every sync.

## Verify the integration

Confirm the tenant appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, review the discovered users, administrators, groups, roles, access tokens, and activity in your Oleria workspace.

In the integration's **Capabilities and operation readiness** section, **Read users**, **Read groups**, and **Read roles** show **Available**. Sophos doesn't tell a missing permission apart from a missing licence, so these rows don't change to **Needs permission**. If Oleria can't read one of them, it keeps the last result it saved.

If the sync is marked as partially completed, Oleria couldn't read all of the audit log. Either Sophos refused it, reading it failed partway through, or the tenant's audit log was too large to read in one sync. Oleria reads the audit log newest first, so in that last case only the oldest events are missed. Some activity, last activity dates, or partner and enterprise administrators may be missing. If access tokens or alerts are missing, Sophos refused them: Oleria skips them and the sync still completes. See [Known limitations](#known-limitations).

## Remediation actions

Oleria can take these actions in Sophos Central. They need the API credentials to have the **Service Principal Super Admin** role (see the warning in [Prerequisites](#prerequisites)).

| Action | What it does | Revert |
| :- | :- | :- |
| Disable user accounts | Removes the user's Sophos Central administrator access. Sophos has no way to disable a user, so this is how Oleria removes their access. The directory user stays. Oleria refuses a user who isn't an administrator, because they have no console access to remove. | Supported - gives the user administrator access again, with the same role. Not supported for an administrator shown as their own account, because Sophos creates administrators only from a single directory user: the revert makes no change and says so, so re-add the administrator in Sophos Central. |
| Add user to role | Changes an administrator's role to the role you choose, or makes a directory user an administrator with that role. | Supported - restores the previous role, or removes the administrator access the action gave. |
| Remove user from role | Removes the administrator's access, if the administrator holds that role. Sophos gives each administrator exactly one role, so removing it removes their administrator access. | Supported - gives the user administrator access again, with that role. Not supported for an administrator shown as their own account, for the same reason as **Disable user accounts**. |
| Add user to group | Adds a directory user to a group created in Sophos Central. | Supported - removes the user from the group. |
| Remove user from group | Removes a directory user from a group created in Sophos Central. | Supported - adds the user back to the group. |
| Disable NHI accounts | For a Linux Sensor access token, moves the token's expiry to now. If Sophos refuses that expiry, Oleria revokes the token instead, and the action's result says so. If Sophos refuses the change for any other reason, the action fails and revokes nothing. Not supported for API credentials. | Supported - restores the token's original expiry, which Sophos may cut short at your server licence's expiry. Not supported after Oleria revoked the token, or when Sophos reported no expiry for it. If the original expiry has already passed, the revert makes no change. |
| Delete user | Deletes a directory user created in Sophos Central, after removing their administrator access if they have it. If Sophos then refuses to delete the user, Oleria gives the administrator access back, with the same role, and the action fails. If that also fails, the message names the role to give back in Sophos Central. The action's result records the user's email. | Not supported. Deleting a user can't be undone in Sophos Central. |
| Create group | Creates a group in Sophos Central. If a group with the same name already exists, ignoring upper and lower case, the action fails and changes nothing. | Supported - deletes the group, but only while it keeps its name and has no members. |
| Create user | Creates a directory user in Sophos Central with the name and email you provide. It can also add the user to groups created in Sophos Central, by group ID. | Supported - deletes the user the action created. |

> [!NOTE]
>
> The **Remediations** page offers **Revert** only for **Disable user accounts**, **Remove user from group**, and **Disable NHI accounts**. The integration supports the other reverts in this table, but the Remediations page doesn't offer them yet. Oleria can revert only an action that completed or partially completed, never one that failed.

> [!WARNING]
>
> **Delete user** can't be undone. A user created again gets a new ID. To remove a user's console access but keep the user, use **Disable user accounts** instead.
>
> If Sophos refuses to move an access token's expiry, **Disable NHI accounts** revokes the token, which can't be undone. Anything that uses the token stops working until you issue a new one.

Keep these limits in mind when you use these actions:

* Oleria reads the user, administrator, group, or token before it makes a change. If it's already in the state the action asks for, Oleria makes no change, and reverting the action makes no change either.
* After Sophos accepts a change, Oleria reads the target again to check it, and retries a few seconds apart if Sophos hasn't caught up yet. If no read shows the change, or the reads fail, the action still succeeds and can still be reverted, but it's marked unverified: check the target in Sophos Central.
* If Sophos doesn't answer a change to an existing administrator, group membership, or access token, or answers with a server error, Oleria reads the target again. If the change is there, the action succeeds but is marked unconfirmed, because Oleria can't tell that the change was its own. Oleria won't revert an unconfirmed action, so check the target in Sophos Central and correct it there.
* Reverting an action changes only what the action changed. If the user, role, group, or token is already back to how it was, has changed since, or no longer exists, the revert makes no change and says why. A user who gets administrator access again gets a new administrator ID.
* Oleria refuses any change that would leave the tenant with no administrator holding the **Super Admin** role. If Oleria can't find the **Super Admin** role in the tenant's roles, it refuses to remove or change the access of any administrator who holds an administrator role. Sophos also refuses to remove the last Super Admin.
* **Add user to role** and **Remove user from role** accept only roles for administrators. Roles for API credentials can be held only by API credentials.
* Oleria can't change API credentials, including the API credentials this integration connects as, or partner and enterprise administrators. Change them in Sophos Central or in the partner or enterprise account.
* **Add user to group**, **Remove user from group**, **Create user**, and **Delete user** work only with groups created in Sophos Central, and **Add user to group**, **Create user**, and **Delete user** only with users created there. Oleria refuses groups and users synced from a directory, and the message names the directory: change them there. **Remove user from group** can remove a synced user from a group created in Sophos Central, but that removal can't be reverted, because Sophos doesn't let Oleria add synced users to a group.
* If a directory user is linked to more than one administrator, Oleria refuses to change their administrator access: change it in Sophos Central. If one administrator is linked to several directory users, Oleria shows that administrator as its own account and refuses changes made through one of the users. The message names the administrator account to use instead.
* **Create user** creates a directory user only. Sophos directory users have no password and no console access, and the action's result notes this. To give the user console access, run **Add user to role**. If a directory user with the same email already exists, ignoring upper and lower case, the action fails and changes nothing.
* If Sophos doesn't answer **Create user**, **Create group**, or **Add user to role** for someone who isn't an administrator yet, Oleria doesn't send it again. It checks for the new user, group, or administrator instead. If it now exists, the action fails and can't be reverted, because Oleria can't tell it made the change. Check it in Sophos Central, and remove it there if needed.
* If an administrator held no role before **Add user to role** or **Disable user accounts**, the action can't be reverted, because there's no role to give back.
* Reverting **Create user** deletes only the user the action created. Oleria refuses if that user now has a different email, or has since been made an administrator.

## Known limitations

* **Tenants only.** Oleria connects with API credentials created in a Sophos Central tenant. Sophos Central Partner and Sophos Central Enterprise credentials aren't supported.
* **No API credentials.** Sophos has no API that lists API credentials, so Oleria doesn't discover them, and can't disable them. Their roles still appear. To remove API credentials, delete them in **Global Settings** > **API Credentials Management**. Audit events made with other API credentials aren't attributed to an account.
* **No user status.** Sophos doesn't report whether a user or administrator is disabled, so every listed user and administrator shows as enabled.
* **No sign-in policy.** Sophos configures SSO only in Sophos Central Admin and doesn't report it, so SSO shows as unavailable. MFA shows as required for administrators and unavailable for other directory users.
* **90 days of history.** Sophos keeps 90 days of audit log, so activity, last activity, and last password changes don't go back further. A user with no audit events in that time shows no last activity. Sophos documents only the sign-in event, so Oleria classifies the other audit events by their description. Events it can't classify keep their Sophos name.
* **24 hours of alerts.** Sophos keeps alerts for 24 hours, so alerts from before you connected don't appear, and if new activity isn't synced for more than 24 hours, the oldest alerts are missed.
* **Licence-dependent data.** Access tokens need a Sophos XDR server licence. If Sophos refuses the access tokens, the audit log, or the alerts, Oleria skips them and keeps syncing everything else. A refused audit log marks the sync as partially completed.
* **Custom administrator roles.** A custom role is marked as an administrator role only when Sophos reports administrator permissions for it. If Oleria can't read the tenant's permission sets, only the predefined **Super Admin** and **Admin** roles are.
* **No endpoint agents or AI agents.** Sophos protection agents are security software on your devices, not identities, so they don't appear. Sophos Central has no AI agents.
* **Rate limits.** Sophos limits each API credential to 100 requests per minute. Oleria paces its requests to share that limit, so the first sync of a large tenant can take a while.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.