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

# IBM Verify

> Connect an IBM Verify tenant to Oleria to discover users, groups, admin roles, applications and their access, API clients and machine-to-machine applications, MFA enrollments, identity threats, and activity, and take remediation actions directly from Oleria.

IBM Verify (formerly IBM Security Verify) is IBM's cloud identity provider. Connect an IBM Verify tenant to Oleria to see who can sign in through it, which applications they can reach, who administers the tenant, and which API clients and applications act as non-human identities. Oleria reads this data from the IBM Verify APIs with an API client that you create in the IBM Verify admin console. You can then review over-provisioned access and take action directly from Oleria.

One Oleria integration covers one IBM Verify tenant. To connect another tenant, add another integration.

## What Oleria discovers

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

* **Users** - every user, with username, display name, email address, title, department, employee number, and whether the user is active. Oleria also shows when each user was created, last modified, and set to expire, the user's realm, and, when IBM Verify records them, their manager, delegate, and when their password was locked. Last activity is the later of the user's last sign-in and last MFA use.
  * Users in IBM Verify's Cloud Directory sign in with an IBM Verify password. Oleria shows when they last changed it.
  * Users from an identity source, such as an enterprise SAML or OIDC provider, sign in through that source, so SSO shows as required for them. Users from a social identity source, such as Google, Facebook, or LinkedIn, appear as external users.
  * Users who hold any IBM Verify admin role, directly or through a group, are marked as administrators. Each administrator's account role is `admin:tenantadmin` when they hold the tenant administrator role, and otherwise one of their admin roles. Other users show the account role `user`.
* **Sign-in methods and MFA** - each user's password or identity source, plus the MFA methods they've enrolled and used: email, SMS, and voice one-time codes, authenticator app (TOTP), FIDO2 and passkeys, security questions, IBM Verify app push, and QR code sign-in. MFA status comes from the first of these that applies:

  | Condition | MFA shown |
  | :- | :- |
  | Two-factor authentication is turned on for the user | Required |
  | The tenant's default access policy always requires MFA | Required |
  | The tenant's default access policy requires MFA under some conditions | Adaptive |
  | The tenant's MFA settings require users to enroll a factor | Awaiting enrollment |
  | None of the above | Not required |

  If the API client can't read access policies, MFA shows as unavailable for users who don't have two-factor authentication turned on.
* **MFA factors and enrollments** - each MFA factor type the tenant offers, and each user's enrollments, shown as active, pending until validated, or suspended when disabled.
* **Groups** - three kinds, with their members:

  * **Standard groups**, shown as custom groups, including groups nested in other groups. Each group shows its description, creation and modification dates, member count, and its owners.
  * **Reserved groups**, the groups IBM Verify creates, such as the admin and developer groups, shown as built-in groups.
  * **Dynamic groups**, whose members IBM Verify computes from a rule, shown as dynamic groups with their creator and status.

  Oleria also shows a built-in group named **All IBM Verify users**, with every user as a member. It stands for the applications that every user can access. See **Applications**.
* **Roles** - IBM Verify's admin roles and admin permissions, such as tenant administrator and user administrator. Roles that IBM provides are standard roles. Roles you create are custom roles. Each role shows which roles and permissions it contains, so its holders get all of their access. Roles are granted to users and to groups, including dynamic groups. A grant with an end date shows its expiration. Disabled grants, grants past their end date, and grants of a disabled admin role aren't shown.
* **Applications** - every application in the tenant, with its type, template, whether it's enabled, its provisioning mode, and its OAuth client ID or SAML entity ID. Each application shows who can access it: users, groups, and dynamic groups granted access, with the application roles each holds. When an application gives every user access, Oleria shows access from the **All IBM Verify users** group.
* **Application roles** - the roles and permissions defined for each application, linked to their application.
* **Non-human identities (NHIs):**

  | Identity | Shown as |
  | :- | :- |
  | API clients | API token, with its client ID, description, entitlements, client authentication method, access token type, and whether it's enabled and restricted by IP address. API clients with `tenantAdmin`, `manageAPIClients`, or `manageEntitlements` are marked as administrators. The API client the integration connects with is marked as such. |
  | Applications that authenticate as themselves | Application, for each application whose OIDC settings allow the client credentials, JWT bearer, or token exchange grant. Each shows its client ID, enabled grants, client authentication method, and owners. |

  Each NHI also appears with its credential: a client secret, a key pair for `private_key_jwt` clients, or a certificate for mutual TLS clients. Oleria records that a credential exists, never its value. Last used is the newest token that IBM Verify issued to the client in the last 90 days.
* **Identity threats** - detections from IBM Verify identity threat protection in the last 90 days, shown as risks on the tenant: multiple failed logins, compromised credentials, login deviations, credential stuffing, abnormal user activity, and other threats. Warning detections are moderate risks and critical detections are high risks. Each shows the rule, its summary, start and end times, the number of impacted users, and the IDs of the compromised users.
* **Activity** - events from the IBM Verify event log:

  * sign-ins, failed sign-ins, and sign-outs, including SSO sign-ins to applications, with the IP address, location, realm, device type, and the sign-in or MFA method used
  * tokens issued to and revoked for API clients and applications that authenticate as themselves
  * management events: users created, changed, deleted, enabled, or disabled, password resets, group changes and membership changes, admin and application access granted and revoked, application changes, API clients created, changed, and deleted, MFA factors added and removed, and access and password policy changes
  * access policy decisions: sign-ins that adaptive access or an access policy allowed or denied, with the risk level and the rule that matched
  * identity governance events: access requests submitted, approved, and rejected, certification campaign decisions to keep or revoke access, and accounts provisioned or deprovisioned in applications
  * users who self-register, and privacy consents users grant or withdraw
  * service, notice, and digital badge events, kept as custom events

  Each event is credited to the user, API client, or application that IBM Verify names as performing it. Events that IBM Verify performs on its own, such as automatic deprovisioning, have no performer. Failed events show IBM Verify's reason. Events Oleria doesn't recognize are kept as custom events.

Oleria refreshes users, groups, roles, and applications on its [regular sync schedule](https://docs.oleria.com/integrations/overview.md#sync-model). Activity syncs separately.

> [!NOTE]
>
> This integration covers identities, access to applications, roles, and activity. IBM Verify has no resource inventory, so Oleria doesn't populate resource-level Access Graph or Access Inventory data for IBM Verify.

## Prerequisites

* An IBM Verify tenant on `verify.ibm.com`, such as `acme.verify.ibm.com`.
* An IBM Verify administrator who can create API clients under **Security** -> **API access**, such as a tenant administrator.
* Admin access on the Oleria platform to add a new integration.

### Permissions

Oleria uses one API client for both discovery and remediation actions. The client's entitlements decide what Oleria can read and change. IBM Verify accepts any one of the entitlements listed for an operation.

Read entitlements:

| Entitlement | Used for | Also accepted |
| :- | :- | :- |
| `readUserGroups` | Users and their group memberships, and groups and their members. Required to connect. | Users: `readUsersGroupMembership`, `manageUserGroups`, `manageAllUserGroups`, `manageUsers`. Groups: `readGroupMembers`, `manageUserGroups`, `manageAllUserGroups`, `manageGroupMembers`. |
| `readEntitlements` | Admin roles and permissions and who holds them, and application roles and who holds them. Required to connect. | `manageEntitlements`, `tenantAdmin` |
| `manageAppAccessAdmin` | Applications, who can access them, and the applications that act as non-human identities. IBM Verify has no read-only entitlement for applications. See the warning below. | - |
| `readAPIClients` | API clients. Also required for actions: Oleria checks the API client's own entitlements before an action runs. | `manageAPIClients` |
| `readDynamicGroups` | Dynamic groups and their members. | `manageDynamicGroups`, `tenantAdmin` |
| `readEnrollMFAMethodAnyUser` | MFA factors, users' MFA enrollments, and whether the tenant requires users to enroll a factor. | - |
| `readAccessPolicies` | The tenant's default access policy, for MFA status. | - |
| `readReports` | Activity, identity threats, and the last-used dates of API clients and applications. | `manageReports` |

Don't use `readUsers` or `readGroups` in place of `readUserGroups`: they don't return group memberships.

If the API client is missing an entitlement other than `readUserGroups` and `readEntitlements`, Oleria skips that data and syncs the rest of the tenant. The exception is activity: without `readReports`, the activity sync fails rather than showing no activity.

Remediation entitlements, required for actions:

| Entitlement | Actions | Also accepted |
| :- | :- | :- |
| `updateAnyUser` | Disable user accounts, Enable user accounts, Activate user accounts | `manageUsers`, `manageUserGroups`, `manageAllUserGroups`, `manageUserStandardGroups`, `manageUsersInStandardGroups` |
| `updateAnyGroupMember` | Add user to group, Remove user from group | `manageGroupMembers`, `manageStandardGroupMembers`, `manageUserGroups`, `manageAllUserGroups`, `manageUserStandardGroups` |
| `manageEntitlements` | Add user to role, Remove user from role | `tenantAdmin` |
| `manageAppAccessAdmin` | Assign and remove user and group application entitlements | `manageAppAccessOwner` |
| `manageUsers` | Create user, Delete user | `manageUserGroups`, `manageAllUserGroups`, `manageUserStandardGroups`, `manageUsersInStandardGroups` |
| `manageGroups` | Create group | `manageUserGroups`, `manageAllUserGroups`, `manageStandardGroups`, `manageUserStandardGroups` |
| `revokeAllSessions` | Revoke user sessions | `manageLoginSessions` |
| `manageAPIClients` | Disable NHI accounts | - |

Grant only the remediation entitlements of the actions you plan to use. Before an action runs, Oleria checks that the API client holds the action's entitlement, and refuses the action if it doesn't.

> [!WARNING]
>
> `manageAppAccessAdmin` can change applications and who can access them, not only read them. IBM Verify has no read-only alternative, so Oleria needs it to show applications, application access, and applications that act as non-human identities. Without it, Oleria syncs the rest of the tenant without them. Store and rotate this API client's secret as you would an administrator credential.

> [!NOTE]
>
> Use a dedicated API client for this integration. Oleria never disables the API client it connects with.

## Create an API client in IBM Verify

**1. Open API access**

Sign in to the IBM Verify admin console and go to **Security** -> **API access**. Click **Add API client** and name it `Oleria`.

**2. Select the read entitlements**

Under **Entitlements**, select `readUserGroups` and `readEntitlements`, which Oleria needs to connect, plus `manageAppAccessAdmin`, `readAPIClients`, `readDynamicGroups`, `readEnrollMFAMethodAnyUser`, `readAccessPolicies`, and `readReports`. Read the [warning about `manageAppAccessAdmin`](#permissions) first.

**3. Select the remediation entitlements (optional)**

To let Oleria take [remediation actions](#remediation-actions), also select the entitlements of the actions you'll use: `updateAnyUser` to disable and enable users, `updateAnyGroupMember` for group membership, `manageEntitlements` for admin roles, `manageUsers` to create and delete users, `manageGroups` to create groups, `revokeAllSessions` to revoke sessions, and `manageAPIClients` to disable API clients. Application access actions use `manageAppAccessAdmin`, which you selected in the previous step.

**4. Copy the credentials**

Save the API client, then copy its **Client ID** and **Client secret** from **Security** -> **API access**.

If you restrict the API client to specific IP addresses, allow Oleria's IP addresses. Contact [support@oleria.com](mailto:support@oleria.com) for the current list.

> [!NOTE]
>
> The IBM Verify admin console changes over time. If these steps don't match what you see, refer to IBM's [API access](https://docs.verify.ibm.com/verify/docs/api-access) documentation.

## Connect IBM Verify to Oleria

**1. Open the integration**

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

**2. Complete the connection form**

Fill in the connection form:

| Field | Notes |
| :- | :- |
| Tenant host | Required. The host name of your IBM Verify tenant, for example `acme.verify.ibm.com`. Only tenants on `verify.ibm.com` are supported. A leading `https://` or a trailing path is ignored. |
| Client ID | Required. The client ID of the API client you created. |
| Client secret | Required. The client secret of that API client. |

**3. Authenticate**

Select **Authenticate**. Before it saves anything, Oleria gets a token for the API client and checks that it can read users, groups, and admin roles. If IBM Verify rejects the client ID or secret, check both values and that the API client is enabled. If `readUserGroups` or `readEntitlements` is missing, Oleria names the missing entitlement. Other missing read entitlements don't block the connection.

Find the newly connected tenant, named `IBM Verify (<tenant host>)`, on the **Connected** tab of your Oleria **Integrations** page.

### Edit the connection

You can change the **Client ID** and **Client secret** of an existing integration. Leave **Client secret** blank to keep the stored secret. If you change the **Client ID**, also enter that API client's secret. You can't change the **Tenant host**. To connect a different tenant, add a new integration.

## Verify the integration

Confirm the IBM Verify 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, groups, roles, applications, non-human identities, and activity in your Oleria workspace.

In the integration's **Capabilities and operation readiness** section, **Read users**, **Read groups**, and **Read roles** show **Available**. If one shows **Needs permission**, add the missing entitlement to the API client:

| Row | Entitlement |
| :- | :- |
| Read users | `readUserGroups` |
| Read groups | `readUserGroups` |
| Read roles | `readEntitlements` |

When the API client has `readAPIClients`, the section also lists the entitlements the API client holds.

## Remediation actions

Oleria runs actions with the integration's API client. Each action needs the entitlement listed in [Permissions](#permissions), plus `readAPIClients`.

| Action | What it does | Revert |
| :- | :- | :- |
| Create user | Creates a Cloud Directory user with the username, or the email address when no username is given, plus the first and last name, display name, and work email address you provide. The user is inactive unless you choose to activate it. If you don't provide a password, IBM Verify generates one. IBM Verify doesn't email the user, so set or reset the password before the user's first sign-in. The user is then added to the requested groups. If a user with that username already exists, nothing changes. If adding a group fails, Oleria deletes the user it just created and the action fails. | Supported - deletes the user the action created. |
| Delete user | Permanently deletes the user, without notifying them. To block sign-in without deleting, use **Disable user accounts**. | Not supported - IBM Verify can't restore a deleted user. |
| Disable user accounts | Sets the user to inactive, without notifying them. | Supported - sets the user to active again. |
| Enable user accounts | Sets the user to active. | Supported - sets the user to inactive again. |
| Activate user accounts | Sets the user to active, such as a user that **Create user** created. It works the same way as **Enable user accounts**. | Supported - sets the user to inactive again. |
| Revoke user sessions | Ends every sign-in session the user has. | Not supported - the user signs in again. |
| Add user to group | Adds the user to a standard group. | Supported - removes the user from the group. |
| Remove user from group | Removes the user from a standard group. | Supported - adds the user back. |
| Create group | Creates an empty standard group with the name you enter. If a group with that name already exists, nothing changes. | Supported - deletes the group the action created. |
| Add user to role | Grants an IBM Verify admin role or admin permission to the user directly. | Supported - removes the grant. |
| Remove user from role | Removes the user's direct grant of an admin role or admin permission. | Supported - grants it again. |
| Assign user to application entitlement | Gives the user direct access to an application. | Supported - removes only the grant the action created. |
| Remove user from application entitlement | Removes the user's direct access to an application. | Supported - gives the user access again. |
| Assign group to application entitlement | Gives a group or dynamic group access to an application. | Supported - removes only the grant the action created. |
| Remove group from application entitlement | Removes a group's or dynamic group's access to an application. | Supported - gives the group access again. |
| Disable NHI accounts | Disables an API client, so it can no longer get tokens. Oleria sends the API client back to IBM Verify unchanged apart from its status, so its secret and entitlements stay the same. | Supported - enables the API client again. |

| Identity | Disable NHI supported |
| :- | :- |
| API client | Yes |
| Application that authenticates as itself | No. IBM Verify applications have no disabled state. Only deleting the application or rotating its secret is possible, and neither can be reverted. |

Oleria refuses these actions and sends no change to IBM Verify:

* Changing the membership of reserved groups, dynamic groups, or the **All IBM Verify users** group. IBM Verify computes dynamic group membership from the group's rule.
* Removing the tenant's last user who holds the tenant administrator role directly.
* Removing a role that the user holds only through a group. Remove the user from the group instead.
* Removing application access that the user has only through a group, a dynamic group, or because the application gives every user access. Change the group's access or the application's settings in IBM Verify instead.
* Assigning or removing application access for the **All IBM Verify users** group. Whether every user can access an application is a setting of the application in IBM Verify.
* Disabling the API client the integration connects with.
* Disabling an API client that IBM Verify returns without its secret. IBM Verify would generate a new secret for it, which would break whatever uses the API client.

Keep these points in mind:

* Oleria reads the target before it changes anything. If the target is already in the requested state, the action succeeds without making a change, and there's nothing to revert.
* After each change, Oleria reads the target again. If IBM Verify didn't apply the change, the action fails.
* When you remove a direct grant of a role or application access that the user also has through a group or for every user, Oleria removes the direct grant, and the result notes that the user keeps the access.
* Before an action runs, Oleria checks that the API client holds the action's entitlement. This needs `readAPIClients`; without it, Oleria doesn't run actions and reports that `readAPIClients` is missing.
* Reverting checks the target first. If it changed after the action ran, or no longer exists, Oleria leaves it as is.

## Known limitations

* **Only `verify.ibm.com` tenants.** Tenants on the older `ice.ibmcloud.com` domain and custom domains can't be connected.
* **Applications need `manageAppAccessAdmin`.** IBM Verify has no read-only entitlement for applications. Without it, Oleria shows no applications, no application access, and no applications that act as non-human identities.
* **Activity history is limited to 90 days.** IBM Verify keeps events for 90 days. The first sync imports activity from that window only, identity threats cover the last 90 days, and an API client or application with no token in that window has no last-used date. If a five-minute period holds more events than the IBM Verify events API returns for one query, some of those events may be missing.
* **Some event types aren't imported.** Account sync, registration drop-off, and gateway agent health events aren't synced. They report reconciliation jobs, sign-up analytics, and on-premises gateway health rather than changes to users or access.
* **Large groups may show no members.** On tenants without IBM Verify's large group support, IBM Verify doesn't list the members of a group with more than 10,000 members. Oleria shows the group without its members and marks it as truncated.
* **Applications can't be disabled as NHIs.** See [Remediation actions](#remediation-actions).
* **API clients have no owner or creation date.** IBM Verify doesn't record who owns or created an API client, or when. Secret creation and rotation dates aren't available either, because Oleria never reads secrets.
* **Password change dates are for Cloud Directory users only.** Users from an identity source have no IBM Verify password.
* **No impersonation.** A user's delegate in IBM Verify receives the user's approval and recertification tasks, not the ability to sign in as the user, so Oleria shows the delegate on the user without an impersonation link.
* **Identity threats are shown on the tenant.** Each threat lists the IDs of the compromised users in its details instead of being linked to their accounts.
* **Application roles can only be viewed.** Role actions apply to IBM Verify admin roles and admin permissions. Manage application roles in IBM Verify.
* **Not synced.** Accounts that IBM Verify provisions in downstream applications, identity source configurations, access requests and certification campaigns, consent records, workflow models, and the IBM Verify app registrations of each user aren't synced.

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