API

The Security plugin REST API lets you programmatically create and manage users, roles, role mappings, and action groups.


Table of contents

  1. Access control for the API
  2. Read-only and hidden resources
  3. Action groups
    1. Get action group
    2. Get action groups
    3. Delete action group
    4. Create action group
    5. Patch action group
    6. Patch action groups
  4. Users
    1. Get user
    2. Get users
    3. Delete user
    4. Create user
    5. Patch user
    6. Patch users
  5. Roles
    1. Get role
    2. Get roles
    3. Delete role
    4. Create role
    5. Patch role
    6. Patch roles
  6. Role mappings
    1. Get role mapping
    2. Get role mappings
    3. Delete role mapping
    4. Create role mapping
    5. Patch role mapping
    6. Patch role mappings
  7. Authentication
    1. Get authentication details
  8. Cache
    1. Flush cache
  9. Health
    1. Health check

Access control for the API

Just like Elasticsearch permissions, you control access to the Security plugin REST API using roles. Specify roles in elasticsearch.yml:

opendistro_security.restapi.roles_enabled: ["<role>", ...]

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

opendistro_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 line grants the my-role role access to the PUT, POST, and DELETE methods of the ROLES URIs.

opendistro_security.restapi.endpoints_disabled.my-role.ROLES: ["PUT", "POST", "DELETE"]

Read-only and hidden resources

You can mark users, role, role mappings, and action groups as read-only in their respective configuration files. Resources that have this flag set to true can’t be changed using the REST API and are marked as reserved in Kibana.

To mark a resource readonly, add the following flag:

kibana_user:
  readonly: 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 cannot be changed nor deleted:

kibana_user:
  hidden: true

Hidden resources are read-only by definition.

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


Action groups

Get action group

Retrieves one action group.

Request

GET _opendistro/_security/api/actiongroups/<action-group>

Sample response

{
  "SEARCH" : [ "indices:data/read/search*", "indices:data/read/msearch*", "SUGGEST" ]
}

Get action groups

Retrieves all action groups.

Request

GET _opendistro/_security/api/actiongroups/

Sample response

asdf

Delete action group

Request

DELETE _opendistro/_security/api/actiongroups/<action-group>

Sample response

{
  "status":"OK",
  "message":"actiongroup SEARCH deleted."
}

Create action group

Creates or replaces the specified action group.

Request

PUT _opendistro/_security/api/actiongroups/<action-group>
{
  "permissions": ["indices:data/read/search*", "indices:data/read/msearch*", "SUGGEST" ]
}

Sample response

{
  "status":"CREATED",
  "message":"action group SEARCH created"
}

Patch action group

Updates individual attributes of an action group.

Request

PATCH _opendistro/_security/api/actiongroups/<action-group>
[
  {
    "op": "replace", "path": "/permissions", "value": ["indices:admin/create", "indices:admin/mapping/put"]
  }
]

Sample response

{
  "status":"OK",
  "message":"actiongroup SEARCH deleted."
}

Patch action groups

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

Request

PATCH _opendistro/_security/api/actiongroups
[
  {
    "op": "add", "path": "/CREATE_INDEX", "value": ["indices:admin/create", "indices:admin/mapping/put"]
  },
  {
    "op": "delete", "path": "/CRUD"
  }
]

Sample response

{
  "status":"OK",
  "message":"actiongroup SEARCH deleted."
}

Users

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

GET _opendistro/_security/api/internalusers/<username>

Sample response

{
  "kirk": {
    "hash": "",
    "roles": [ "captains", "starfleet" ],
    "attributes": {
       "attribute1": "value1",
       "attribute2": "value2",
    }
  }
}

Get users

Request

GET _opendistro/_security/api/internalusers/

Sample response

{
  "kirk": {
    "hash": "",
    "roles": [ "captains", "starfleet" ],
    "attributes": {
       "attribute1": "value1",
       "attribute2": "value2",
    }
  }
}

Delete user

Request

DELETE _opendistro/_security/api/internalusers/<username>

Sample response

{
  "status":"OK",
  "message":"user kirk deleted."
}

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.

Request

PUT _opendistro/_security/api/internalusers/<username>
{
  "password": "kirk",
  "roles": ["captains", "starfleet"],
   "attributes": {
     "attribute1": "value1",
     "attribute2": "value2",       
   }
}

Sample response

{
  "status":"CREATED",
  "message":"User kirk created"
}

Patch user

Updates individual attributes of an internal user.

Request

PATCH _opendistro/_security/api/internalusers/<username>
[
  {
    "op": "replace", "path": "/roles", "value": ["klingons"]
  },
  {
    "op": "replace", "path": "/attributes", "value": {"newattribute": "newvalue"}
  }
]

Sample response

{
  "status":"CREATED",
  "message":"User kirk created"
}

Patch users

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

Request

PATCH _opendistro/_security/api/internalusers
[
  {
    "op": "add", "path": "/spock", "value": { "password": "testpassword1", "roles": ["testrole1"] }
  },
  {
    "op": "add", "path": "/worf", "value": { "password": "testpassword2", "roles": ["testrole2"] }
  },
  {
    "op": "delete", "path": "/riker"
  }
]

Sample response

{
  "status":"CREATED",
  "message":"User kirk created"
}

Roles

Get role

Retrieves one role.

Request

GET _opendistro/_security/api/roles/<role>

Sample response

{
  "role_starfleet" : {
    "indices" : {
      "pub*" : {
        "*" : [ "READ" ],
        "_dls_": "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"  }}}}",
        "_fls_": [
          "Designation",
          "FirstName",
          "LastName",
          "Salary"
        ]
      }
    }
  }
}

Get roles

Retrieves all roles.

Request

GET _opendistro/_security/api/roles/

Sample response

{
  "role_starfleet" : {
    "indices" : {
      "pub*" : {
        "*" : [ "READ" ],
        "_dls_": "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"  }}}}",
        "_fls_": [
          "Designation",
          "FirstName",
          "LastName",
          "Salary"
        ]
      }
    }
  }
}

Delete role

Request

DELETE _opendistro/_security/api/roles/<role>

Sample response

{
  "status":"OK",
  "message":"role role_starfleet deleted."
}

Create role

Creates or replaces the specified role.

Request

PUT _opendistro/_security/api/roles/<role>
{
  "cluster" : [ "*" ],
  "indices" : {
    "pub*" : {
      "*" : [ "READ" ],
      "_dls_": "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"}}}}",
      "_fls_": ["field1", "field2"]
    }
  },
  "tenants": {
    "tenant1": "RW",
    "tenant2": "RO"
  }  
}

Sample response

{
  "status":"OK",
  "message":"role role_starfleet created."
}

Patch role

Updates individual attributes of a role.

Request

PATCH _opendistro/_security/api/roles/<role>
[
  {
    "op": "replace", "path": "/indices/public/_fls_", "value": ["field1"]
  },
  {
    "op": "remove", "path": "/indices/public/_dls_"
  }   
]

Sample response

{
  "status":"OK",
  "message":"role role_starfleet created."
}

Patch roles

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

Request

PATCH _opendistro/_security/api/roles
[
  {
    "op": "add", "path": "/klingons",  "value": { "indices" : { "klingonindex" : { "*" : [ "READ" ] }  } }
  },
  {
    "op": "add", "path": "/romulans",  "value": { "indices" : { "romulansindex" : { "*" : [ "READ" ] }  } }
  }
]

Sample response

{
  "status":"OK",
  "message":"role role_starfleet created."
}

Role mappings

Get role mapping

Retrieves one role mapping.

Request

GET _opendistro/_security/api/rolesmapping/<role>

Sample response

{
  "role_starfleet" : {
    "backendroles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
    "hosts" : [ "*.starfleetintranet.com" ],
    "users" : [ "worf" ]
  }
}

Get role mappings

Retrieves all role mappings.

Request

GET _opendistro/_security/api/rolesmapping

Sample response

{
  "role_starfleet" : {
    "backendroles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
    "hosts" : [ "*.starfleetintranet.com" ],
    "users" : [ "worf" ]
  }
}

Delete role mapping

Request

DELETE _opendistro/_security/api/rolesmapping/<role>

Sample response

{
  "status": "OK",
  "message": "'my-role' deleted."
}

Create role mapping

Creates or replaces the specified role mapping.

Request

PUT _opendistro/_security/api/rolesmapping/<role>
{
  "backendroles" : [ "starfleet", "captains", "defectors", "cn=ldaprole,ou=groups,dc=example,dc=com" ],
  "hosts" : [ "*.starfleetintranet.com" ],
  "users" : [ "worf" ]
}

Sample response

{
  "status": "CREATED",
  "message": "'my-role' created."
}

Patch role mapping

Updates individual attributes of a role mapping.

Request

PATCH _opendistro/_security/api/rolesmapping/<role>
[
  {
    "op": "replace", "path": "/users", "value": ["myuser"]
  },
  {
    "op": "replace", "path": "/backendroles", "value": ["mybackendrole"]
  }
]

Sample response

{
  "status": "OK",
  "message": "'my-role' updated."
}

Patch role mappings

Creates or updates multiple role mappings in a single call.

Request

PATCH _opendistro/_security/api/rolesmapping
[
  {
    "op": "add", "path": "/human_resources", "value": { "users": ["user1"], "backendroles": ["backendrole2"] }
  },
  {
    "op": "add", "path": "/finance", "value": { "users": ["user2"], "backendroles": ["backendrole2"] }
  }
]

Sample response

{
  "status": "OK",
  "message": "Resource updated."
}

Authentication

Get authentication details

Request

GET _opendistro/_security/api/config

Cache

Flush cache

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

Request

DELETE _opendistro/_security/api/cache

Sample response

{
  "status": "OK",
  "message": "Cache flushed successfully."
}

Health

Health check

Checks to see if the Security plugin is up and running.

Request

GET _opendistro/_security/health

Sample response

{
  "message": null,
  "mode": "strict",
  "status": "UP"
}