API

    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 configuration APIs, 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, modify config/opensearch-security/internal_users.yml and run plugins/opensearch-security/tools/securityadmin.sh.

    Account

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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.     "allowed_actions": [
    6.       "kibana_all_read",
    7.       "indices:admin/aliases/get",
    8.       "indices:admin/aliases/exists"
    9.     ],
    10.     "description": "My custom action group",
    11.     "static": false
    12.   }
    13. }

    Get action groups

    Introduced 1.0

    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

    Introduced 1.0

    Request

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

    Sample response

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

    Create action group

    Introduced 1.0

    Creates or replaces the specified 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.     "read",
    8.     "write"
    9.   ]
    10. }

    Sample response

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

    Patch action group

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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 opendistro_security_roles array must already exist for the security plugin to map the user to that role. To see predefined roles, refer to . For instructions on how to create a role, refer to creating a role.

    Request

    1. PUT _plugins/_security/api/internalusers/<username>
    2. {
    3.   "password": "kirkpass",
    4.   "opendistro_security_roles": ["maintenance_staff", "weapons"],
    5.   "backend_roles": ["captains", "starfleet"],
    6.   "attributes": {
    7.     "attribute1": "value1",
    8.     "attribute2": "value2"
    9.   }
    10. }

    Sample response

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

    Patch user

    Introduced 1.0

    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": "/opendistro_security_roles", "value": ["ship_manager"]
    8.   },
    9.   {
    10.     "op": "replace", "path": "/attributes", "value": { "newattribute": "newvalue" }
    11.   }
    12. ]

    Sample response

    Patch users

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    Request

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

    Sample response

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

    Create role

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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.   {
    10.     "op": "add", "path": "/role2/cluster_permissions", "value": ["manage_snapshots"]
    11.   }
    12. ]

    Sample response

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

    Role mappings

    Get role mapping

    Introduced 1.0

    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

    Introduced 1.0

    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.     "users" : [ "worf" ]
    5.   }
    6. }

    Delete role mapping

    Introduced 1.0

    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

    Introduced 1.0

    Creates or replaces the specified 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

    Introduced 1.0

    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

    Introduced 1.0

    Creates or updates multiple role mappings in a single call.

    Request

    1. PATCH _plugins/_security/api/rolesmapping
    2. [
    3.   {
    4.     "op": "add", "path": "/human_resources", "value": { "users": ["user1"], "backend_roles": ["backendrole2"] }
    5.   },
    6.   {
    7.     "op": "add", "path": "/finance", "value": { "users": ["user2"], "backend_roles": ["backendrole2"] }
    8.   }
    9. ]

    Sample response

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

    Tenants

    Get tenant

    Introduced 1.0

    Request

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

    Sample response

    1. {
    2.   "human_resources": {
    3.     "reserved": false,
    4.     "hidden": false,
    6.     "static": false
    7.   }
    8. }

    Get tenants

    Introduced 1.0

    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. }

    Introduced 1.0

    Deletes the specified tenant.

    Request

    Sample response

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

    Create tenant

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    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

    Introduced 1.0

    Retrieves the current security plugin configuration in JSON format.

    Request

    1. GET _plugins/_security/api/securityconfig

    Update configuration

    Introduced 1.0

    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 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

    Introduced 1.0

    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 for how to enable this operation.

    Before you can execute the operation, you must first add the following line to opensearch.yml:

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

    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. }

    Distinguished names

    These REST APIs let a super admin add, retrieve, update, or delete any distinguished names from an allow list to enable communication between clusters and/or nodes.

    Before you can use the REST API to configure the allow list, you must first add the following line to opensearch.yml:

    1. plugins.security.nodes_dn_dynamic_config_enabled: true

    Get distinguished names

    Retrieves all distinguished names in the allow list.

    Request

    1. GET _plugins/_security/api/nodesdn

    Sample response

    1. {
    2.   "cluster1": {
    3.     "nodes_dn": [
    4.       "CN=cluster1.example.com"
    5.     ]
    6.   }
    7. }

    To get the distinguished names from a specific cluster’s or node’s allow list, include the cluster’s name in the request path.

    Request

    1. GET _plugins/_security/api/nodesdn/<cluster-name>

    Sample response

    1. {
    2.   "cluster3": {
    3.     "nodes_dn": [
    4.       "CN=cluster3.example.com"
    5.     ]
    6.   }
    7. }

    Update distinguished names

    Adds or updates the specified distinguished names in the cluster’s or node’s allow list.

    Request

    1. PUT _plugins/_security/api/nodesdn/<cluster-name>
    2. {
    3.   "nodes_dn": [
    4.     "CN=cluster3.example.com"
    5.   ]
    6. }

    Sample response

    1. {
    2.   "status": "CREATED",
    3.   "message": "'cluster3' created."
    4. }

    Delete distinguished names

    Deletes all distinguished names in the specified cluster’s or node’s allow list.

    Request

    1. DELETE _plugins/_security/api/nodesdn/<cluster-name>

    Sample response

    1. {
    2.   "status": "OK",
    3.   "message": "'cluster3' deleted."
    4. }

    Certificates

    Get certificates

    Introduced 1.0

    Retrieves the cluster’s security certificates.

    Request

    1. GET _plugins/_security/api/ssl/certs

    Sample response

    1. {
    2.   "http_certificates_list": [
    3.     {
    4.       "issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com",
    5.       "subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de",
    6.       "san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]",
    7.       "not_before": "2018-04-22T03:43:47Z",
    8.       "not_after": "2028-04-19T03:43:47Z"
    9.     }
    10.   ],
    11.   "transport_certificates_list": [
    12.     {
    13.       "issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com",
    14.       "subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de",
    15.       "san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]",
    16.       "not_before": "2018-04-22T03:43:47Z",
    17.       "not_after": "2028-04-19T03:43:47Z"
    18.     }
    19.   ]
    20. }

    Reload certificates

    Introduced 1.0

    Reloads SSL certificates that are about to expire without restarting the OpenSearch node.

    This call assumes that new certificates are in the same location specified by the security configurations in opensearch.yml. To keep sensitive certificate reloads secure, this call only allows hot reload with certificates issued by the same issuer and subject DN and SAN with expiry dates after the current certificate.

    Request

    1. PUT _opendistro/_security/api/ssl/transport/reloadcerts
    2. PUT _opendistro/_security/api/ssl/http/reloadcerts

    Sample response

    1. { 
    2.   "message": "updated http certs" 
    3. }

    Cache

    Flush cache

    Introduced 1.0

    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 check

    Checks to see if the security plugin is up and running. If you operate your cluster behind a load balancer, this operation is useful for determining node health and doesn’t require a signed request.

    Request

    1. GET _plugins/_security/health

    Sample response

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