Skip to content

Adds doc for using detectors and forecaster with resource access control #11572

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 7 commits into
base: main
Choose a base branch
from
+281 −0
Draft

Adds doc for using detectors and forecaster with resource access control #11572

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c55d233
Initial commit
DarshitChanpura Nov 20, 2025
4ae2155
Update AD doc
DarshitChanpura Nov 20, 2025
422499e
Adds forecaster doc and updates AD doc
DarshitChanpura Nov 21, 2025
677f91f
Updates doc and addresses review dog errors
DarshitChanpura Nov 21, 2025
5228cbf
minor update
DarshitChanpura Nov 21, 2025
bfe2c31
Add a section for migration info
DarshitChanpura Nov 21, 2025
741abbc
Fix lingo
DarshitChanpura Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions _observing-your-data/ad/detector-access-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
---
layout: default
title: Anomaly detector access control
nav_order: 5
parent: Anomaly detection
has_children: false
redirect_from:
- /monitoring-plugins/ad/detector-access-control/
---

# Anomaly detector access control

**Status:** Experimental
**Replaces:** `plugins.anomaly_detection.filter_by_backend_roles`
{: .warning }

This page explains how **Anomaly Detection (AD)** integrates with the Security plugin’s **Resource Sharing and Access Control** framework to provide **document-level** authorization for detectors.

> For the end-to-end framework concepts and APIs, see [Resource Sharing and Access Control]({{site.url}}{{site.baseurl}}/security/access-control/resources/)
{: .note}

---

## Onboarding

- **Resource type:** `anomaly-detector`
- **System index:** `.opendistro-anomaly-detectors`
- **Onboarded in:** `3.3`

Check failure on line 28 in _observing-your-data/ad/detector-access-control.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Onboarded. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Onboarded. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_observing-your-data/ad/detector-access-control.md", "range": {"start": {"line": 28, "column": 5}}}, "severity": "ERROR"}

When resource-level authorization is enabled for this type, each detector’s visibility is governed by a central sharing record. Owners and users with share capability can grant or revoke access for specific **users**, **roles**, or **backend roles**.

---
## Enable or disable for this resource type

Add the type to the protected list and enable the feature.

> **Admin-only:** These settings can be configured **only by cluster administrators** (super-admins).
{: .important }

### `opensearch.yml` (3.3+)

```yaml
plugins.security.experimental.resource_sharing.enabled: true
plugins.security.system_indices.enabled: true
plugins.security.experimental.resource_sharing.protected_types:
- "anomaly-detector"
````

### Dev Tools (3.4+)

```curl
PUT _cluster/settings
{
"transient": {
"plugins.security.experimental.resource_sharing.enabled": true,
"plugins.security.experimental.resource_sharing.protected_types": ["anomaly-detector", <existing-resource-types>]
}
}
```
{% include copy-curl.html %}

---

## Anomaly detector access levels

AD exposes **three access levels** for granting access to detectors:

### ad_read_only
This read-only access level grants a read and search only access to the shared detector.

Following actions are allowed with this access-level:
```yaml
- 'cluster:admin/opendistro/ad/detector/info'
- 'cluster:admin/opendistro/ad/detector/validate'
- 'cluster:admin/opendistro/ad/detector/preview'
- 'cluster:admin/opendistro/ad/detectors/get'
- 'cluster:admin/opendistro/ad/result/topAnomalies'
```

### ad_read_write
This read-write access level grants full access to a detector except share.

Following actions are allowed with this access level:
```yaml
- "cluster:admin/opendistro/ad/*"
- 'cluster:monitor/*'
- "cluster:admin/ingest/pipeline/delete"
- "cluster:admin/ingest/pipeline/put"
```

### ad_full_access
This access level grants complete access to a detector and will allow shared user owner-like permission.

Following actions are allowed with this access level:
```yaml
- "cluster:admin/ingest/pipeline/delete"
- "cluster:admin/ingest/pipeline/put"
- "cluster:admin/opendistro/ad/*"
- 'cluster:monitor/*'
- "cluster:admin/security/resource/share"
```


> These access-levels are non-configurable. If you would like to add more access-levels, file an issue on [the GitHub repo](https://github.com/opensearch-project/anomaly-detection/).
{: .note } yellow

---

## Migrating from legacy framework

> **Admin-only:** The migrate API can only be run **by cluster administrators** (super-admins or rest-admins).
{: .important }

Once the feature is turned on, and the resource is marked as protected it is imperative that cluster-admins call the migrate API to migrate legacy-sharing information to the new framework:

### 3.3 clusters
```curl
POST _plugins/_security/api/resources/migrate
{
"source_index": ".opendistro-anomaly-detectors",
"username_path": "/user/name",
"backend_roles_path": "/user/backend_roles",
"default_access_level": "<pick-one-access-level>"
}
```
{% include copy-curl.html %}

### 3.4+ clusters

```curl
POST _plugins/_security/api/resources/migrate
{
"source_index": ".oopendistro-anomaly-detectors",
"username_path": "/user/name",
"backend_roles_path": "/user/backend_roles",
"default_owner": "<replace-with-existing-user>",
"default_access_level": {
"anomaly-detector": "<pick-one-access-level>"
}
}
```
{% include copy-curl.html %}
139 changes: 139 additions & 0 deletions _observing-your-data/forecast/forecaster-access-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
---
layout: default
title: Forecaster access control
parent: Forecasting
nav_order: 5
has_children: false
---

# Forecaster access control

**Status:** Experimental
**Replaces:** `plugins.forecast.filter_by_backend_roles`
{: .warning }

This page explains how the **Forecaster** resource integrates with the Security plugin’s **Resource Sharing and Access Control** framework to provide **document-level** authorization for forecasters.

> For the end-to-end framework concepts and APIs, see [Resource Sharing and Access Control]({{site.url}}{{site.baseurl}}/security/access-control/resources/)
{: .note}

---

## Onboarding

- **Resource type:** `forecaster`
- **System index:** `.opensearch-forecasters`
- **Onboarded in:** `3.3`

Check failure on line 26 in _observing-your-data/forecast/forecaster-access-control.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Onboarded. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Onboarded. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_observing-your-data/forecast/forecaster-access-control.md", "range": {"start": {"line": 26, "column": 5}}}, "severity": "ERROR"}

When resource-level authorization is enabled for this type, each forecaster’s visibility is governed by a central sharing record. Owners and users with share capability can grant or revoke access for specific **users**, **roles**, or **backend roles**.

---
## Enable or disable for this resource type

Add the type to the protected list and enable the feature.

> **Admin-only:** These settings can be configured **only by cluster administrators** (super-admins).
{: .important }

### `opensearch.yml` (3.3+)

```yaml
plugins.security.experimental.resource_sharing.enabled: true
plugins.security.system_indices.enabled: true
plugins.security.experimental.resource_sharing.protected_types:
- "forecaster"
````

### Dev Tools (3.4+)

```curl
PUT _cluster/settings
{
"transient": {
"plugins.security.experimental.resource_sharing.enabled": true,
"plugins.security.experimental.resource_sharing.protected_types": ["forecaster", <existing-resource-types>]
}
}
```
{% include copy-curl.html %}

---

## Forecaster access levels

There are **three access levels** for granting access to forecasters:

### forecast_read_only
This read-only access level grants a read and search only access to the shared forecaster.

Following actions are allowed with this access-level:
```yaml
- 'cluster:admin/plugin/forecast/forecaster/info'
- 'cluster:admin/plugin/forecast/forecaster/stats'
- 'cluster:admin/plugin/forecast/forecaster/suggest'
- 'cluster:admin/plugin/forecast/forecaster/validate'
- 'cluster:admin/plugin/forecast/forecasters/get'
- 'cluster:admin/plugin/forecast/forecasters/info'
- 'cluster:admin/plugin/forecast/result/topForecasts'
```

### forecast_read_write
This read-write access level grants full access to a forecaster except share.

Following actions are allowed with this access level:
```yaml
- 'cluster:admin/plugin/forecast/*'
- 'cluster:monitor/*'
- 'cluster:admin/settings/update'
```

### forecast_full_access
This access level grants complete access to a forecaster and will allow shared user owner-like permission.

Following actions are allowed with this access level:
```yaml
- 'cluster:admin/plugin/forecast/*'
- 'cluster:monitor/*'
- 'cluster:admin/settings/update'
- "cluster:admin/security/resource/share"
```

> These access-levels are non-configurable. If you would like to add more access-levels, file an issue on [the GitHub repo](https://github.com/opensearch-project/anomaly-detection/).
{: .note } yellow

---

## Migrating from legacy framework

> **Admin-only:** The migrate API can only be run **by cluster administrators** (super-admins or rest-admins).
{: .important }

Once the feature is turned on, and the resource is marked as protected it is imperative that cluster-admins call the migrate API to migrate legacy-sharing information to the new framework:

### 3.3 clusters
```curl
POST _plugins/_security/api/resources/migrate
{
"source_index": ".opensearch-forecasters",
"username_path": "/user/name",
"backend_roles_path": "/user/backend_roles",
"default_access_level": "<pick-one-access-level>"
}
```
{% include copy-curl.html %}

### 3.4+ clusters

```curl
POST _plugins/_security/api/resources/migrate
{
"source_index": ".opensearch-forecasters",
"username_path": "/user/name",
"backend_roles_path": "/user/backend_roles",
"default_owner": "<replace-with-existing-user>",
"default_access_level": {
"forecaster": "<pick-one-access-level>"
}
}
```
{% include copy-curl.html %}
Loading