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

# Qualys

> Connect Qualys to Oleria to discover the users, business units, user roles, Administration roles, API-only users, Cloud Agent activation keys, and activity log of your Qualys subscription, and to act on that access.

Connect Qualys to Oleria to see who has access to your Qualys subscription: every user with their status and last login, the business unit each one belongs to, their Qualys user role and Administration roles, and the API-only users and Cloud Agent activation keys that work without a person behind them. Oleria connects with the username and password of a dedicated Qualys Manager user, so you can find over-privileged and dormant accounts and take action directly from Oleria.

Each Oleria integration covers one Qualys subscription on one Qualys platform.

## What Oleria discovers

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

* **Accounts** - every Qualys user, with their name, email address, title, status, creation date, and last login date. Users that Qualys shows as **Inactive** or **Pending Activation** appear as disabled. Users with the **Manager**, **Unit Manager**, or **Administrator** user role are marked as administrators. On a subscription with Enhanced role-based access control (RBAC) turned on, Super Users are also marked as administrators. Users who hold an Administration role that can manage user accounts or roles are also marked as administrators, whatever their user role. Users who have the Security Assertion Markup Language (SAML) access permission are shown as having single sign-on configured.
* **Business units** - each business unit as a group, with its members. Users who aren't in a business unit appear in the built-in **Unassigned** group. The business unit's Unit Manager point of contact is shown as its manager.
* **Roles** - two kinds of role, with the users who hold each one:
  * Qualys user roles: the one primary role each user has, such as **Manager**, **Unit Manager**, **Administrator**, **Auditor**, **Scanner**, **Reader**, **Remediation User**, **KnowledgeBase Only**, or **Contact**.
  * Administration roles: the predefined and custom roles from the Qualys Administration module, with the permissions each role grants.
* **Non-human identities** - three kinds:
  * API-only users: Qualys users that have API access but no graphical user interface (GUI) access.
  * System users: vendor-managed Qualys users, on subscriptions with Enhanced RBAC turned on only. Oleria never deactivates, disables, or deletes them.
  * Cloud Agent activation keys: each key with its status (active, disabled, or expired), expiry date, and the modules, tags, and network it binds agents to. Each key is linked to the Qualys user who owns it. Oleria never reads or stores the key value.
* **Activity** - events from the Qualys activity log, such as sign-ins and failed sign-ins, sign-outs, password changes and resets, user activations and deactivations, configuration changes, and downloads and uploads, with the user's role and IP address. Other events appear with their Qualys module and action.

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

> [!NOTE]
>
> Oleria doesn't import hosts, assets, asset groups, scans, reports, or vulnerabilities. This integration covers identity and access governance for your Qualys subscription only.

## Prerequisites

* A Qualys subscription with API access enabled for it.
* A dedicated Qualys user for Oleria with the **Manager** user role and the **API access** permission. See [Create the Qualys user](#create-the-qualys-user).
* The Qualys platform that hosts your subscription. Find it under **Help** > **About** in the Qualys UI. Alternatively, identify it on the [Qualys platform identification page](https://www.qualys.com/platform-identification/). See [Supported platforms](#supported-platforms).
* Optional: a second Manager user with API access, if you want Oleria to run remediation actions with a separate credential.
* Admin access to the Oleria workspace.

### Why the user must be a Manager

Qualys has no read-only role that can see the whole subscription. Only a Manager sees every user together with every last login date and every activity log entry. Other roles get a narrower view, without telling Oleria that anything is missing:

* A **Unit Manager** can manage only the users in its own business unit.
* An **Administrator** can't manage Manager or Administrator users.
* **Scanner** and **Reader** users see only their own activity, without usernames.

To keep Oleria from syncing a partial view, Oleria refuses a connection user with any role other than Manager. On a subscription with Enhanced RBAC turned on, a Super User is also accepted.

## Supported platforms

Oleria supports the 14 shared Qualys platforms. Select yours by the API server address that **Help** > **About** shows in the Qualys UI:

| Platform | API server |
| :- | :- |
| US1 | `qualysapi.qualys.com` |
| US2 | `qualysapi.qg2.apps.qualys.com` |
| US3 | `qualysapi.qg3.apps.qualys.com` |
| US4 | `qualysapi.qg4.apps.qualys.com` |
| GOV1 | `qualysapi.gov1.qualys.us` |
| EU1 | `qualysapi.qualys.eu` |
| EU2 | `qualysapi.qg2.apps.qualys.eu` |
| EU3 | `qualysapi.qg3.apps.qualys.it` |
| IN1 | `qualysapi.qg1.apps.qualys.in` |
| CA1 | `qualysapi.qg1.apps.qualys.ca` |
| AE1 | `qualysapi.qg1.apps.qualys.ae` |
| UK1 | `qualysapi.qg1.apps.qualys.co.uk` |
| AU1 | `qualysapi.qg1.apps.qualys.com.au` |
| KSA1 | `qualysapi.qg1.apps.qualysksa.com` |

Oleria derives every address it calls from the platform you select. You don't type a URL.

> [!WARNING]
>
> Qualys Private Cloud Platforms aren't supported.

## Create the Qualys user

**1. Create the user**

Sign in to the Qualys UI as a Manager. In the Vulnerability Management (VM) or Vulnerability Management, Detection and Response (VMDR) application, go to **Users** > **Users** > **New** > **User** and create a new user for Oleria. Use a dedicated user rather than a named person's account.

**2. Set the role and access**

Set **User Role** to **Manager**, and give the user the **API access** permission. Keep GUI access for now, because you need it to activate the user.

**3. Activate the user**

Sign in to the Qualys UI once with the new user and accept the end user license agreement (EULA), so Qualys activates the account. Alternatively, accept the EULA for it with Qualys's `/msp/acceptEULA.php` API. Qualys refuses API requests from a user that hasn't completed registration.

**4. Optional: remove GUI access**

After the user is activated, you can remove its GUI access, because Oleria only uses the API. When Qualys reports the user's GUI access as off, Oleria lists this user as an API-only user (a non-human identity), and never disables it.

**5. Optional: create an action user**

To run remediation actions with a separate credential, repeat these steps for a second Manager user with API access. Oleria uses this user only for actions. If you skip it, actions run as the first user.

> [!WARNING]
>
> Don't turn on SecureID for the Oleria users. Qualys blocks API access for users that require SecureID authentication. Your Qualys password expiry policy also applies to these users: if a password expires, syncs and actions fail until you update it in Oleria.

> [!NOTE]
>
> On a subscription with Enhanced RBAC turned on, you manage users in the Qualys Administration module instead. Go to **Administration** > **User Management** > **Users** > **Create User**. The exact location of these settings can change over time. If the steps above don't match what you see, refer to Qualys's own documentation.

## Permissions Oleria needs

Qualys has no grantable scopes. Each read and action needs a user role plus an access permission.

### Read permissions

The integration's **Capabilities** tab shows **Read users**, **Read groups**, and **Read roles** with the permissions each one needs, and checks them against the connection user.

| What Oleria reads | What it needs |
| :- | :- |
| Users and API-only users | Qualys user role **Manager** and the **API access** permission. |
| Business units | Qualys user role **Manager** and the **API access** permission. |
| User roles and Administration roles | Qualys user role **Manager** and the **API access** permission. |
| Cloud Agent activation keys | The same Manager user. If your subscription doesn't include Cloud Agent, Oleria skips activation keys and syncs everything else. |
| Activity log | The same Manager user. Only a Manager sees every user's activity. |

If Qualys reports that the user or subscription isn't authorized to use one of these APIs, Oleria marks that read as needing permission.

### Write permissions

Every remediation action runs as the action user, or as the connection user when you didn't set one. That user needs:

| Action | What it needs |
| :- | :- |
| Disable user account / Enable user account | Qualys user role **Manager** and the **API access** permission. |
| Create user | Qualys user role **Manager** and the **API access** permission. |
| Delete user | Qualys user role **Manager** and the **API access** permission, on a subscription with Enhanced RBAC turned on. |
| Add user to role / Remove user from role | Qualys user role **Manager** and the **API access** permission. |
| Disable NHI | Qualys user role **Manager** and the **API access** permission. |

Before every action, Oleria reads the user list and checks that the action user is still a Manager. If not, the action doesn't run.

## Connect Qualys to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations**, then select the **Qualys** tile.

**2. Complete the connection form**

| Field | Notes |
| :- | :- |
| Qualys platform | Required. The shared Qualys platform that hosts your subscription, for example `US1 (qualysapi.qualys.com)`. You can't change it after you create the integration. To move to another platform, create a new integration. |
| Username | Required. The Qualys Manager user with API access. |
| Password | Required. That user's password. Oleria stores it encrypted after it validates the connection. |
| Action username (optional) | A second Qualys Manager user with API access that Oleria uses only for remediation actions. Leave it empty to run actions with the user above. |
| Action user password | Required when you set an action username. |
| New user address (optional) | The address Oleria gives every Qualys user it creates. |
| New user city (optional) | The city Oleria gives every Qualys user it creates. |
| New user country (optional) | The country Oleria gives every Qualys user it creates. |
| New user phone number (optional) | The phone number Oleria gives every Qualys user it creates. |
| New user state (optional) | The state Oleria gives every Qualys user it creates. Qualys requires a state only for addresses in the United States, Australia, Canada, and India. |

**3. Authenticate**

Select **Authenticate**. Oleria signs in as the user, reads the whole user list, and checks that the user is a Manager before it saves anything. If you set an action user, Oleria checks that user the same way.

The new integration is named after its platform, for example `Qualys (US1)`.

### New user address fields

Qualys requires an address, city, country, and phone number on every new user, and a state for the United States, Australia, Canada, and India. Oleria's **Create user** action doesn't carry an address, so Oleria uses the **New user** fields instead. Fill them in only if you want Oleria to create Qualys users. If they're empty, the **Create user** action fails with a message asking for them. The other actions don't use them.

### Edit the integration

When you edit the integration, select **Update** to save. The **Qualys platform** can't be changed.

* Leave **Password** empty to keep the stored password.
* Leave **Action user password** empty to keep the stored one, as long as **Action username (optional)** is unchanged. A new action username needs its password.
* Clear **Action username (optional)** to remove the stored action user. Actions then run as the connection user.

## Verify the integration

Confirm Qualys appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, check that your Qualys users, business units, and roles appear in your Oleria workspace, that your Managers are marked as administrators, and that your API-only users and activation keys appear as non-human identities.

If Oleria can't connect, the message names the problem:

| Message mentions | What to do |
| :- | :- |
| Bad Login/Password | Check the username and password, and that the platform matches your subscription under **Help** > **About**. |
| Qualys returned no user record | Check that the username is the exact Qualys login, and that the user has the **Manager** role. |
| A role other than Manager | Change the user's **User Role** to **Manager**, or use another Manager user. |
| Inactive (code 2002) | Activate the user in Qualys, or use another Manager user. |
| Registration not completed (code 2003) | Sign in to the Qualys UI once with the user, or accept the EULA with `/msp/acceptEULA.php`, then try again. |
| SecureID (code 2011) | Use a user that doesn't require SecureID. |
| Not authorized to use this API (code 2012) | Give the user the **API access** permission, or ask Qualys to turn on API access for your subscription. |
| Rate limiting (HTTP 409) | Try again after the wait that Qualys advertises. |

## Remediation actions

Oleria can take these actions in Qualys. Each one runs as the action user, or as the connection user when you didn't set one.

| Action | What it does | Revert |
| :- | :- | :- |
| Disable user account | Deactivates the Qualys user. Qualys keeps the user's account settings. If the user is already inactive, nothing changes. | Yes - reactivates the user. |
| Enable user account | Reactivates an inactive Qualys user. If the user is already active, nothing changes. | Yes - deactivates the user again. |
| Create user | Creates a Qualys user with the name and email address you give, the **Reader** user role, the **Unassigned** business unit, and the title `Employee`, unless the action sets others. Qualys generates the login, so the username you request isn't used. Qualys emails the new user a registration link, and the user stays **Pending Activation** until their first sign-in. No password passes through Oleria. If an active or pending user with the same name and email address already exists, nothing changes. If that user is inactive, the action fails: use **Enable user account** instead. | No - see below. |
| Delete user | Deletes the Qualys user, on a subscription with Enhanced RBAC turned on. The deleted user's objects are handed over to the action user. | No - a deleted Qualys user can't be restored. |
| Add user to role / Remove user from role | Grants or revokes a Qualys Administration role. If the user already has the requested state, nothing changes. | Yes - applies the opposite change to that one role. |
| Disable NHI | For an API-only user, deactivates the user. For a Cloud Agent activation key, disables the key. If it's already disabled, nothing changes. | Yes - reactivates the user or re-enables the key. |

Keep these limits in mind when you use these actions:

* Oleria reads the current state before it changes anything. A revert undoes only the change the action made. If the action changed nothing, the revert changes nothing too.
* After a role change or an activation key change, Oleria reads the state again to confirm that Qualys applied it.
* **Create user can't be reverted** on a subscription without Enhanced RBAC. Qualys's user API has no delete, and Qualys can't deactivate a **Pending Activation** user. Remove or deactivate the user in the Qualys UI. If the subscription has turned on Enhanced RBAC since the user was created, reverting deletes the user.
* **Create user isn't available on Enhanced RBAC subscriptions.** Create the user in Qualys.
* **Delete user can't be reverted.** Recreating a user gives it a new Qualys login, so it appears in Oleria as a new account. Without Enhanced RBAC, Qualys has no delete API, so use **Disable user account** instead.
* **Only Administration roles can be granted or revoked.** Qualys doesn't let the API change a user's primary user role, such as Manager or Reader. On a subscription without Enhanced RBAC, Qualys doesn't return the Administration roles of Managers, Super Users, or inactive users, so Oleria can't confirm their current roles and refuses to change them.
* **Disable NHI** acts only on users that Oleria discovered as API-only users, and on activation keys.
* Qualys can't activate or deactivate a **Pending Activation** user, so Oleria refuses.
* Oleria never deactivates or deletes the connection user or the action user, and never removes a role from them. It never deactivates, disables, or deletes Qualys system users.
* Oleria can't change a user's business unit, create business units, or reset passwords.

## Enhanced RBAC

Qualys lets a Manager turn on Enhanced RBAC in the Administration module. After that, user management moves from the Vulnerability Management application to the Administration module, and Qualys's older user APIs stop working.

Oleria supports both modes. It detects which mode your subscription uses on every sync and before every action, so you don't need to configure anything, and nothing breaks if you turn on Enhanced RBAC later. Your accounts, groups, and roles keep the same IDs in Oleria in both modes.

The mode changes which actions are available:

* **Delete user** is available only with Enhanced RBAC.
* **Create user** is available only without Enhanced RBAC.

## Known limitations

* **No multi-factor authentication status.** Qualys supports two-factor authentication for sign-ins to the Qualys UI only, and no Qualys API reports it for a user or the subscription. Oleria shows MFA status as unavailable.
* **No last password change date.** No Qualys API reports when a user last changed their password.
* **Single sign-on is shown as configured, not enforced.** Oleria reads each user's SAML access permission. Qualys doesn't report whether single sign-on is required.
* **Primary user roles and business units can't be changed from Oleria.** Qualys doesn't allow either to be changed through its API. Change them in the Qualys UI.
* **Low subscription tiers have tight API limits.** Qualys limits API calls per subscription and per API. On the lowest tiers, the default is one call at a time and 50 calls a day. Oleria spaces its calls and waits when Qualys asks it to. If Qualys asks for a wait of more than a few minutes, the sync fails instead of waiting. If syncs keep failing on rate limits, ask Qualys to raise your limits.
* **Private Cloud Platforms aren't supported.** Only the [14 shared platforms](#supported-platforms) are.
* **One subscription per integration.** The platform can't be changed after you connect. To connect another subscription or platform, add another integration.
* **API-only users depend on Qualys reporting access methods.** Oleria lists a user as an API-only user only when Qualys reports that the user's GUI access is off. If Qualys doesn't report GUI access, Oleria shows the user as a person, not a non-human identity. On Enhanced RBAC subscriptions, Qualys doesn't report access methods, so Oleria doesn't discover API-only users there.
* **Administration roles can be partial.** If your subscription doesn't allow the Administration role APIs, Oleria shows Qualys user roles only. Without Enhanced RBAC, Qualys doesn't list Managers, Super Users, or inactive users as holders of Administration roles.
* **No creation date with Enhanced RBAC.** Qualys reports a user's creation date only on subscriptions without Enhanced RBAC.
* **Activity covers the Qualys activity log only.** Oleria imports at most the last 90 days. With Enhanced RBAC, the Administration audit log isn't imported. Oleria skips its own API calls, and skips events that have no username. Configuration and user changes are linked to the Qualys subscription, not to the object they changed, because Qualys doesn't name the object in a fixed format. On a very busy subscription, a sync window can hold more events than Oleria reads in one sync, and the rest are skipped.
* **No creation date or last use for activation keys.** Qualys doesn't report them.
* **Some identities aren't inventoried.** Qualys Managed Token API clients have no API to list them. Authentication records, scanner appliances, and access by Qualys partners, consultants, or Qualys Support aren't imported.

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