API

Table of contents

  2. Reserved and hidden resources
    1. Get account details
  4. Action groups
    2. Get action groups
    4. Create action group
    6. Patch action groups
    1. Get user
    3. Delete user
    5. Patch user
  6. Roles
    2. Get roles
    4. Create role
    6. Patch roles
    1. Get role mapping
    3. Delete role mapping
    5. Patch role mapping
  8. Tenants
    2. Get tenants
    4. Create tenant
    6. Patch tenants
    1. Get configuration
    3. Patch configuration
    1. Get certificates
    3. Patch configuration
    1. Flush cache
    1. Health check

Just like OpenSearch permissions, you control access to the security plugin REST API using roles. Specify roles in :

These roles can now access all APIs. To prevent access to certain APIs:

  1. plugins.security.restapi.endpoints_disabled.<role>.<endpoint>: ["<method>", ...]

Possible values for endpoint are:

  • ACTIONGROUPS
  • ROLES
  • ROLESMAPPING
  • INTERNALUSERS
  • CONFIG
  • CACHE
  • LICENSE
  • SYSTEMINFO

Possible values for method are:

  • GET
  • PUT
  • POST
  • DELETE
  • PATCH

For example, the following configuration grants three roles access to the REST API, but then prevents test-role from making PUT, POST, DELETE, or PATCH requests to _plugins/_security/api/roles or _plugins/_security/api/internalusers:

  1. plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "test-role"]
  2. plugins.security.restapi.endpoints_disabled.test-role.ROLES: ["PUT", "POST", "DELETE", "PATCH"]
  3. plugins.security.restapi.endpoints_disabled.test-role.INTERNALUSERS: ["PUT", "POST", "DELETE", "PATCH"]

To use the PUT and PATCH methods for the , add the following line to opensearch.yml:

  1. plugins.security.unsupported.restapi.allow_securityconfig_modification: true

Reserved and hidden resources

You can mark users, role, role mappings, and action groups as reserved. Resources that have this flag set to true can’t be changed using the REST API or OpenSearch Dashboards.

To mark a resource as reserved, add the following flag:

  1. kibana_user:
  2.   reserved: true

Likewise, you can mark users, role, role mappings, and action groups as hidden. Resources that have this flag set to true are not returned by the REST API and not visible in OpenSearch Dashboards:

  1. kibana_user:
  2.   hidden: true

Hidden resources are automatically reserved.

To add or remove these flags, you need to modify plugins/opensearch-security/securityconfig/internal_users.yml and run plugins/opensearch-security/tools/securityadmin.sh.

Account

Returns account details for the current user. For example, if you sign the request as the admin user, the response includes details for that user.

Request

  1. GET _plugins/_security/api/account

Sample response

  1. {
  2.   "user_name": "admin",
  3.   "is_reserved": true,
  4.   "is_hidden": false,
  5.   "is_internal_user": true,
  6.   "user_requested_tenant": null,
  7.   "backend_roles": [
  8.     "admin"
  9.   ],
  10.   "custom_attribute_names": [],
  11.   "tenants": {
  12.     "global_tenant": true,
  13.     "admin_tenant": true,
  14.     "admin": true
  15.   },
  16.   "roles": [
  17.     "all_access",
  18.     "own_index"
  19.   ]
  20. }

Change password

Changes the password for the current user.

Request

  1. PUT _plugins/_security/api/account
  2. {
  3.     "current_password" : "old-password",
  4.     "password" : "new-password"
  5. }

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'test-user' updated."
  4. }

Action groups

Get action group

Retrieves one action group.

Request

  1. GET _plugins/_security/api/actiongroups/<action-group>

Sample response

  1. {
  2.   "custom_action_group": {
  3.     "reserved": false,
  4.     "hidden": false,
  5.       "kibana_all_read",
  6.       "indices:admin/aliases/get",
  7.       "indices:admin/aliases/exists"
  8.     ],
  9.     "description": "My custom action group",
  10.     "static": false
  11.   }
  12. }

Get action groups

Retrieves all action groups.

Request

  1. GET _plugins/_security/api/actiongroups/

Sample response

  1. {
  2.   "read": {
  3.     "reserved": true,
  4.     "hidden": false,
  5.     "allowed_actions": [
  6.       "indices:data/read*",
  7.       "indices:admin/mappings/fields/get*"
  8.     ],
  9.     "type": "index",
  10.     "description": "Allow all read operations",
  11.     "static": true
  12.   },
  13.   ...
  14. }

Delete action group

Request

  1. DELETE _plugins/_security/api/actiongroups/<action-group>

Sample response

  1. {
  2.   "status":"OK",
  3.   "message":"actiongroup SEARCH deleted."
  4. }

Create action group

Request

  1. PUT _plugins/_security/api/actiongroups/<action-group>
  2. {
  3.   "allowed_actions": [
  4.     "indices:data/write/index*",
  5.     "indices:data/write/update*",
  6.     "indices:admin/mapping/put",
  7.     "indices:data/write/bulk*",
  8.     "read",
  9.     "write"
  10.   ]
  11. }

Sample response

  1. {
  2.   "status": "CREATED",
  3.   "message": "'my-action-group' created."
  4. }

Patch action group

Updates individual attributes of an action group.

Request

  1. PATCH _plugins/_security/api/actiongroups/<action-group>
  2. [
  3.   {
  4.     "op": "replace", "path": "/allowed_actions", "value": ["indices:admin/create", "indices:admin/mapping/put"]
  5.   }
  6. ]

Sample response

  1. {
  2.   "status":"OK",
  3.   "message":"actiongroup SEARCH deleted."
  4. }

Patch action groups

Creates, updates, or deletes multiple action groups in a single call.

Request

  1. PATCH _plugins/_security/api/actiongroups
  2. [
  3.   {
  4.     "op": "add", "path": "/CREATE_INDEX", "value": { "allowed_actions": ["indices:admin/create", "indices:admin/mapping/put"] }
  5.   },
  6.   {
  7.     "op": "remove", "path": "/CRUD"
  8.   }
  9. ]

Sample response

  1. {
  2.   "status":"OK",
  3.   "message":"actiongroup SEARCH deleted."
  4. }

These calls let you create, update, and delete internal users. If you use an external authentication backend, you probably don’t need to worry about internal users.

Get user

Request

  1. GET _plugins/_security/api/internalusers/<username>

Sample response

  1. {
  2.   "kirk": {
  3.     "hash": "",
  4.     "roles": [ "captains", "starfleet" ],
  5.     "attributes": {
  6.        "attribute1": "value1",
  7.        "attribute2": "value2",
  8.     }
  9.   }
  10. }

Get users

Request

  1. GET _plugins/_security/api/internalusers/

Sample response

  1. {
  2.   "kirk": {
  3.     "hash": "",
  4.     "roles": [ "captains", "starfleet" ],
  5.     "attributes": {
  6.        "attribute1": "value1",
  7.        "attribute2": "value2",
  8.     }
  9.   }
  10. }

Delete user

Request

  1. DELETE _plugins/_security/api/internalusers/<username>

Sample response

  1. {
  2.   "status":"OK",
  3.   "message":"user kirk deleted."
  4. }

Create user

Creates or replaces the specified user. You must specify either password (plain text) or hash (the hashed user password). If you specify password, the security plugin automatically hashes the password before storing it.

Note that any role you supply in the opensearch_security_roles array must already exist for the security plugin to map the user to that role. To see predefined roles, refer to the list of predefined roles. For instructions on how to create a role, refer to .

Request

Sample response

  1. {
  2.   "status":"CREATED",
  3.   "message":"User kirk created"
  4. }

Patch user

Updates individual attributes of an internal user.

Request

  1. PATCH _plugins/_security/api/internalusers/<username>
  2. [
  3.   {
  4.     "op": "replace", "path": "/backend_roles", "value": ["klingons"]
  5.   },
  6.   {
  7.     "op": "replace", "path": "/opensearch_security_roles", "value": ["ship_manager"]
  8.   },
  9.   {
  10.     "op": "replace", "path": "/attributes", "value": { "newattribute": "newvalue" }
  11.   }
  12. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'kirk' updated."
  4. }

Creates, updates, or deletes multiple internal users in a single call.

Request

  1. PATCH _plugins/_security/api/internalusers
  2. [
  3.   {
  4.     "op": "add", "path": "/spock", "value": { "password": "testpassword1", "backend_roles": ["testrole1"] }
  5.   },
  6.   {
  7.     "op": "add", "path": "/worf", "value": { "password": "testpassword2", "backend_roles": ["testrole2"] }
  8.   },
  9.   {
  10.     "op": "remove", "path": "/riker"
  12. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Roles

Get role

Retrieves one role.

Request

  1. GET _plugins/_security/api/roles/<role>

Sample response

  1. {
  2.   "test-role": {
  3.     "reserved": false,
  4.     "hidden": false,
  5.     "cluster_permissions": [
  6.       "cluster_composite_ops",
  7.       "indices_monitor"
  8.     ],
  9.     "index_permissions": [{
  10.       "index_patterns": [
  11.         "movies*"
  12.       ],
  13.       "dls": "",
  14.       "fls": [],
  15.       "masked_fields": [],
  16.       "allowed_actions": [
  17.         "read"
  18.       ]
  19.     }],
  20.     "tenant_permissions": [{
  21.       "tenant_patterns": [
  22.         "human_resources"
  23.       ],
  24.       "allowed_actions": [
  25.         "kibana_all_read"
  26.       ]
  27.     }],
  28.     "static": false
  29.   }
  30. }

Get roles

Retrieves all roles.

Request

  1. GET _plugins/_security/api/roles/

Sample response

  1. {
  2.   "manage_snapshots": {
  3.     "reserved": true,
  4.     "hidden": false,
  5.     "description": "Provide the minimum permissions for managing snapshots",
  6.     "cluster_permissions": [
  7.       "manage_snapshots"
  8.     ],
  9.     "index_permissions": [{
  10.       "index_patterns": [
  11.         "*"
  12.       ],
  13.       "fls": [],
  14.       "masked_fields": [],
  15.       "allowed_actions": [
  16.         "indices:data/write/index",
  17.         "indices:admin/create"
  18.       ]
  19.     }],
  20.     "tenant_permissions": [],
  21.     "static": true
  22.   },
  23.   ...
  24. }

Delete role

Request

  1. DELETE _plugins/_security/api/roles/<role>

Sample response

  1. {
  2.   "status":"OK",
  3.   "message":"role test-role deleted."
  4. }

Create role

Creates or replaces the specified role.

Request

  1. PUT _plugins/_security/api/roles/<role>
  2. {
  3.   "cluster_permissions": [
  4.     "cluster_composite_ops",
  5.     "indices_monitor"
  6.   ],
  7.   "index_permissions": [{
  8.     "index_patterns": [
  9.       "movies*"
  10.     ],
  11.     "dls": "",
  12.     "fls": [],
  13.     "masked_fields": [],
  14.     "allowed_actions": [
  15.       "read"
  16.     ]
  17.   }],
  18.   "tenant_permissions": [{
  19.     "tenant_patterns": [
  20.       "human_resources"
  21.     ],
  22.     "allowed_actions": [
  23.       "kibana_all_read"
  24.     ]
  25.   }]
  26. }

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'test-role' updated."
  4. }

Patch role

Updates individual attributes of a role.

Request

  1. PATCH _plugins/_security/api/roles/<role>
  2. [
  3.   {
  4.     "op": "replace", "path": "/index_permissions/0/fls", "value": ["myfield1", "myfield2"]
  5.   },
  6.   {
  7.     "op": "remove", "path": "/index_permissions/0/dls"
  8.   }
  9. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'<role>' updated."
  4. }

Patch roles

Creates, updates, or deletes multiple roles in a single call.

Request

  1. PATCH _plugins/_security/api/roles
  2. [
  3.   {
  4.     "op": "replace", "path": "/role1/index_permissions/0/fls", "value": ["test1", "test2"]
  5.   },
  6.   {
  7.     "op": "remove", "path": "/role1/index_permissions/0/dls"
  8.   {
  9.     "op": "add", "path": "/role2/cluster_permissions", "value": ["manage_snapshots"]
  10.   }
  11. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Role mappings

Get role mapping

Retrieves one role mapping.

Request

  1. GET _plugins/_security/api/rolesmapping/<role>

Sample response

  1. {
  2.   "role_starfleet" : {
  3.     "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
  4.     "hosts" : [ "*.starfleetintranet.com" ],
  5.     "users" : [ "worf" ]
  6.   }
  7. }

Get role mappings

Retrieves all role mappings.

Request

  1. GET _plugins/_security/api/rolesmapping

Sample response

  1. {
  2.   "role_starfleet" : {
  3.     "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
  4.     "hosts" : [ "*.starfleetintranet.com" ],
  5.     "users" : [ "worf" ]
  6.   }
  7. }

Delete role mapping

Deletes the specified role mapping.

Request

  1. DELETE _plugins/_security/api/rolesmapping/<role>

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'my-role' deleted."
  4. }

Create role mapping

Request

  1. PUT _plugins/_security/api/rolesmapping/<role>
  2. {
  3.   "backend_roles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
  4.   "hosts" : [ "*.starfleetintranet.com" ],
  5.   "users" : [ "worf" ]
  6. }

Sample response

  1. {
  2.   "status": "CREATED",
  3.   "message": "'my-role' created."
  4. }

Patch role mapping

Updates individual attributes of a role mapping.

Request

  1. PATCH _plugins/_security/api/rolesmapping/<role>
  2. [
  3.   {
  4.     "op": "replace", "path": "/users", "value": ["myuser"]
  5.   },
  6.   {
  7.     "op": "replace", "path": "/backend_roles", "value": ["mybackendrole"]
  8.   }
  9. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'my-role' updated."
  4. }

Patch role mappings

Creates or updates multiple role mappings in a single call.

Request

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Tenants

Retrieves one tenant.

Request

  1. GET _plugins/_security/api/tenants/<tenant>

Sample response

  1. {
  2.   "human_resources": {
  3.     "reserved": false,
  4.     "hidden": false,
  5.     "description": "A tenant for the human resources team.",
  6.     "static": false
  7.   }

Get tenants

Retrieves all tenants.

Request

  1. GET _plugins/_security/api/tenants/

Sample response

  1. {
  2.   "global_tenant": {
  3.     "reserved": true,
  4.     "hidden": false,
  5.     "description": "Global tenant",
  6.     "static": true
  7.   },
  8.   "human_resources": {
  9.     "reserved": false,
  10.     "hidden": false,
  11.     "description": "A tenant for the human resources team.",
  12.     "static": false
  13.   }
  14. }

Delete tenant

Deletes the specified tenant.

Request

  1. DELETE _plugins/_security/api/tenants/<tenant>

Sample response

  1. {
  2.   "status":"OK",
  3.   "message":"tenant human_resources deleted."
  4. }

Create tenant

Creates or replaces the specified tenant.

Request

  1. PUT _plugins/_security/api/tenants/<tenant>
  2. {
  3.   "description": "A tenant for the human resources team."
  4. }

Sample response

  1. {
  2.   "status":"CREATED",
  3.   "message":"tenant human_resources created"
  4. }

Patch tenant

Add, delete, or modify a single tenant.

Request

  1. PATCH _plugins/_security/api/tenants/<tenant>
  2. [
  3.   {
  4.     "op": "replace", "path": "/description", "value": "An updated description"
  5.   }
  6. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Patch tenants

Add, delete, or modify multiple tenants in a single call.

Request

  1. PATCH _plugins/_security/api/tenants/
  2. [
  3.   {
  4.     "op": "replace",
  5.     "path": "/human_resources/description",
  6.     "value": "An updated description"
  7.   },
  8.   {
  9.     "op": "add",
  10.     "path": "/another_tenant",
  11.     "value": {
  12.       "description": "Another description."
  13.     }
  14.   }
  15. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Get configuration

Retrieves the current security plugin configuration in JSON format.

Request

  1. GET _plugins/_security/api/securityconfig

Update configuration

Creates or updates the existing configuration using the REST API. This operation can easily break your existing configuration, so we recommend using securityadmin.sh instead, which is far safer. See Access control for the API for how to enable this operation.

Request

  1. PUT _plugins/_security/api/securityconfig/config
  2. {
  3.   "dynamic": {
  4.     "filtered_alias_mode": "warn",
  5.     "disable_rest_auth": false,
  6.     "disable_intertransport_auth": false,
  7.     "respect_request_indices_options": false,
  8.     "opensearch-dashboards": {
  9.       "multitenancy_enabled": true,
  10.       "server_username": "kibanaserver",
  11.       "index": ".opensearch-dashboards"
  12.     },
  13.     "http": {
  14.       "anonymous_auth_enabled": false
  15.     },
  16.     "authc": {
  17.       "basic_internal_auth_domain": {
  18.         "http_enabled": true,
  19.         "transport_enabled": true,
  20.         "order": 0,
  21.         "http_authenticator": {
  22.           "challenge": true,
  23.           "type": "basic",
  24.           "config": {}
  25.         },
  26.         "authentication_backend": {
  27.           "type": "intern",
  28.           "config": {}
  29.         },
  30.         "description": "Authenticate via HTTP Basic against internal users database"
  31.       }
  32.     },
  33.     "auth_failure_listeners": {},
  34.     "do_not_fail_on_forbidden": false,
  35.     "multi_rolespan_enabled": true,
  36.     "hosts_resolver_mode": "ip-only",
  37.     "do_not_fail_on_forbidden_empty": false
  38.   }
  39. }

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'config' updated."
  4. }

Patch configuration

Updates the existing configuration using the REST API. This operation can easily break your existing configuration, so we recommend using securityadmin.sh instead, which is far safer. See Access control for the API for how to enable this operation.

Request

  1. PATCH _plugins/_security/api/securityconfig
  2. [
  3.   {
  4.     "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
  5.   }
  6. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Certificates

Get certificates

Retrieves the current security plugin configuration in JSON format.

Request

  1. GET _plugins/_security/api/securityconfig

Update configuration

Creates or updates the existing configuration using the REST API rather than securityadmin.sh. This operation can easily break your existing configuration, so we recommend using securityadmin.sh instead. See for how to enable this operation.

Request

  1. PUT _plugins/_security/api/securityconfig/config
  2. {
  3.   "dynamic": {
  4.     "filtered_alias_mode": "warn",
  5.     "disable_rest_auth": false,
  6.     "disable_intertransport_auth": false,
  7.     "respect_request_indices_options": false,
  8.     "opensearch-dashboards": {
  9.       "multitenancy_enabled": true,
  10.       "server_username": "kibanaserver",
  11.       "index": ".opensearch-dashboards"
  12.     },
  13.     "http": {
  14.       "anonymous_auth_enabled": false
  15.     },
  16.     "authc": {
  17.       "basic_internal_auth_domain": {
  18.         "http_enabled": true,
  19.         "transport_enabled": true,
  20.         "order": 0,
  21.         "http_authenticator": {
  22.           "challenge": true,
  23.           "type": "basic",
  24.           "config": {}
  25.         },
  26.         "authentication_backend": {
  27.           "type": "intern",
  28.           "config": {}
  29.         },
  30.         "description": "Authenticate via HTTP Basic against internal users database"
  31.       }
  32.     },
  33.     "auth_failure_listeners": {},
  34.     "do_not_fail_on_forbidden": false,
  35.     "multi_rolespan_enabled": true,
  36.     "hosts_resolver_mode": "ip-only",
  37.     "do_not_fail_on_forbidden_empty": false
  38.   }
  39. }

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "'config' updated."
  4. }

Patch configuration

Updates the existing configuration using the REST API rather than securityadmin.sh. This operation can easily break your existing configuration, so we recommend using securityadmin.sh instead. See for how to enable this operation.

Request

  1. PATCH _plugins/_security/api/securityconfig
  2. [
  3.   {
  4.     "op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
  5.   }
  6. ]

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Resource updated."
  4. }

Cache

Flush cache

Flushes the security plugin user, authentication, and authorization cache.

Request

  1. DELETE _plugins/_security/api/cache

Sample response

  1. {
  2.   "status": "OK",
  3.   "message": "Cache flushed successfully."
  4. }

Health

Request

  1. GET _plugins/_security/health

Sample response

  1. {
  2.   "message": null,
  3.   "mode": "strict",
  4.   "status": "UP"