Skip to content

Adds doc for using workflow and workflow-state with resource access control #11574

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 5 commits into
base: main
Choose a base branch
from
Draft

Adds doc for using workflow and workflow-state with resource access control #11574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a6a0c5d
Initial commit
DarshitChanpura Nov 20, 2025
98aedb9
Adds doc for workflow and workflow-state
DarshitChanpura Nov 21, 2025
cd2e9a8
Updates docs
DarshitChanpura Nov 21, 2025
cf764a1
Adds migration steps
DarshitChanpura Nov 21, 2025
baa359c
Add ntoe
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
134 changes: 134 additions & 0 deletions _automating-configurations/workflow-access-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
---
layout: default
title: Workflow access control
nav_order: 30
---

# Workflow access control

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

This page explains how **Flow Framework** integrates with the Security plugin’s **Resource Sharing and Access Control** framework to provide **document-level** authorization for **workflow state** records.

> 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:** `workflow`
- **System index:** `.plugins-flow-framework-templates`
- **Onboarded in:** `3.4`

Check failure on line 24 in _automating-configurations/workflow-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": "_automating-configurations/workflow-access-control.md", "range": {"start": {"line": 24, "column": 5}}}, "severity": "ERROR"}

When resource-level authorization is enabled for this type, each workflow’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.4+)

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

### Dev Tools (3.4+)

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

---

## Workflow access levels

Flow Framework exposes **three access levels** for workflow documents.

### workflow_read_only

This read-only access level grants a read and search only access to the shared workflow.

Following actions are allowed with this access-level:
```yaml
- "cluster:admin/opensearch/flow_framework/workflow/get"
- "cluster:admin/opensearch/flow_framework/workflow/search"
```

### workflow_read_write

This read-write access level grants full access to a workflow except share.

Following actions are allowed with this access-level:
```yaml
- "cluster:admin/opensearch/flow_framework/workflow/*"
- "cluster:monitor/*"
```

### workflow_full_access

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

Following actions are allowed with this access-level:
```yaml
- "cluster:admin/opensearch/flow_framework/workflow/*"
- "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/flow-framework/).
{: .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": ".plugins-flow-framework-templates",
"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": ".plugins-flow-framework-templates",
"username_path": "/user/name",
"backend_roles_path": "/user/backend_roles",
"default_owner": "<replace-with-existing-user>",
"default_access_level": {
"workflow": "<pick-one-access-level>"
}
}
```
{% include copy-curl.html %}
134 changes: 134 additions & 0 deletions _automating-configurations/workflow-state-access-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
---
layout: default
title: Workflow state access control
nav_order: 35
---

# Workflow state access control

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

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

> 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:** `workflow-state`
- **System index:** `.plugins-flow-framework-state`
- **Onboarded in:** `3.4`

Check failure on line 24 in _automating-configurations/workflow-state-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": "_automating-configurations/workflow-state-access-control.md", "range": {"start": {"line": 24, "column": 5}}}, "severity": "ERROR"}

When resource-level authorization is enabled for this type, each workflow-state’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.4+)

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

### Dev Tools (3.4+)

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

---

## Workflow state access levels

Flow Framework exposes **three access levels** for workflow states.

### workflow_state_read_only

This read-only access level grants a read and search only access to the shared workflow-state.

Following actions are allowed with this access-level:
```yaml
- "cluster:admin/opensearch/flow_framework/workflow_state/get"
- "cluster:admin/opensearch/flow_framework/workflow_state/search"
```

### workflow_state_read_write

This read-write access level grants full access to a workflow-state except share.

Following actions are allowed with this access-level:
```yaml
- "cluster:admin/opensearch/flow_framework/workflow_state/*"
- "cluster:monitor/*"
```

### workflow_state_full_access

This access level grants complete access to a workflow-state and will allow shared user owner-like permission.

Following actions are allowed with this access-level:
```yaml
- "cluster:admin/opensearch/flow_framework/workflow_state/*"
- "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/flow-framework/).
{: .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": ".plugins-flow-framework-state",
"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": ".plugins-flow-framework-state",
"username_path": "/user/name",
"backend_roles_path": "/user/backend_roles",
"default_owner": "<replace-with-existing-user>",
"default_access_level": {
"workflow-state": "<pick-one-access-level>"
}
}
```
{% include copy-curl.html %}
Loading