elasticsearch-authz

What this skill does

# Elasticsearch Authorization

Manage Elasticsearch role-based access control: native users, roles, role assignment, and role mappings for external
realms.

For authentication methods and API key management, see the **elasticsearch-authn** skill.

For detailed API endpoints, see [references/api-reference.md](references/api-reference.md).

> **Deployment note:** Feature availability differs between self-managed, ECH, and Serverless. See
> [Deployment Compatibility](#deployment-compatibility) for details.

## Jobs to Be Done

- Create a native user with a specific set of privileges
- Define a custom role with least-privilege index and cluster access
- Assign one or more roles to an existing user
- Create a role with Kibana feature or space privileges
- Configure a role mapping for external realm users (SAML, LDAP, PKI)
- Derive role assignments dynamically from user attributes (Mustache templates)
- Restrict document visibility per user or department (document-level security)
- Hide sensitive fields like PII from certain roles (field-level security)
- Implement attribute-based access control (ABAC) using templated role queries
- Translate a natural-language access request into user, role, and role mapping tasks

## Prerequisites

| Item                   | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| **Elasticsearch URL**  | Cluster endpoint (e.g. `https://localhost:9200` or a Cloud deployment URL) |
| **Kibana URL**         | Required only when setting Kibana feature/space privileges                 |
| **Authentication**     | Valid credentials (see the elasticsearch-authn skill)                      |
| **Cluster privileges** | `manage_security` is required for user and role management operations      |

Prompt the user for any missing values.

## Decomposing Access Requests

When the user describes access in natural language (e.g. "create a user that has read-only access to `logs-*`"), break
the request into discrete tasks before executing. Follow this workflow:

### Step 1 — Identify the components

Extract from the prompt:

| Component        | Question to answer                                                        |
| ---------------- | ------------------------------------------------------------------------- |
| **Who**          | New native user, existing user, or external realm user (LDAP, SAML, etc.) |
| **What**         | Which indices, data streams, or Kibana features                           |
| **Access level** | Read, write, manage, or a specific set of privileges                      |
| **Scope**        | All documents/fields, or restricted by region, department, sensitivity?   |
| **Kibana?**      | Does the request mention any Kibana feature (dashboards, Discover, etc.)  |
| **Deployment?**  | Self-managed, ECH, or Serverless? Serverless has a different user model.  |

### Step 2 — Check for existing roles

Before creating a new role, check if an existing role already grants the required access:

```bash
curl "${ELASTICSEARCH_URL}/_security/role" <auth_flags>
```

If a matching role exists, skip role creation and reuse it.

### Step 3 — Create the role (if needed)

Derive a role name and display name from the request. Use the Elasticsearch API for pure index/cluster roles. Use the
Kibana API if Kibana features are involved (see [Choosing the right API](#choosing-the-right-api)).

### Step 4 — Create or update the user

| Scenario                 | Action                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **New native user**      | Create the user with the role and a strong generated password. (Self-managed / ECH only.)                                            |
| **Existing native user** | Fetch current roles, append the new role, update the user with the full array. (Self-managed / ECH only.)                            |
| **External realm user**  | Create a role mapping that matches the user's realm attributes to the role. (Self-managed / ECH only.)                               |
| **Serverless user**      | Use the **cloud-access-management** skill. Assign a predefined role or create a custom role first, then assign it via the Cloud API. |

### Example decomposition

**Prompt:** "Create a user `analyst` with read-only access to `logs-*` and `metrics-*` and view dashboards in Kibana."

1. Identify: new user `analyst`, indices `logs-*`/`metrics-*`, dashboards, read access.
1. Check roles: `GET /_security/role` — no match.
1. Create role via Kibana API (dashboards involved): `logs-metrics-dashboard-viewer`.
1. Create user: `POST /_security/user/analyst` with `roles: ["logs-metrics-dashboard-viewer"]`.

Confirm each step with the user if the request is ambiguous.

## Manage Native Users

> Native user management applies to self-managed and ECH deployments. On Serverless, users are managed at the
> organization level — skip this section.

### Create a user

```bash
curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "password": "'"${PASSWORD}"'",
    "roles": ["'"${ROLE_NAME}"'"],
    "full_name": "'"${FULL_NAME}"'",
    "email": "'"${EMAIL}"'",
    "enabled": true
  }'
```

### Update a user

Use `PUT /_security/user/${USERNAME}` with the fields to change. Omit `password` to keep the existing one.

### Other user operations

```bash
curl -X POST "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_password" \
  <auth_flags> -H "Content-Type: application/json" \
  -d '{"password": "'"${NEW_PASSWORD}"'"}'
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_disable" <auth_flags>
curl -X PUT "${ELASTICSEARCH_URL}/_security/user/${USERNAME}/_enable" <auth_flags>
curl "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>
curl -X DELETE "${ELASTICSEARCH_URL}/_security/user/${USERNAME}" <auth_flags>
```

## Manage Roles

### Choosing the right API

Use the **Elasticsearch API** (`PUT /_security/role/{name}`) when the role only needs `cluster` and `indices`
privileges. This is the default — no Kibana endpoint is required.

Use the **Kibana role API** (`PUT /api/security/role/{name}`) when the role includes any Kibana feature or space
privileges. The Elasticsearch API cannot set Kibana feature grants, space scoping, or base privileges, so if the user
mentions Kibana features like Discover, Dashboards, Maps, Visualize, Canvas, or any other Kibana application, the Kibana
API is required.

If the Kibana endpoint is not available or API key authentication to Kibana fails, fall back to the Elasticsearch API
for the `cluster` and `indices` portion and warn the user that Kibana privileges could not be set. Prompt for a Kibana
URL or alternative credentials before giving up.

### Create or update a role (Elasticsearch API)

Default choice when the role has only index and cluster privileges:

```bash
curl -X PUT "${ELASTICSEARCH_URL}/_security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "cluster": [],
    "indices": [
      {
        "names": ["'"${INDEX_PATTERN}"'"],
        "privileges": ["read", "view_index_metadata"]
      }
    ]
  }'
```

### Create or update a role (Kibana API)

Required when the role includes Kibana feature or space privileges:

```bash
curl -X PUT "${KIBANA_URL}/api/security/role/${ROLE_NAME}" \
  <auth_flags> \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "'"${ROLE_DISPLAY_NAME}"'",
    "elasticsearch": {
      "cluster": [],
      "indices": [
        {
          "names": ["'"${INDEX_PATTERN}"'"],
          "p