Link Search Menu Expand Document Documentation Menu
Documentation

Notification access control

This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the OpenSearch forum.

Notifications integrates with the Security plugin’s resource sharing and access control framework to provide document-level authorization for notification configurations. A notification configuration is the underlying document for a channel, so sharing a configuration controls access to the corresponding channel. This replaces the legacy opensearch.notifications.general.filter_by_backend_roles setting with a more flexible sharing system that allows resource owners to grant specific access levels to users, roles, or backend roles.

For the end-to-end framework concepts and APIs, see Resource sharing and access control.

Resource configuration

The following table describes the notification configuration resource.

Field Value
Resource type notification_config
System index .opensearch-notifications-config
Onboarded version OpenSearch 3.8

When resource-level authorization is enabled, each notification configuration’s visibility is governed by a central sharing record. Resource owners and users with sharing capabilities can grant or revoke access permissions for specific users, roles, or backend roles.

Enable notification resource sharing

To enable resource sharing for notifications, add the notification configuration resource type to the protected types list and enable resource sharing cluster-wide.

Admin-only: These settings can be configured only by cluster administrators with superadmin privileges.

Configuration using opensearch.yml

Add the following settings to your opensearch.yml configuration file to enable resource sharing for notifications:

plugins.security.experimental.resource_sharing.enabled: true
plugins.security.system_indices.enabled: true
plugins.security.experimental.resource_sharing.protected_types:
  - "notification_config"

Configuration using the Cluster Settings API

Alternatively, you can enable resource sharing dynamically using the Cluster Settings API:

PUT _cluster/settings
{
  "transient": {
    "plugins.security.experimental.resource_sharing.enabled": true,
    "plugins.security.experimental.resource_sharing.protected_types": ["notification_config"]
  }
}

When adding the notification configuration resource type to an existing configuration, include all previously configured resource types in the protected_types array.

Notification access levels

Notifications provides three predefined access levels for notification configuration documents. These access levels determine the specific permissions granted to users who have been granted access to a notification configuration resource.

notifications_read_only

The notifications_read_only read-only access level grants users the ability to view shared notification configurations and channels but not modify them. This access level includes the following permissions:

- 'cluster:admin/opensearch/notifications/configs/get'
- 'cluster:admin/opensearch/notifications/channels/get'
- 'cluster:admin/opensearch/notifications/features'

notifications_read_write

The notifications_read_write read-write access level grants users full access to notification configuration operations except for sharing capabilities. This access level includes all read permissions plus write and send operations:

- 'cluster:admin/opensearch/notifications/configs/*'
- 'cluster:admin/opensearch/notifications/channels/get'
- 'cluster:admin/opensearch/notifications/features'
- 'cluster:admin/opensearch/notifications/feature/send'
- 'cluster:admin/opensearch/notifications/test_notification'

notifications_full_access

The notifications_full_access full access level grants users complete control over a notification configuration, including owner-like permissions such as sharing the resource with other users. This access level includes all notification operations plus resource sharing permissions:

- 'cluster:admin/opensearch/notifications/configs/*'
- 'cluster:admin/opensearch/notifications/channels/get'
- 'cluster:admin/opensearch/notifications/features'
- 'cluster:admin/opensearch/notifications/feature/send'
- 'cluster:admin/opensearch/notifications/test_notification'
- 'cluster:admin/security/resource/share'

These access levels are predefined and cannot be modified. To request additional access levels, create an issue in the Notifications GitHub repository.

Migrating from the legacy framework

After enabling resource sharing and marking the notification configuration resource type as protected, cluster administrators must run the migration API to transfer existing notification sharing information from the legacy framework to the new resource sharing system.

Admin-only: The Migrate API can only be executed by cluster administrators with superadmin or REST admin privileges.

Notification configuration documents track their authorized backend roles under metadata.access and do not store a per-user owner. Set backend_roles_path to /metadata/access. The username_path parameter is required and must be a non-empty path (an empty value is rejected), so point it at a field that notification documents do not contain, such as /metadata/owner. The path resolves to no value, and ownership falls back to default_owner.

Use the following API call to migrate legacy notification sharing data to the resource sharing framework:

POST _plugins/_security/api/resources/migrate
{
  "source_index": ".opensearch-notifications-config",
  "username_path": "/metadata/owner",
  "backend_roles_path": "/metadata/access",
  "default_owner": "<replace-with-existing-user>",
  "default_access_level": {
    "notification_config": "<select-appropriate-access-level>"
  }
}

Replace <replace-with-existing-user> with the username of an existing user who should own notification configurations. Because notification documents do not carry an owner name, every migrated configuration is attributed to this user. Replace <select-appropriate-access-level> with one of the available notification access levels: notifications_read_only, notifications_read_write, or notifications_full_access.

350 characters left

Have a question? .

Want to contribute? or .