From 60a9b3bf8a6cd6beed50b0854a18c730ca0f48e6 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Wed, 19 Feb 2025 08:21:11 -0600 Subject: [PATCH] Update security parameter descriptions (#819) * Update Security API descriptions. Signed-off-by: Archer * Update unique descriptions. Signed-off-by: Archer * Fix the linting error. Signed-off-by: Archer * Fix validation error Signed-off-by: Archer * Another validation error attempt. Signed-off-by: Archer * Apply suggestions from code review Co-authored-by: Craig Perkins Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Fix query language Signed-off-by: Archer * Make descriptions consistent> Signed-off-by: Archer * Update operations groups to have different definitions Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Fix validation error Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Archer Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Craig Perkins --- spec/namespaces/security.yaml | 168 +++++++++++++++-------------- spec/schemas/security._common.yaml | 95 ++++++++-------- 2 files changed, 133 insertions(+), 130 deletions(-) diff --git a/spec/namespaces/security.yaml b/spec/namespaces/security.yaml index 73f744878..8e9a0b76a 100644 --- a/spec/namespaces/security.yaml +++ b/spec/namespaces/security.yaml @@ -9,7 +9,7 @@ paths: operationId: security.get_sslinfo.0 x-operation-group: security.get_sslinfo x-version-added: '1.0' - description: Retrieves the SSL configuration information. + description: Retrieves information about the SSL configuration. parameters: - $ref: '#/components/parameters/security.get_sslinfo::query.show_dn' responses: @@ -25,7 +25,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Returns the authentication information. + description: Returns or updates authentication information for the currently authenticated user. parameters: - $ref: '#/components/parameters/security.authinfo::query.auth_type' - $ref: '#/components/parameters/security.authinfo::query.verbose' @@ -41,7 +41,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Returns the authentication information. + description: Returns or updates authentication information for the currently authenticated user. parameters: - $ref: '#/components/parameters/security.authinfo::query.auth_type' - $ref: '#/components/parameters/security.authinfo::query.verbose' @@ -58,7 +58,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves the current security-dashboards plugin configuration. + description: Retrieves the current values for dynamic security settings for OpenSearch Dashboards. responses: '200': $ref: '#/components/responses/security.get_dashboards_info@200' @@ -71,7 +71,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates the current security-dashboards plugin configuration. + description: Retrieves the current values for dynamic security settings for OpenSearch Dashboards. responses: '200': $ref: '#/components/responses/security.post_dashboards_info@200' @@ -85,7 +85,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Checks to see if the Security plugin is up and running. + description: Checks to see if the Security plugin is running. parameters: - $ref: '#/components/parameters/security.health::query.mode' externalDocs: @@ -100,7 +100,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Checks to see if the Security plugin is up and running. + description: Checks to see if the Security plugin is running. parameters: - $ref: '#/components/parameters/security.health::query.mode' externalDocs: @@ -116,7 +116,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves the tenant names if any exist. Only accessible to super admins or kibanaserver user. + description: Retrieves the names of current tenants. Requires super admin or `kibanaserver` permissions. responses: '200': $ref: '#/components/responses/security.tenant_info@200' @@ -131,7 +131,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves the tenant names if any exist. Only accessible to super admins or kibanaserver user. + description: Retrieves the names of current tenants. Requires super admin or `kibanaserver` permissions. responses: '200': $ref: '#/components/responses/security.tenant_info@200' @@ -147,7 +147,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Gets the user identity related information for currently logged in user. + description: Gets the identity information for the user currently logged in. responses: '200': $ref: '#/components/responses/security.who_am_i@200' @@ -160,7 +160,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Gets the user identity related information for currently logged in user. + description: Gets the identity information for the user currently logged in. responses: '200': $ref: '#/components/responses/security.who_am_i@200' @@ -174,7 +174,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Gets the user identity related information for currently logged in user. User needs to have access to this endpoint when authorization at REST layer is enabled. + description: Gets the identity information for the user currently logged in. To use this operation, you must have access to this endpoint when authorization at REST layer is enabled. responses: '200': $ref: '#/components/responses/security.who_am_i_protected@200' @@ -188,7 +188,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Check whether or not an upgrade can be performed and what resources can be updated. + description: Checks whether or not an upgrade can be performed and which security resources can be updated. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#configuration-upgrade-check responses: @@ -202,7 +202,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Helps cluster operator upgrade missing defaults and stale default definitions. + description: Assists the cluster operator with upgrading missing default values and stale default definitions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#configuration-upgrade requestBody: @@ -220,7 +220,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Returns account details for the current user. + description: Returns account information for the current user. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-account-details responses: @@ -264,7 +264,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Creates, updates, or deletes multiple action groups in a single call. + description: Creates, updates, or deletes multiple action groups in a single request. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-action-groups requestBody: @@ -314,7 +314,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates individual attributes of an action group. + description: Updates the individual attributes of an action group. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-action-group parameters: @@ -331,7 +331,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Delete a specified action group. + description: Deletes the specified action group. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#delete-action-group parameters: @@ -347,7 +347,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves the current list of allowed API accessible to normal user. + description: Retrieves the current list of allowed APIs accessible to a normal user. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#access-control-for-the-api responses: @@ -362,7 +362,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Creates or replaces the permitted APIs. Accessible using Super Admin certificate or REST API permission. + description: Creates or replaces APIs permitted for users on the allow list. Requires a super admin certificate or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#access-control-for-the-api requestBody: @@ -379,7 +379,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates the current list of allowed API accessible to normal user. + description: Updates the current list of APIs accessible for users on the allow list. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#access-control-for-the-api requestBody: @@ -410,7 +410,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: A PATCH call is used to update specified fields in the audit configuration. + description: Updates the specified fields in the audit configuration. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#audit-logs requestBody: @@ -442,7 +442,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Returns the authorization token. + description: Returns the authorization token for the current user. responses: '200': $ref: '#/components/responses/security.authtoken@200' @@ -455,7 +455,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Not supported for cache API. + description: Not supported for the Cache API. responses: '501': $ref: '#/components/responses/security.cache@501' @@ -467,7 +467,7 @@ paths: - amazon-managed - amazon-serverless x-ignorable: true - description: Not supported for cache API. + description: Not supported for the Cache API. responses: '501': $ref: '#/components/responses/security.cache@501' @@ -479,7 +479,7 @@ paths: - amazon-managed - amazon-serverless x-ignorable: true - description: Not supported for cache API. + description: Not supported for the Cache API. responses: '501': $ref: '#/components/responses/security.cache@501' @@ -490,7 +490,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Flushes the Security plugin user, authentication, and authorization cache. + description: Flushes the Security plugin's user, authentication, and authorization cache. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#flush-cache responses: @@ -523,7 +523,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves the given node's security certificates. + description: Retrieves the specified node's security certificates. parameters: - $ref: '#/components/parameters/security.get_node_certificates::path.node_id' - $ref: '#/components/parameters/security.get_node_certificates::query.cert_type' @@ -543,7 +543,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Generates On-Behalf-Of token for the current user. + description: Generates a `On-Behalf-Of` token for the current user. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/authentication-tokens/#api-endpoint requestBody: @@ -574,7 +574,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Creates, updates, or deletes multiple internal users in a single call. + description: Creates, updates, or deletes multiple internal users in a single request. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-users requestBody: @@ -590,7 +590,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieve one internal user. + description: Retrieve information about the specified internal user. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-user parameters: @@ -624,7 +624,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates individual attributes of an internal user. + description: Updates individual attributes for an internal user. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-user parameters: @@ -641,7 +641,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Delete the specified user. + description: Deletes the specified internal user. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#delete-user parameters: @@ -657,7 +657,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Generates authorization token for the given user. + description: Generates an authorization token for the specified user. parameters: - $ref: '#/components/parameters/security.generate_user_token::path.username' responses: @@ -673,7 +673,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Migrates security configuration from v6 to v7. + description: Migrates the security configuration from v6 to v7. responses: '200': $ref: '#/components/responses/security.migrate@200' @@ -687,7 +687,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves distinguished names. Only accessible to super-admins and with rest-api permissions when enabled. + description: Retrieves all node distinguished names. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-distinguished-names parameters: @@ -706,7 +706,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Bulk update of distinguished names. Only accessible to super-admins and with rest-api permissions when enabled. + description: Bulk updates specified node distinguished names. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#update-all-distinguished-names requestBody: @@ -726,7 +726,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves distinguished names. Only accessible to super-admins and with rest-api permissions when enabled. + description: Retrieves all node distinguished names. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-distinguished-names parameters: @@ -746,7 +746,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Adds or updates the specified distinguished names in the cluster or node allow list. Only accessible to super-admins and with rest-api permissions when enabled. + description: Adds or updates the specified distinguished names in the cluster or node allowlist. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#update-distinguished-names parameters: @@ -769,7 +769,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates a distinguished cluster name for a specific cluster. Only accessible to super-admins and with rest-api permissions when enabled. + description: Updates the distinguished cluster name for the specified cluster. Requires super admin or REST API permissions. parameters: - $ref: '#/components/parameters/security.patch_distinguished_name::path.cluster_name' requestBody: @@ -788,7 +788,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Deletes all distinguished names in the specified cluster or node allow list. Only accessible to super-admins and with rest-api permissions when enabled. + description: Deletes all distinguished names in the specified cluster or node allowlist. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#delete-distinguished-names parameters: @@ -808,7 +808,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Gets the evaluated REST API permissions for the currently logged in user. + description: Retrieves the evaluated REST API permissions for the currently logged in user. responses: '200': $ref: '#/components/responses/security.get_permissions_info@200' @@ -887,7 +887,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates individual attributes of a role. + description: Updates the individual attributes of a role. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-role parameters: @@ -906,7 +906,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Delete the specified role. + description: Deletes the specified role. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#delete-role parameters: @@ -935,7 +935,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Creates or updates multiple role mappings in a single call. + description: Creates or updates multiple role mappings in a single request. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-role-mappings requestBody: @@ -953,7 +953,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves one role mapping. + description: Retrieves the specified role mapping. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-role-mapping parameters: @@ -987,7 +987,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Updates individual attributes of a role mapping. + description: Updates the individual attributes of a role mapping. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-role-mapping parameters: @@ -1022,7 +1022,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Returns the current Security plugin configuration in JSON format. + description: Returns the current Security plugin configuration in a JSON format. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-configuration responses: @@ -1035,7 +1035,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: A `PATCH` call is used to update the existing configuration using the REST API. Only accessible by admins and users with REST API access and only when put or patch is enabled. + description: Updates the existing security configuration using the REST API. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-configuration requestBody: @@ -1053,7 +1053,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Adds or updates the existing configuration using the REST API. Only accessible by admins and users with REST API access and only when put or patch is enabled. + description: Updates the settings for an existing security configuration. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#update-configuration requestBody: @@ -1089,7 +1089,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Reload HTTP layer communication certificates. + description: Reloads the HTTP communication certificates. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#reload-http-certificates responses: @@ -1107,7 +1107,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Reload Transport layer communication certificates. + description: Reloads the transport communication certificates. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#reload-transport-certificates responses: @@ -1125,7 +1125,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves multi-tenancy configuration. Only accessible to admins and users with REST API permissions. + description: Retrieves the multi-tenancy configuration. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/multi-tenancy/dynamic-config/#configuring-multi-tenancy-with-the-rest-api responses: @@ -1140,7 +1140,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Creates or replaces the multi-tenancy configuration. Only accessible to admins and users with REST API permissions. + description: Creates or replaces the multi-tenancy configuration. Requires super admin or REST API permissions. externalDocs: url: https://opensearch.org/docs/latest/security/multi-tenancy/dynamic-config/#configuring-multi-tenancy-with-the-rest-api requestBody: @@ -1173,7 +1173,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Add, delete, or modify multiple tenants in a single call. + description: Adds, deletes, or modifies multiple tenants in a single request. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-tenants requestBody: @@ -1191,7 +1191,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Retrieves one tenant. + description: Retrieves the specified tenant. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#get-tenant parameters: @@ -1227,7 +1227,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Add, delete, or modify a single tenant. + description: Adds, deletes, or modifies a single tenant. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#patch-tenant parameters: @@ -1246,7 +1246,7 @@ paths: x-distributions-excluded: - amazon-managed - amazon-serverless - description: Delete the specified tenant. + description: Deletes the specified tenant. externalDocs: url: https://opensearch.org/docs/latest/security/access-control/api/#delete-action-group parameters: @@ -2241,14 +2241,14 @@ components: security.authinfo::query.auth_type: name: auth_type in: query - description: The type of current authentication request. + description: The type of the current authentication request. schema: type: string required: false security.authinfo::query.verbose: name: verbose in: query - description: Indicates whether a verbose response should be returned. + description: Whether to return a verbose response. schema: type: boolean required: false @@ -2262,35 +2262,35 @@ components: security.create_role::path.role: name: role in: path - description: The name of the role to be created. + description: The name of the role to create. schema: type: string required: true security.create_role_mapping::path.role: name: role in: path - description: The name of the role to create a role mapping for. + description: The name of the role for which to create a role mapping. schema: type: string required: true security.create_tenant::path.tenant: name: tenant in: path - description: The name of the tenant to be created. + description: The name of the tenant to create. schema: type: string required: true security.create_user::path.username: name: username in: path - description: The name of the user to be created. + description: The name of the user to create. schema: type: string required: true security.create_user_legacy::path.username: name: username in: path - description: The name of the user to be created. + description: The name of the user to create. schema: type: string required: true @@ -2304,7 +2304,7 @@ components: security.delete_distinguished_name::path.cluster_name: name: cluster_name in: path - description: The cluster-name to delete from list of distinguished names. + description: The cluster name to delete from list of distinguished names. schema: type: string required: true @@ -2318,7 +2318,7 @@ components: security.delete_role_mapping::path.role: name: role in: path - description: The name of the role whose mapping needs to delete. + description: The name of the role for which to delete the role's mappings. schema: type: string required: true @@ -2346,14 +2346,14 @@ components: security.generate_user_token::path.username: name: username in: path - description: The name of the user for whom an auth token is to be vended. + description: The name of the user for whom to issue an authorization token. schema: type: string required: true security.generate_user_token_legacy::path.username: name: username in: path - description: The name of the user for whom an auth token is to be vended. + description: The name of the user for whom to issue an authorization token. schema: type: string required: true @@ -2367,75 +2367,77 @@ components: security.get_node_certificates::path.node_id: name: node_id in: path - description: The full-id of the node to retrieve certificates. + description: The node ID to retrieve certificates for. schema: type: string required: true security.get_all_certificates::query.cert_type: name: cert_type in: query - description: The type of certificates (HTTP, TRANSPORT, ALL) to retrieve from all nodes. + description: The type of certificates (`HTTP`, `TRANSPORT`, or `ALL`) to retrieve from all nodes. schema: type: string required: false security.get_node_certificates::query.cert_type: name: cert_type in: query - description: The type of certificates (HTTP, TRANSPORT, ALL) to retrieve for a node. + description: The type of certificates (`HTTP`, `TRANSPORT`, or `ALL`) to retrieve from a node. schema: type: string required: false security.get_all_certificates::query.timeout: name: timeout in: query - description: The maximum duration, in seconds, to be spent to retrieve certificates from all nodes. + description: The maximum duration, in seconds, to spend retrieving certificates from all nodes before a timeout. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' required: false security.get_node_certificates::query.timeout: name: timeout in: query - description: The maximum duration, in seconds, to be spent to retrieve a node's certificates. + description: The maximum duration, in seconds, to spend retrieving certificates from all nodes before a timeout. schema: $ref: '../schemas/_common.yaml#/components/schemas/Duration' required: false security.get_distinguished_name::path.cluster_name: name: cluster_name in: path - description: The cluster-name to retrieve nodes DN setting for. + description: The name of the cluster to retrieve that cluster's nodes DN settings. schema: type: string required: true security.get_distinguished_name::query.show_all: name: show_all in: query - description: A Boolean flag to include/exclude static nodes DN from final result. + description: Whether to include or exclude any static node's DN settings from the final result. schema: type: boolean required: false security.get_distinguished_names::query.show_all: name: show_all in: query - description: A Boolean flag to include/exclude static nodes DN from final result. + description: Whether to include or exclude any static node's DN settings from the final result. schema: type: boolean required: false security.get_role::path.role: name: role in: path + description: The name of the role to retrieve. schema: type: string required: true security.get_role_mapping::path.role: name: role in: path + description: The name of the role mapping to retrieve. schema: type: string required: true security.get_sslinfo::query.show_dn: name: show_dn in: query - description: A Boolean flag to indicate whether all domain names should be returned. + description: Whether to include all domain names in the response. schema: type: [boolean, string] required: false @@ -2463,7 +2465,7 @@ components: security.health::query.mode: name: mode in: query - description: A flag to indicate whether service should consider security-plugin's status before returning health response. `strict` mode indicates service should check Security plugin status. + description: A flag that determines whether to consider the security status before returning a response for a health query response. For example, `strict` mode indicates service should check the Security plugin status. schema: type: string required: false @@ -2477,7 +2479,7 @@ components: security.patch_distinguished_name::path.cluster_name: name: cluster_name in: path - description: The cluster name to update `nodesDn` value. + description: The cluster name to update the `nodesDn` value. schema: type: string required: true @@ -2491,7 +2493,7 @@ components: security.patch_role_mapping::path.role: name: role in: path - description: The name of the role to update role-mapping for. + description: The name of the role to update a role mapping for schema: type: string required: true @@ -2512,14 +2514,14 @@ components: security.update_distinguished_name::path.cluster_name: name: cluster_name in: path - description: The cluster-name to create/update `nodesDn` value for. + description: The name of the cluster containing the `nodesDn` value to create or update. schema: type: string required: true security.validate::query.accept_invalid: name: accept_invalid in: query - description: A Boolean flag to indicate whether invalid v6 configuration should be allowed. + description: Whether an invalid v6 configuration should be allowed. schema: type: boolean required: false diff --git a/spec/schemas/security._common.yaml b/spec/schemas/security._common.yaml index ac53b2be7..5bb998d60 100644 --- a/spec/schemas/security._common.yaml +++ b/spec/schemas/security._common.yaml @@ -131,65 +131,65 @@ components: properties: user: type: string - description: A User object as a string. + description: A user object as a string. user_name: type: string - description: User's name. + description: The username. user_requested_tenant: type: ['null', string] - description: Name of the tenant the user wants to switch to. + description: The name of the tenant the user would like to switch to. remote_address: type: ['null', string] description: The IP address of remote user. backend_roles: type: array - description: Backend roles associated with the user. + description: The backend roles associated with the user. items: type: string custom_attribute_names: type: array - description: Name of the attributes associated with the user. + description: The name of the attributes associated with the user. items: type: string roles: type: array - description: Roles associated with the user. + description: The roles associated with the user. items: type: string tenants: type: object - description: Tenants the user has access to with read-write or read-only access indicator. + description: The tenants the user has access to with `read-write` or `read-only` access indicators. principal: type: ['null', string] - description: User principal. + description: The user's principal. peer_certificates: type: [number, string] - description: Number of peer certificates. + description: The number of peer certificates related to the user. sso_logout_url: type: ['null', string] - description: Logout URL. + description: The logout URL. size_of_user: type: string - description: Size of user in memory. + description: The size of user contained in memory. size_of_custom_attributes: type: string - description: Size of user's custom attributes in bytes. + description: The size of the user's custom attributes in bytes. size_of_backendroles: type: string - description: Size of backend roles in bytes. + description: The size of the user's backend roles in bytes. CertificateCountPerNode: type: object properties: total: type: number - description: Total number of nodes. + description: The total number of nodes. successful: type: number - description: Number of nodes for which certificates could be fetched. + description: The number of nodes for which certificates can be fetched. failed: type: number - description: Number of nodes for which certificates could not be fetched. + description: The number of nodes for which certificates could not be fetched. CertificatesDetail: type: object @@ -210,7 +210,7 @@ components: properties: name: type: string - description: Name of the node. + description: The name of the node. certificates: type: object additionalProperties: @@ -307,7 +307,7 @@ components: properties: config: type: array - description: List of configs to be upgraded. + description: A list of configurations to upgrade. items: type: string @@ -325,36 +325,36 @@ components: description: User's name not_fail_on_forbidden_enabled: type: boolean - description: Indicates whether DNFOF is enabled. + description: Indicates whether `DNFOF` is enabled. opensearch_dashboards_mt_enabled: type: boolean description: Indicates whether multi-tenancy is enabled. opensearch_dashboards_index: type: string - description: Name of the dashboards index. + description: The name of the dashboard's index. opensearch_dashboards_server_user: type: string - description: Name of the user used to connect dashboards to the server. + description: The name of the user used to connect dashboard's to the server. multitenancy_enabled: type: boolean description: Indicates whether multi-tenancy is enabled. private_tenant_enabled: type: boolean - description: Indicates whether private tenant is enabled for all users. + description: Indicates whether a private tenant is enabled for all users. default_tenant: type: string description: The default tenant setting for the dashboard. sign_in_options: type: array - description: List of available sign-in options available. + description: A list of available sign-in options. items: type: string password_validation_error_message: type: string - description: Error message when password validation fails. + description: The error message when a password validation fails. password_validation_regex: type: string - description: Reg-ex to be used to perform password validation. + description: The regular expression used perform password validation. DistinguishedNames: type: object @@ -420,7 +420,8 @@ components: description: The generated OBO token. durationSeconds: type: string - description: The duration of the token. Default is `300s`. + default: 300s + description: The duration of the token. HealthInfo: type: object @@ -496,13 +497,13 @@ components: properties: description: type: string - description: Contains the description supplied by the user to describe the token. + description: The description supplied by the user to describe the token. service: type: string - description: A name of the service if generating a token for that service. + description: The name of the service when generating a token for that service. duration: type: string - description: Value in seconds. + description: A duration in seconds. required: - description @@ -513,7 +514,7 @@ components: type: [number, string] message: type: string - description: Message returned as part of OK response. + description: The nessage returned as part of an `OK` response. Created: type: object @@ -522,7 +523,7 @@ components: type: [number, string] message: type: string - description: Message returned as part of CREATED response. + description: The message returned as part of a `CREATED` response. PatchOperations: type: array @@ -534,7 +535,7 @@ components: properties: op: type: string - description: 'The operation to perform. Possible values: remove, add, replace, move, copy, test.' + description: The operation to perform, such as `remove`, `add`, `replace`, `move`, `copy`, or `test`. path: type: string description: The path to the resource. @@ -555,7 +556,7 @@ components: type: boolean disabled_endpoints: type: object - description: An object with disabled APIs as key and array of HTTP methods as values. + description: An object with disabled APIs as keys and an array of HTTP methods as values. Role: type: object @@ -628,53 +629,53 @@ components: properties: principal: type: ['null', string] - description: User principal. + description: The user's principal. peer_certificates: type: [number, string] - description: Number of certificates. + description: The number of certificates. peer_certificates_list: type: [array,'null'] - description: List of domain names from peer certificates. + description: A list of domain names from peer certificates. items: type: string local_certificates_list: type: array - description: List of domain names from local certificates. + description: A list of domain names from local certificates. items: type: string ssl_protocol: type: ['null',string] - description: Protocol for this SSL setup. + description: The protocol for this SSL setup. ssl_cipher: type: ['null',string] - description: Cipher for this SSL setup. + description: The cipher for this SSL setup. ssl_openssl_available: type: boolean - description: A Boolean to indicate if OpenSSL is available. + description: Whether OpenSSL is available. ssl_openssl_version: type: [number, string] description: Version of OpenSSL. ssl_openssl_version_string: type: ['null', string] - description: Full version string for OpenSSL version. + description: The full version string for the OpenSSL version. ssl_openssl_non_available_cause: type: ['null', string] - description: Reason for OpenSSL unavailability. + description: The reason OpenSSL is unavailable. ssl_openssl_supports_key_manager_factory: type: boolean - description: Indicates where KMF is supported. + description: Whether `KMF` is supported. ssl_openssl_supports_hostname_validation: type: boolean - description: Indicates whether hostname validation is supported. + description: Whether the hostname validation is supported. ssl_provider_http: type: ['null',string] - description: Returns HTTP provider's name. + description: Returns the HTTP provider's name. ssl_provider_transport_server: type: string - description: Returns transport server's name. + description: Returns the transport server's name. ssl_provider_transport_client: type: string - description: Returns transport client's name. + description: Returns the transport client's name. required: - peer_certificates - principal