Module: ElasticsearchServerless::API::Security::Actions

Defined in:
lib/elasticsearch-serverless/api/security/get_role.rb,
lib/elasticsearch-serverless/api/security/put_role.rb,
lib/elasticsearch-serverless/api/security/query_role.rb,
lib/elasticsearch-serverless/api/security/delete_role.rb,
lib/elasticsearch-serverless/api/security/get_api_key.rb,
lib/elasticsearch-serverless/api/security/authenticate.rb,
lib/elasticsearch-serverless/api/security/create_api_key.rb,
lib/elasticsearch-serverless/api/security/has_privileges.rb,
lib/elasticsearch-serverless/api/security/query_api_keys.rb,
lib/elasticsearch-serverless/api/security/update_api_key.rb,
lib/elasticsearch-serverless/api/security/invalidate_api_key.rb,
lib/elasticsearch-serverless/api/security/get_builtin_privileges.rb

Instance Method Summary collapse

Instance Method Details

#authenticate(arguments = {}) ⇒ Object

Authenticate a user. Authenticates a user and returns information about the authenticated user. Include the user information in a basic auth header. A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user. If the user cannot be authenticated, this API returns a 401 status code.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :headers (Hash) —

    Custom HTTP headers

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/elasticsearch-serverless/api/security/authenticate.rb', line 35

def authenticate(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.authenticate' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  method = ElasticsearchServerless::API::HTTP_GET
  path   = '_security/_authenticate'
  params = {}

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#create_api_key(arguments = {}) ⇒ Object

Create an API key. Create an API key for access without requiring basic authentication. IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error. A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys. The API keys are created by the Elasticsearch API key service, which is automatically enabled. To configure or turn off the API key service, refer to API key service setting documentation.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :refresh (String) —

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/elasticsearch-serverless/api/security/create_api_key.rb', line 41

def create_api_key(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.create_api_key' }

  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  method = ElasticsearchServerless::API::HTTP_PUT
  path   = '_security/api_key'
  params = Utils.process_params(arguments)

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#delete_role(arguments = {}) ⇒ Object

Delete roles. Delete roles in the native realm. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The delete roles API cannot remove roles that are defined in roles files.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :name (String) —

    The name of the role. (Required)

  • :refresh (String) —

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/elasticsearch-serverless/api/security/delete_role.rb', line 36

def delete_role(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.delete_role' }

  defined_params = [:name].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'name' missing" unless arguments[:name]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _name = arguments.delete(:name)

  method = ElasticsearchServerless::API::HTTP_DELETE
  path   = "_security/role/#{Utils.listify(_name)}"
  params = Utils.process_params(arguments)

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#get_api_key(arguments = {}) ⇒ Object

Get API key information. Retrieves information for one or more API keys. NOTE: If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. If you have read_security, manage_api_key or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    An API key id. This parameter cannot be used with any of name, realm_name or username.

  • :name (String) —

    An API key name. This parameter cannot be used with any of id, realm_name or username. It supports prefix search with wildcard.

  • :owner (Boolean) —

    A boolean flag that can be used to query API keys owned by the currently authenticated user. The realm_name or username parameters cannot be specified when this parameter is set to true as they are assumed to be the currently authenticated ones.

  • :realm_name (String) —

    The name of an authentication realm. This parameter cannot be used with either id or name or when owner flag is set to true.

  • :username (String) —

    The username of a user. This parameter cannot be used with either id or name or when owner flag is set to true.

  • :with_limited_by (Boolean) —

    Return the snapshot of the owner user’s role descriptors associated with the API key. An API key’s actual permission is the intersection of its assigned role descriptors and the owner user’s role descriptors.

  • :active_only (Boolean) —

    A boolean flag that can be used to query API keys that are currently active. An API key is considered active if it is neither invalidated, nor expired at query time. You can specify this together with other parameters such as owner or name. If active_only is false, the response will include both active and inactive (expired or invalidated) keys.

  • :with_profile_uid (Boolean) —

    Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.

  • :headers (Hash) —

    Custom HTTP headers

See Also:



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/elasticsearch-serverless/api/security/get_api_key.rb', line 51

def get_api_key(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.get_api_key' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  method = ElasticsearchServerless::API::HTTP_GET
  path   = '_security/api_key'
  params = Utils.process_params(arguments)

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#get_builtin_privileges(arguments = {}) ⇒ Object

Get builtin privileges. Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :headers (Hash) —

    Custom HTTP headers

See Also:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/elasticsearch-serverless/api/security/get_builtin_privileges.rb', line 32

def get_builtin_privileges(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.get_builtin_privileges' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  method = ElasticsearchServerless::API::HTTP_GET
  path   = '_security/privilege/_builtin'
  params = {}

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#get_role(arguments = {}) ⇒ Object

Get roles. Get roles in the native realm. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The get roles API cannot retrieve roles that are defined in roles files.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :name (String, Array<String>) —

    The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.

  • :headers (Hash) —

    Custom HTTP headers

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/elasticsearch-serverless/api/security/get_role.rb', line 37

def get_role(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.get_role' }

  defined_params = [:name].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = nil

  _name = arguments.delete(:name)

  method = ElasticsearchServerless::API::HTTP_GET
  path   = if _name
             "_security/role/#{Utils.listify(_name)}"
           else
             '_security/role'
           end
  params = Utils.process_params(arguments)

  if Array(arguments[:ignore]).include?(404)
    Utils.rescue_from_not_found do
      ElasticsearchServerless::API::Response.new(
        perform_request(method, path, params, body, headers, request_opts)
      )
    end
  else
    ElasticsearchServerless::API::Response.new(
      perform_request(method, path, params, body, headers, request_opts)
    )
  end
end

#has_privileges(arguments = {}) ⇒ Object

Check user privileges. Determine whether the specified user has a specified list of privileges. All users can use this API, but only to determine their own privileges. To check the privileges of other users, you must use the run as feature.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :user (String) —

    Username

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/elasticsearch-serverless/api/security/has_privileges.rb', line 36

def has_privileges(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.has_privileges' }

  defined_params = [:user].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  _user = arguments.delete(:user)

  method = ElasticsearchServerless::API::HTTP_POST
  path   = if _user
             "_security/user/#{Utils.listify(_user)}/_has_privileges"
           else
             '_security/user/_has_privileges'
           end
  params = {}

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#invalidate_api_key(arguments = {}) ⇒ Object

Invalidate API keys. This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted. To use this API, you must have at least the manage_security, manage_api_key, or manage_own_api_key cluster privileges. The manage_security privilege allows deleting any API key, including both REST and cross cluster API keys. The manage_api_key privilege allows deleting any REST API key, but not cross cluster API keys. The manage_own_api_key only allows deleting REST API keys that are owned by the user. In addition, with the manage_own_api_key privilege, an invalidation request must be issued in one of the three formats:

  • Set the parameter owner=true.

  • Or, set both username and realm_name to match the user’s identity.

  • Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the ids field.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/elasticsearch-serverless/api/security/invalidate_api_key.rb', line 42

def invalidate_api_key(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.invalidate_api_key' }

  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  method = ElasticsearchServerless::API::HTTP_DELETE
  path   = '_security/api_key'
  params = {}

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#put_role(arguments = {}) ⇒ Object

Create or update roles. The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. The create or update roles API cannot update roles that are defined in roles files. File-based role management is not available in Elastic Serverless.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :name (String) —

    The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only contain letters, digits and the characters ‘_’, ‘-’, and ‘.’. Each role must have a unique name, as this will serve as the identifier for that role. (Required)

  • :refresh (String) —

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/elasticsearch-serverless/api/security/put_role.rb', line 37

def put_role(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.put_role' }

  defined_params = [:name].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  raise ArgumentError, "Required argument 'name' missing" unless arguments[:name]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  _name = arguments.delete(:name)

  method = ElasticsearchServerless::API::HTTP_PUT
  path   = "_security/role/#{Utils.listify(_name)}"
  params = Utils.process_params(arguments)

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#query_api_keys(arguments = {}) ⇒ Object

Find API keys with a query. Get a paginated list of API keys and their information. You can optionally filter the results with a query. To use this API, you must have at least the manage_own_api_key or the read_security cluster privileges. If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. If you have the read_security, manage_api_key, or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :with_limited_by (Boolean) —

    Return the snapshot of the owner user’s role descriptors associated with the API key. An API key’s actual permission is the intersection of its assigned role descriptors and the owner user’s role descriptors (effectively limited by it). An API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has manage_api_key or higher privileges.

  • :with_profile_uid (Boolean) —

    Determines whether to also retrieve the profile UID for the API key owner principal. If it exists, the profile UID is returned under the profile_uid response field for each API key.

  • :typed_keys (Boolean) —

    Determines whether aggregation names are prefixed by their respective types in the response.

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

See Also:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/elasticsearch-serverless/api/security/query_api_keys.rb', line 43

def query_api_keys(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.query_api_keys' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  method = if body
             ElasticsearchServerless::API::HTTP_POST
           else
             ElasticsearchServerless::API::HTTP_GET
           end

  path   = '_security/_query/api_key'
  params = Utils.process_params(arguments)

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#query_role(arguments = {}) ⇒ Object

Find roles with a query. Get roles in a paginated manner. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. You can optionally filter the results with a query. Also, the results can be paginated and sorted.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/elasticsearch-serverless/api/security/query_role.rb', line 37

def query_role(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.query_role' }

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  method = if body
             ElasticsearchServerless::API::HTTP_POST
           else
             ElasticsearchServerless::API::HTTP_GET
           end

  path   = '_security/_query/role'
  params = {}

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#update_api_key(arguments = {}) ⇒ Object

Update an API key. Update attributes of an existing API key. This API supports updates to an API key’s access scope, expiration, and metadata. To use this API, you must have at least the manage_own_api_key cluster privilege. Users can only update API keys that they created or that were granted to them. To update another user’s API key, use the run_as feature to submit a request on behalf of another user. IMPORTANT: It’s not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required. Use this API to update API keys created by the create API key or grant API Key APIs. If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead. It’s not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API. The access scope of an API key is derived from the role_descriptors you specify in the request and a snapshot of the owner user’s permissions at the time of the request. The snapshot of the owner’s permissions is updated automatically on every call. IMPORTANT: If you don’t specify role_descriptors in the request, a call to this API might still change the API key’s access scope. This change can occur if the owner user’s permissions have changed since the API key was created or last modified.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The ID of the API key to update. (Required)

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/elasticsearch-serverless/api/security/update_api_key.rb', line 46

def update_api_key(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'security.update_api_key' }

  defined_params = [:id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  _id = arguments.delete(:id)

  method = ElasticsearchServerless::API::HTTP_PUT
  path   = "_security/api_key/#{Utils.listify(_id)}"
  params = {}

  ElasticsearchServerless::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end