# Outlier Detection {% hint style="warning" %} **Early Access Feature**: Outlier Detection is currently in Early Access and available via API only. The feature and API are subject to change. Contact your Veza Customer Success Manager to enable this feature for your tenant. {% endhint %} Configure outlier detection to automatically identify and flag anomalous access patterns during Access Reviews. The Manager-Centric algorithm compares each user's access to their peer group and detects access held by fewer than a specified threshold percentage of peers, helping reviewers focus on unusual or potentially risky permissions. ## How Outlier Detection Works The Manager-Centric outlier detection algorithm uses statistical analysis to identify rare access patterns: 1. **Peer Grouping**: Users are grouped based on configurable properties (default: users sharing the same manager) 2. **Statistical Analysis**: For each destination (resource/permission) in the review, Veza calculates what percentage of the peer group has access using the Wilson score confidence interval method at 95% confidence 3. **Threshold Comparison**: Access paths where the statistical lower bound is at or below the configured threshold are flagged as outliers 4. **Reviewer Visibility**: Flagged items are highlighted in the reviewer interface with explanations indicating the access is rare within the peer group ### Default Behavior By default, outlier detection uses: * **Grouping**: Users with the same manager (`manager_idp_unique_id` property) * **Threshold**: 15% (access held by ≤15% of peers is flagged as an outlier) ### Example Scenario Consider an Access Review for Okta groups: * 100 users report to Manager A * 95 of them have access to the "Engineering-All-Hands" group * 5 users have access to the "Admin-Production-Access" group Given a 15% threshold: * "Engineering-All-Hands" access (95% of peers) is **not flagged**, as this is normal access * "Admin-Production-Access" (5% of peers) is **flagged as an outlier**, as this is rare access The reviewer sees a warning on those 5 rows that this access is anomalous within the peer group — no more than 15% of peers with shared characteristics have it. ## API Endpoints Administrators can customize outlier detection using APIs: ### Get Outlier Detection Configuration `GET /api/private/workflows/access/global_settings/manager_centric_config` Retrieve the current outlier detection configuration, either globally or for a specific review configuration. #### Parameters | Name | Type | Required | In | Description | | ------------- | ------ | -------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow_id` | string | No | query | Review configuration ID. If specified, returns the configuration for that specific review configuration. If omitted or empty, returns the global configuration. | #### Example: Get Global Configuration ```bash curl 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/manager_centric_config' \ -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \ -H 'Content-Type: application/json' ``` #### Example: Get Configuration for Specific Review ```bash curl 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/manager_centric_config?workflow_id=8ae1c414-3a76-46cb-950a-925316b3f264' \ -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \ -H 'Content-Type: application/json' ``` #### Response ```json { "value": { "grouping_properties": [ { "property_name": "manager_idp_unique_id" } ], "threshold": 0.15 } } ``` ### Set Outlier Detection Configuration `PUT /api/private/workflows/access/global_settings/manager_centric_config` Update the outlier detection configuration globally or for a specific review configuration. #### Parameters | Name | Type | Required | Description | | --------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow_id` | string | No | Review configuration ID. If specified, applies settings only to that configuration. If omitted, updates the global default. | | `value` | object | Yes | Configuration object | | `value.grouping_properties` | array | No | Array of property references defining how to group users into peer groups. If empty, uses population-wide comparison. See [Grouping Properties](#grouping-properties) below. | | `value.threshold` | number | Yes | Threshold percentage (0.0 to 1.0) below which access is considered an outlier. For example, 0.15 means access held by ≤15% of peers is flagged. | #### Example: Set Global Configuration ```bash curl -X PUT 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/manager_centric_config' \ -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "value": { "grouping_properties": [ { "property_name": "department", "target": "TARGET_NODE_SOURCE" }, { "property_name": "location", "target": "TARGET_NODE_SOURCE" } ], "threshold": 0.1 } }' ``` #### Example: Set Configuration for Specific Review ```bash curl -X PUT 'https://your-organization.vezacloud.com/api/private/workflows/access/global_settings/manager_centric_config' \ -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "workflow_id": "8ae1c414-3a76-46cb-950a-925316b3f264", "value": { "grouping_properties": [ { "property_name": "manager_idp_unique_id" } ], "threshold": 0.2 } }' ``` #### Response ```json {} ``` ## Grouping Properties Grouping properties define how users are organized into peer groups for outlier analysis. You can specify properties from: * **Source nodes** (the users/identities in the review) * **Destination nodes** (the resources/permissions being reviewed) * **Enriched/joined nodes** (additional data joined to the query, such as manager information from an IdP) ### Property Reference Schema Each property reference has these fields: | Field | Type | Required | Description | | ------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `property_name` | string | Yes | The name of the property to group by (e.g., "department", "location", "manager\_idp\_unique\_id") | | `target` | enum | No | Where the property comes from. Options: `TARGET_NODE_UNSPECIFIED` (default, assumes source), `TARGET_NODE_SOURCE`, `TARGET_NODE_DESTINATION`, `TARGET_NODE_JOINED` | | `joined_node_alias` | string | Conditional | Required when `target` is `TARGET_NODE_JOINED`. The alias of the joined node from the review query's JoinNodeSpec | ### Target Node Types #### SOURCE Node Properties Properties from the source entities in the review (typically users/identities). **Common source properties:** * `department` - User's department * `location` - User's location * `manager_idp_unique_id` - User's manager identifier (default) * `is_active` - Whether the user account is active * `employee_type` - Employee classification (e.g., full-time, contractor) **Example:** ```json { "property_name": "department", "target": "TARGET_NODE_SOURCE" } ``` #### DESTINATION Node Properties Properties from the destination entities (resources/permissions being reviewed). **Common destination properties:** * `classification` - Resource classification level * `data_sensitivity` - Data sensitivity level * `owner` - Resource owner * `environment` - Environment (prod, dev, test) **Example:** ```json { "property_name": "classification", "target": "TARGET_NODE_DESTINATION" } ``` #### JOINED Node Properties (Enrichment) Properties from enriched/joined metadata from another data source. These require the review query to include a `JoinNodeSpec` that joins additional data (such as manager information from an IdP). **Example:** ```json { "property_name": "department", "target": "TARGET_NODE_JOINED", "joined_node_alias": "manager" } ``` This groups all users by their manager's department, requiring the review query to join the manager data with the alias "manager". ## Configuration Examples ### Example 1: Default Manager-Based Grouping Groups users by manager with a 15% threshold (default configuration): ```json { "value": { "grouping_properties": [ { "property_name": "manager_idp_unique_id" } ], "threshold": 0.15 } } ``` **Use case**: Identify access that's unusual compared to direct peers reporting to the same manager. ### Example 2: Department and Location Grouping Groups users by both department and location with a 10% threshold: ```json { "value": { "grouping_properties": [ { "property_name": "department", "target": "TARGET_NODE_SOURCE" }, { "property_name": "location", "target": "TARGET_NODE_SOURCE" } ], "threshold": 0.1 } } ``` **Use case**: Identify access that's rare among users in the same department and office location. ### Example 3: No Grouping (Population-Wide) Compares each user to the entire population with 5% threshold: ```json { "value": { "grouping_properties": [], "threshold": 0.05 } } ``` **Use case**: Flag extremely rare access across the entire organization, regardless of role or department. ### Example 4: Resource Classification Grouping Groups by destination resource classification with a 20% threshold: ```json { "value": { "grouping_properties": [ { "property_name": "classification", "target": "TARGET_NODE_DESTINATION" } ], "threshold": 0.2 } } ``` **Use case**: Identify unusual access patterns within resources of the same classification level. ### Example 5: Manager's Department (Enrichment) Groups by the manager's department (requires query enrichment) with a 15% threshold: ```json { "value": { "grouping_properties": [ { "property_name": "department", "target": "TARGET_NODE_JOINED", "joined_node_alias": "manager" } ], "threshold": 0.15 } } ``` **Use case**: Identify access that's unusual among users whose managers are in the same department, useful in matrix organizations. ## Use Cases ### Finance Audit Compliance **Scenario**: Reviewing access to financial systems where SOX compliance requires attention to outlier access. **Configuration**: ```json { "value": { "grouping_properties": [ { "property_name": "department", "target": "TARGET_NODE_SOURCE" } ], "threshold": 0.05 } } ``` Users with access held by ≤5% of their department peers are flagged for additional scrutiny. ### Engineering Production Access **Scenario**: Reviewing production system access where most engineers shouldn't have admin rights. **Configuration**: ```json { "value": { "grouping_properties": [ { "property_name": "team", "target": "TARGET_NODE_SOURCE" }, { "property_name": "environment", "target": "TARGET_NODE_DESTINATION" } ], "threshold": 0.1 } } ``` Identifies engineers with production access that is unusual within their team, considering the environment. ### Role-Based Access Review **Scenario**: Reviewing access where job role should predict permissions. **Configuration**: ```json { "value": { "grouping_properties": [ { "property_name": "job_role", "target": "TARGET_NODE_SOURCE" } ], "threshold": 0.15 } } ``` Flags access held by ≤15% of users with the same job role, indicating potential role creep or over-provisioning. ### Cross-Department Anomaly Detection **Scenario**: Detecting access patterns that are unusual for an entire department. **Configuration**: ```json { "value": { "grouping_properties": [ { "property_name": "department", "target": "TARGET_NODE_SOURCE" }, { "property_name": "location", "target": "TARGET_NODE_SOURCE" } ], "threshold": 0.08 } } ``` Identifies access held by ≤8% of users in the same department and location, flagging potentially inappropriate cross-functional access. ## Important Considerations {% hint style="info" %} **Configuration Scope**: Settings can be applied globally (affecting all new reviews by default) or per-review configuration. Review-specific settings override global settings for reviews created from that configuration. {% endhint %} {% hint style="warning" %} **Property Availability**: Grouping properties must exist in your access review query results. If a specified property doesn't exist for source/destination/joined nodes, outlier detection may not function as expected. Verify property names match your data schema. {% endhint %} {% hint style="info" %} **Statistical Confidence**: The algorithm uses the Wilson score confidence interval at 95% confidence level to ensure statistically sound outlier detection even with small peer groups. Peer groups with fewer than 3 members are excluded from outlier analysis to maintain statistical validity. {% endhint %} {% hint style="success" %} **Threshold Tuning**: Start with the default 15% threshold and adjust based on your organization's risk tolerance: * **Lower thresholds** (5-10%): More sensitive, flags only the rarest access * **Higher thresholds** (20-25%): Less sensitive, flags more broadly uncommon access After implementing Outlier Detection, monitor reviewer feedback and adjust accordingly. {% endhint %} {% hint style="info" %} **Enrichment Requirements**: When using `TARGET_NODE_JOINED` properties, ensure your Access Review query includes the corresponding `JoinNodeSpec` with the matching alias. See [Access Reviews Configuration](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/access-review-settings.md) for enrichment configuration. {% endhint %} ## Related Documentation * [Access Reviews Settings](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/access-review-settings.md) - Overview of all Access Reviews settings * [Access Reviews Configuration](/4yItIzMvkpAvMVFAamTf/features/access-reviews.md) - Complete Access Reviews documentation --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/access-review-settings/outlierdetection.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.