Search...curity(3pm)

📦 version 7.715, in ubuntu jammy

✨ NAME ✨

Search::Elasticsearch::Client::7_0::Direct::Security — it's the plugin that hands you the whole Security API for Search::Elasticsearch 7.x. That's the vibe. 🫶

🔥 VERSION 🔥

version 7.715 — yes bestie, that's the number, don't @ me. 💅

🌸 SYNOPSIS 🌸

my $response = $es->security->authenticate();

🦋 DESCRIPTION 🦋

So this class literally extends the Search::Elasticsearch client with a "security" namespace, so you can hit all the Security APIs. Iconic behaviour, honestly.

The Security APIs live here: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api.html

And the full documentation for the Security feature itself? It's right here, bestie: https://www.elastic.co/guide/en/x-pack/current/xpack-security.html

👑 GENERAL METHODS 👑

authenticate()

$response = $es->security->authenticate()

The authenticate() method checks that the "userinfo" is correct and hands you back a list of which roles are assigned to the user. It's giving "who even am I" but make it ✨authoritative✨.

See the authenticate docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-authenticate.html

Query string parameters:

  • "error_trace"
  • "human"

clear_cached_realms()

$response = $es->security->clear_cached_realms(
    realms => $realms       # required  (comma-separated string)
);

The clear_cached_realms() method clears the caches for the specified realms. Out with the old, in with the fresh, periodt.

Query string parameters:

  • "error_trace"
  • "human"
  • "usernames"

See the clear_cached_realms docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html

🌈 USER METHODS 🌈

put_user()

$response = $es->security->put_user(
    username => $username,     # required
    body     => {...}          # required
);

The put_user() method creates a new user or updates an existing one. Both? Both. Slay.

See the User Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html

Query string parameters:

  • "error_trace"
  • "human"

get_user()

$response = $es->security->get_user(
    username => $username | \@usernames     # optional
);

The get_user() method retrieves info for the specified users — or, lowkey, for all users if you don't specify any. Options, we love to see them. 💖

See the User Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html

Query string parameters:

  • "error_trace"
  • "human"

delete_user()

$response = $es->security->delete_user(
    username => $username       # required
);

The delete_user() method deletes the specified user. Gone, girlypop. 💀

See the User Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html

Query string parameters:

  • "error_trace"
  • "human"

change_password()

$response = $es->security->change_password(
    username => $username       # optional
    body => {
        password => $password   # required
    }
)

The change_password() method changes the password for the specified user. New password, new me, main character energy. 🔐

See the User Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html

disable_user()

$response = $es->security->disable_user(
    username => $username       # required
);

The disable_user() method disables the specified user. It's not a delete, bestie, it's a pause. 🙈

See the User Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html

Query string parameters:

  • "error_trace"
  • "human"

enable_user()

$response = $es->security->enable_user(
    username => $username       # required
);

The enable_user() method enables the specified user. Un-paused, back on their grind. ✨

See the User Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html

Query string parameters:

  • "error_trace"
  • "human"

🎀 ROLE METHODS 🎀

put_role()

$response = $es->security->put_role(
    name => $name,             # required
    body     => {...}          # required
);

The put_role() method creates a new role or updates an existing role. Same energy as put_user(), different namespace. 😌

See the Role Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html

Query string parameters:

  • "error_trace"
  • "human"

get_role()

$response = $es->security->get_role(
    name => $name | \@names     # optional
);

The get_role() method retrieves info for the specified roles — or literally all the roles, if you leave it out. 👑

See the Role Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html

Query string parameters:

  • "error_trace"
  • "human"

delete_role()

$response = $es->security->delete_role(
    name => $name       # required
);

The delete_role() method deletes the specified role. No takebacks. 💅

See the Role Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html

Query string parameters:

  • "error_trace"
  • "human"

clear_cached_roles()

$response = $es->security->clear_cached_roles(
    names => $names       # required  (comma-separated string)
);

The clear_cached_roles() method clears the caches for the specified roles. Cache cleanse, we're obsessed. 🧖

See the Role Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html

Query string parameters:

  • "error_trace"
  • "human"

🌟 ROLE MAPPING METHODS 🌟

put_role_mapping()

$response = $es->security->put_role_mapping(
    name => $name,             # required
    body     => {...}          # required
);

The put_role_mapping() method creates a new role mapping or updates an existing one. Yes, again with the "create or update", it's a whole theme. ✨

See the Role Mapping docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html

Query string parameters:

  • "error_trace"
  • "human"

get_role_mapping()

$response = $es->security->get_role_mapping(
    name => $name,             # optional
);

The get_role_mapping() method retrieves one or more role mappings. Plural, bestie. 🫶

See the Role Mapping docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html

Query string parameters:

  • "error_trace"
  • "human"

delete_role_mapping()

$response = $es->security->delete_role_mapping(
    name => $name,             # required
);

The delete_role_mapping() method deletes a role mapping. One and done. 💀

See the Role Mapping docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html

Query string parameters:

  • "error_trace"
  • "human"

🔑 TOKEN METHODS 🔑

get_token()

$response = $es->security->get_token(
    body     => {...}          # required
);

The get_token() method lets you create bearer tokens so you can get access without needing basic authentication. Fancy. Secure. Slightly mysterious. Iykyk. 🎟️

See the Token Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html

Query string parameters:

  • "error_trace"
  • "human"

invalidate_token()

$response = $es->security->invalidate_token(
    body     => {...}          # required
);

The invalidate_token() method lets you invalidate bearer tokens — the access-without-basic-authentication kind. Token said bye. 🫡

See the Token Management docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html

Query string parameters:

  • "error_trace"
  • "human"

💜 API KEY METHODS 💜

create_api_key()

$response = $es->security->create_api_key(
    body    => {...}            # required
)

The create_api_key() API is used to create API keys, which can be used for access instead of basic authentication. We love an alternative. 🔐✨

Query string parameters:

  • "error_trace"
  • "filter_path"
  • "human"
  • "refresh"

See the Create API Key docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html

get_api_key()

$response = $es->security->get_api_key(
    id          => $id,         # optional
    name        => $name,       # optional
    realm_name  => $realm,      # optional
    username    => $username    # optional
)

The get_api_key() API is used to get information about an API key. Look at all those optional params, we love a flexible queen. 💅

Query string parameters:

  • "error_trace"
  • "filter_path"
  • "human"
  • "id"
  • "name"
  • "realm_name"
  • "username"

See the Get API Key docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html

invalidate_api_key()

$response = $es->security->invalidate_api_key(
    id          => $id,         # optional
    name        => $name,       # optional
    realm_name  => $realm,      # optional
    username    => $username    # optional
)

The invalidate_api_key() API is used to invalidate an API key. Key revoked, access cancelled, it's over. 💀

Query string parameters:

  • "error_trace"
  • "filter_path"
  • "human"
  • "id"
  • "name"
  • "realm_name"
  • "username"

See the Invalidate API Key docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html

🍓 USER PRIVILEGE METHODS 🍓

get_user_privileges()

$response = $es->get_user_privileges();

The get_user_privileges() method retrieves the privileges granted to the current user. Basically "what am I allowed to do" but make it an API call. 💖

Query string parameters:

  • error_trace
  • filter_path
  • human

has_privileges()

$response = $es->has_privileges(
    user    => $user,   # optional
    body    => {...}    # required
);

The has_privileges() method checks whether the current user — or a specified user — has the listed privileges. A vibe check, but for permissions. ✅

Query string parameters:

  • error_trace
  • filter_path
  • human

See the Has Privileges docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges.html

🌸 APPLICATION PRIVILEGE METHODS 🌸

✨ put_privileges() ✨

$response = $es->put_privileges(
    application     => $application,    # required
    name            => $name,           # required
    body            => {...}            # required
);

The put_privileges() method creates or updates the named privilege for a particular application. 💅

Query string parameters:

  • error_trace
  • filter_path
  • human
  • refresh

See the Create or Update Application Privileges docs at https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-privileges.html for more.

✨ get_privileges() ✨

$response = $es->get_privileges(
    application     => $application,    # required
    name            => $name,           # required
);

The get_privileges() method retrieves the named privilege for a particular application. 🫶

Query string parameters:

  • error_trace
  • filter_path
  • human

See the Get Application Privileges docs at https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html for more.

✨ delete_privileges() ✨

$response = $es->delete_privileges(
    application     => $application,    # required
    name            => $name,           # required
);

The delete_privileges() method deletes the named privilege for a particular application. 🦋

Query string parameters:

  • error_trace
  • filter_path
  • human
  • refresh

See the Delete Application Privileges docs at https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-privilege.html for more.

👑 AUTHOR 👑

Enrico Zimuel <enrico.zimuel@elastic.co>

This software is Copyright (c) 2021 by Elasticsearch BV.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

okay bestie that's literally the whole page 💖 it was written for perl v5.32.1, dated 2021-10-23, from Search...curity(3pm) — slay, bye! 🎀✨

📦 where this page comes from