> ## 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.

# Webex

> Connect a Webex organization to Oleria to discover users, groups, administrator roles, Service Apps, OAuth integrations, workspaces, devices, and Control Hub audit activity, and take remediation actions directly from Oleria.

Webex is Cisco's collaboration platform for messaging, meetings, and calling. Connect your Webex organization to Oleria to see who can sign in, which groups they belong to, who holds administrator roles in Control Hub, and which apps and devices act in your organization. Oleria connects with a Webex Service App, a machine account that a Full Admin authorizes in Control Hub, so Oleria's API calls don't run as any person's account. You can then review over-provisioned access and take action directly from Oleria.

One Oleria integration covers one Webex organization.

## What Oleria discovers

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

* **Users** - every person in your Webex organization, with name, email address, department, title, and licenses. Users whose Webex sign-in is turned off are shown as disabled. Users with any Control Hub administrator role are marked as administrators, and their most privileged role is shown as their account role. Oleria also shows whether a user's invitation is still pending, their last activity when Webex reports it, and their last password change when the admin audit log records one. A user is shown with a paid license when any of their licenses belongs to a Webex subscription.
* **Bots** - bots that Webex lists in your organization, shown as system accounts.
* **Groups** - the groups in your organization, with their members.
* **Roles** - the Control Hub administrator roles, such as full administrator and read-only administrator, and the users who hold them.
* **Non-human identities (NHIs)**:
  * **Service Apps** - the Service Apps authorized in your organization in the last year, with the scopes each was granted. This includes the Service App Oleria connects with. A Service App with any admin write scope is marked as an administrator. Each Service App is linked, as its owner, to the administrator in your organization who last authorized it.
  * **OAuth integrations** - the apps your users authorized to act on their behalf, including Webex portals such as developer.webex.com. Each is linked to the users who authorized it, as an app that can act as those users.
  * **Workspaces** - shared spaces such as meeting rooms, with their SIP address.
  * **Devices** - Webex devices, linked to the workspace or user they belong to.
* **Activity** - events from the Control Hub admin audit log, such as:

  * administrator sign-ins to Control Hub, and sign-outs
  * users added to the organization, user changes, and changes to a user's MFA setting
  * administrator role changes
  * group creation and group membership changes
  * tokens revoked by an administrator
  * Service App authorizations and deauthorizations
  * organization setting and display name changes
  * workspace and location creation

  If your organization has Pro Pack for Control Hub and user authentication data turned on, Oleria also imports user sign-ins, failed sign-ins, and sign-outs. See [Prerequisites](#prerequisites). Events Oleria doesn't recognize are kept as custom events.

  Events made by the Service App Oleria connects with are shown as made by that Service App. Events made by partner administrators, Cisco, or Webex system processes are shown with an ID instead of a name, because no Webex API available to your organization lists those accounts.

Oleria refreshes users, groups, and roles on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> Oleria doesn't import spaces, messages, meetings, recordings, or calls. This integration covers identity and access governance for users, groups, administrator roles, and NHIs only.

## Prerequisites

* A Webex organization administered in Control Hub (`admin.webex.com`).
* A **Full Admin** of that organization to authorize the Service App. Read-only, device, and other administrator roles can't authorize Service Apps.
* A Webex account in the same organization to create the Service App on the Webex Developer Portal (`developer.webex.com`). This can be the Full Admin's account.
* Optional: **Pro Pack for Control Hub**, to import user sign-ins and sign-outs. A Full Admin must also turn on **Allow user authentication data** in Control Hub under **Management** -> **Organization Settings** -> **User authentication data**. Without both, Oleria imports admin audit events only.
* Admin access on the Oleria platform to add a new integration.

### Scopes

Select these scopes when you create the Service App:

| Scope | Used for |
| :- | :- |
| `spark-admin:people_read` | Users. Required. |
| `spark-admin:roles_read` | Administrator roles. Required. |
| `spark-admin:licenses_read` | License names and paid status. Without it, licenses are shown by ID. |
| `spark-admin:organizations_read` | Your organization's name. Without it, the organization is shown as Webex. |
| `spark-admin:workspaces_read` | Workspaces. Without it, Oleria skips workspaces. |
| `spark-admin:devices_read` | Devices. Without it, Oleria skips devices. |
| `identity:groups_read` | Groups and their members. Required. Also needed for **Add user to group**, **Remove user from group**, and **Create group**. |
| `identity:tokens_read` | OAuth integrations your users authorized. Without it, Oleria skips them. Also needed for **Revoke user sessions** and **Disable NHI accounts**. |
| `audit:events_read` | Activity, Service Apps, and last password changes. Required, and every remediation action needs it. |
| `spark-admin:people_write` | **Disable user accounts**, **Enable user accounts**, **Add user to role**, **Remove user from role**, **Delete user**, and **Create user**. |
| `identity:groups_rw` | **Add user to group**, **Remove user from group**, and **Create group**. |
| `identity:tokens_write` | **Revoke user sessions** and **Disable NHI accounts**. |

When you connect, Oleria checks the four required scopes. The last three scopes are needed only for [remediation actions](#remediation-actions). Without them, Oleria still syncs, and actions fail with a list of the missing scopes.

> [!WARNING]
>
> Webex requires a Full Admin to authorize the Service App again after you change its scopes, and Oleria can't sync until then. Decide whether you want remediation actions, and select the write scopes, before the app is authorized.

## Create a Service App in Webex

**1. Create the Service App**

Sign in to the [Webex Developer Portal](https://developer.webex.com) with an account in your Webex organization. Select **My Webex Apps** from the menu under your avatar, then select **Create a New App** -> **Create a Service App**. Enter a name, such as `Oleria`, a description, and a logo. Full Admins see these in Control Hub.

**2. Select the scopes**

Select the scopes listed in [Scopes](#scopes). Leave out the three write scopes if you don't want Oleria to run remediation actions.

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

Create the app, then copy the **Client ID** and **Client Secret**. Webex shows the client secret only once.

**4. Request admin approval**

If you aren't a Full Admin yourself, select **Request admin approval** on the app's page. This makes the app visible to your organization's Full Admins in Control Hub.

**5. Authorize the Service App**

A Full Admin signs in to [Control Hub](https://admin.webex.com), goes to **Management** -> **Apps** -> **Service Apps**, and selects the app. After reviewing the requested scopes, they select **Authorize**, then **Save**.

**6. Generate the tokens**

Back on the app's page in the Developer Portal, go to **Org Authorizations**. Select your organization, paste the client secret, and select **Generate tokens**. Copy the **refresh\_token** value.

> [!WARNING]
>
> The refresh token expires 90 days after Webex issues it, and Oleria can't renew it for you. Before it expires, have a Full Admin authorize the Service App again in Control Hub, generate new tokens in **Org Authorizations**, and [edit the integration](#edit-the-connection) with the new refresh token.

> [!NOTE]
>
> The Developer Portal and Control Hub change over time. If these steps don't match what you see, refer to Webex's [Service Apps](https://developer.webex.com/docs/service-apps) guide.

## Connect Webex to Oleria

**1. Open the integration**

Sign in to your Oleria workspace, navigate to **Integrations**, and select **Webex**.

**2. Complete the connection form**

Fill in the connection form:

| Field | Notes |
| :- | :- |
| Client ID | Required. The client ID of the Service App. |
| Client Secret | Required. The client secret of the same Service App. |
| Refresh Token | Required. The refresh token you generated in **Org Authorizations**. |

**3. Authenticate**

Select **Authenticate**. Oleria uses the refresh token to get an access token, reads which organization the Service App belongs to, and checks that it can list users, groups, and administrator roles and read the admin audit log. These need `spark-admin:people_read`, `identity:groups_read`, `spark-admin:roles_read`, and `audit:events_read`, and Oleria names any that's missing. Oleria saves the integration only if these checks pass. The integration is named `Webex (<organization ID>)`.

### Edit the connection

You can change the **Client Secret** and **Refresh Token** of an existing integration, for example after you renew the refresh token or regenerate the client secret. Enter both when you edit. You can't change the **Client ID**. To connect a different Service App or organization, add a new integration.

## Verify the integration

Confirm the Webex integration appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, review the discovered users, groups, administrator roles, NHIs, and activity in your Oleria workspace, and check that your Control Hub administrators are marked as administrators.

> [!NOTE]
>
> If the refresh token expires, or a Full Admin deauthorizes the Service App, Oleria can't connect to Webex. Discovery and actions stop until a Full Admin authorizes the app again and you update the **Refresh Token** in Oleria.

## Remediation actions

Oleria runs actions with the Service App's access. Each action needs the scopes listed below.

| Action | What it does | Revert |
| :- | :- | :- |
| Disable user accounts | Turns off the user's Webex sign-in. | Supported - turns the user's sign-in back on. |
| Enable user accounts | Turns on the user's Webex sign-in. | Supported - turns the user's sign-in off again. |
| Add user to role | Grants a Control Hub administrator role to the user. | Supported - removes the role. Webex Meetings site administrator access granted with it stays; see below. |
| Remove user from role | Removes a Control Hub administrator role from the user. Webex Meetings site administrator access stays; see below. | Supported - grants the role again. |
| Add user to group | Adds the user to a Webex group. | Supported - removes the user from the group. |
| Remove user from group | Removes the user from a Webex group. | Supported - adds the user back to the group. |
| Revoke user sessions | Deletes all of the user's Webex OAuth authorizations, including those for Webex portals and for integrations the user authorized. The user must sign in again, and those integrations lose access until the user authorizes them again. | Not supported - the user signs in again. |
| Disable NHI accounts | Revokes an OAuth integration for every user in your organization. OAuth integrations only. | Not supported - users must authorize the integration again. |
| Delete user | Deletes the user from your Webex organization. | Not supported - Webex can't restore a deleted user. |
| Create user | Creates a user with the email address and name you enter. Webex sends the user its activation email. Webex sets no password, and the user isn't added to any groups. Use **Add user to group** for that. If a user with that email address already exists, nothing changes. | Supported - deletes the user, if the action created them. |
| Create group | Creates a Webex group with the name you enter. If a group with that name already exists, nothing changes. | Supported - deletes the group, if the action created it. |

Each action needs these scopes:

| Action | Required scopes |
| :- | :- |
| Disable user accounts, Enable user accounts, Add user to role, Remove user from role, Delete user, Create user | `spark-admin:people_read`, `spark-admin:people_write`, `audit:events_read` |
| Add user to group, Remove user from group, Create group | `identity:groups_read`, `identity:groups_rw`, `audit:events_read` |
| Revoke user sessions, Disable NHI accounts | `identity:tokens_read`, `identity:tokens_write`, `audit:events_read` |

Before an action runs, Oleria reads the Service App's granted scopes from its authorization events in the Control Hub admin audit log, which is why every action needs `audit:events_read`. If the Service App was authorized more than a year ago and not since, Oleria can't see its scopes and doesn't block the action. Webex then refuses any change the app has no scope for.

Oleria refuses these actions and sends no change to Webex:

* Disabling the Service App the integration connects with, or deleting its account.
* Disabling any other Service App. Deauthorize it in Control Hub under **Management** -> **Apps** -> **Service Apps** instead.
* Disabling workspaces or devices.

Keep these points in mind:

* Webex replaces the whole user record on every update. To disable, enable, or change a user's roles, Oleria reads the user first and writes back the user's editable fields, including Webex Calling extension and location, with only that one change. If Webex rejects the update, the action fails and the user isn't changed.
* Enabling a user whose Webex invitation is still pending, including when you revert **Disable user accounts**, makes Webex send them the activation invitation again.
* If the target is already in the requested state, the action succeeds without making a change, and there's nothing to revert.
* When a Control Hub administrator role is granted, Webex can also give the user administrator access to your Webex Meetings sites. Removing the role doesn't remove that site access. After you remove a role, check the user's **Webex site administrator roles** in Control Hub under **Management** -> **Users** -> select the user -> **Administrator roles**.
* After Oleria revokes an authorization, Webex may keep accepting the revoked token for a short time.

## Known limitations

* **The refresh token must be renewed every 90 days.** Renewal needs a Full Admin to authorize the Service App again. See [Create a Service App in Webex](#create-a-service-app-in-webex).
* **No MFA, single sign-on, or authentication method data.** Webex's API doesn't report them, so Oleria shows them as unavailable rather than not required.
* **Last activity isn't always available.** It comes from Webex presence data, which Webex doesn't return for every user.
* **Last password change is best effort.** Oleria takes it from password-change notification events in the admin audit log from the last year. Older changes, and changes Webex didn't log, aren't shown.
* **Service Apps are found through the audit log.** Webex has no API that lists authorized Service Apps, so Oleria finds them from authorization events in the last year. A Service App authorized more than a year ago and not authorized again since isn't shown.
* **OAuth integrations show no scopes.** Webex doesn't report the scopes a user granted to an integration, so Oleria shows who authorized each integration but not what it can do. Oleria doesn't filter out Webex's own portals and clients.
* **Groups appear as custom groups.** Webex doesn't say which groups are synced from a directory, so all groups are shown as custom groups. Groups can't contain other groups.
* **Activity history covers the last year.** Oleria reads at most one year of audit events, the most Webex returns in one request. Sign-in events also need Pro Pack for Control Hub and user authentication data turned on. See [Prerequisites](#prerequisites).
* **Partner administrators and Cisco aren't shown as accounts.** Webex lists partner administrators only to partner administrators, and doesn't list Cisco's or Webex's system accounts, so their activity is shown with an ID instead of a name.
* **Not synced.** Spaces, messages, meetings, recordings, and locations aren't synced. Listing spaces, meetings, and recordings across an organization needs Compliance Officer scopes, which this integration doesn't request.
* **Commercial cloud only.** Oleria connects to Webex's commercial API (`webexapis.com`). Webex for Government organizations aren't supported.

## 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.