diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 821c10b0f6..d19325d562 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -28731,7 +28731,7 @@ "security" ], "summary": "Activate a user profile", - "description": "Create or update a user profile on behalf of another user.", + "description": "Create or update a user profile on behalf of another user.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nThe calling application must have either an `access_token` or a combination of `username` and `password` for the user that the profile document is intended for.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nThis API creates or updates a profile document for end users with information that is extracted from the user's authentication object including `username`, `full_name,` `roles`, and the authentication realm.\nFor example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token.\n\nWhen updating a profile document, the API enables the document if it was disabled.\nAny updates do not change existing content for either the `labels` or `data` fields.", "operationId": "security-activate-user-profile", "requestBody": { "content": { @@ -28740,15 +28740,18 @@ "type": "object", "properties": { "access_token": { + "description": "The user's Elasticsearch access token or JWT.\nBoth `access` and `id` JWT token types are supported and they depend on the underlying JWT realm configuration.\nIf you specify the `access_token` grant type, this parameter is required.\nIt is not valid with other grant types.", "type": "string" }, "grant_type": { "$ref": "#/components/schemas/security._types:GrantType" }, "password": { + "description": "The user's password.\nIf you specify the `password` grant type, this parameter is required.\nIt is not valid with other grant types.", "type": "string" }, "username": { + "description": "The username that identifies the user.\nIf you specify the `password` grant type, this parameter is required.\nIt is not valid with other grant types.", "type": "string" } }, @@ -30599,7 +30602,7 @@ "security" ], "summary": "Disable a user profile", - "description": "Disable user profiles so that they are not visible in user profile searches.", + "description": "Disable user profiles so that they are not visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches.\nTo re-enable a disabled user profile, use the enable user profile API .", "operationId": "security-disable-user-profile", "parameters": [ { @@ -30621,7 +30624,7 @@ "security" ], "summary": "Disable a user profile", - "description": "Disable user profiles so that they are not visible in user profile searches.", + "description": "Disable user profiles so that they are not visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches.\nTo re-enable a disabled user profile, use the enable user profile API .", "operationId": "security-disable-user-profile-1", "parameters": [ { @@ -30689,7 +30692,7 @@ "security" ], "summary": "Enable a user profile", - "description": "Enable user profiles to make them visible in user profile searches.", + "description": "Enable user profiles to make them visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, it's automatically enabled and visible in user profile searches.\nIf you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again.", "operationId": "security-enable-user-profile", "parameters": [ { @@ -30711,7 +30714,7 @@ "security" ], "summary": "Enable a user profile", - "description": "Enable user profiles to make them visible in user profile searches.", + "description": "Enable user profiles to make them visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, it's automatically enabled and visible in user profile searches.\nIf you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again.", "operationId": "security-enable-user-profile-1", "parameters": [ { @@ -31515,7 +31518,7 @@ "security" ], "summary": "Get a user profile", - "description": "Get a user's profile using the unique profile ID.", + "description": "Get a user's profile using the unique profile ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "operationId": "security-get-user-profile", "parameters": [ { @@ -31542,7 +31545,7 @@ { "in": "query", "name": "data", - "description": "List of filters for the `data` field of the profile document.\nTo return all content use `data=*`. To return a subset of content\nuse `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", + "description": "A comma-separated list of filters for the `data` field of the profile document.\nTo return all content use `data=*`.\nTo return a subset of content use `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", "deprecated": false, "schema": { "oneOf": [ @@ -31569,6 +31572,7 @@ "type": "object", "properties": { "profiles": { + "description": "A successful call returns the JSON representation of the user profile and its internal versioning numbers.\nThe API returns an empty object if no profile document is found for the provided `uid`.\nThe content of the data field is not returned by default to avoid deserializing a potential large payload.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:UserProfileWithMetadata" @@ -31770,7 +31774,7 @@ "security" ], "summary": "Check user profile privileges", - "description": "Determine whether the users associated with the specified user profile IDs have all the requested privileges.", + "description": "Determine whether the users associated with the specified user profile IDs have all the requested privileges.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/user-profile.html" }, @@ -31790,7 +31794,7 @@ "security" ], "summary": "Check user profile privileges", - "description": "Determine whether the users associated with the specified user profile IDs have all the requested privileges.", + "description": "Determine whether the users associated with the specified user profile IDs have all the requested privileges.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/user-profile.html" }, @@ -32160,7 +32164,10 @@ "security" ], "summary": "Authenticate SAML", - "description": "Submits a SAML response message to Elasticsearch for consumption.", + "description": "Submit a SAML response message to Elasticsearch for consumption.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe SAML message that is submitted can be:\n\n* A response to a SAML authentication request that was previously created using the SAML prepare authentication API.\n* An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.\n\nIn either case, the SAML message needs to be a base64 encoded XML document with a root element of ``.\n\nAfter successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\nThis API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-stack.html" + }, "operationId": "security-saml-authenticate", "requestBody": { "content": { @@ -32169,7 +32176,7 @@ "type": "object", "properties": { "content": { - "description": "The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document.", + "description": "The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document.", "type": "string" }, "ids": { @@ -32198,18 +32205,23 @@ "type": "object", "properties": { "access_token": { + "description": "The access token that was generated by Elasticsearch.", "type": "string" }, "username": { + "description": "The authenticated user's name.", "type": "string" }, "expires_in": { + "description": "The amount of time (in seconds) left until the token expires.", "type": "number" }, "refresh_token": { + "description": "The refresh token that was generated by Elasticsearch.", "type": "string" }, "realm": { + "description": "The name of the realm where the user was authenticated.", "type": "string" } }, @@ -32234,7 +32246,10 @@ "security" ], "summary": "Logout of SAML completely", - "description": "Verifies the logout response sent from the SAML IdP.", + "description": "Verifies the logout response sent from the SAML IdP.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout.\nThis API verifies the response by ensuring the content is relevant and validating its signature.\nAn empty response is returned if the verification process is successful.\nThe response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding.\nThe caller of this API must prepare the request accordingly so that this API can handle either of them.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-stack.html" + }, "operationId": "security-saml-complete-logout", "requestBody": { "content": { @@ -32284,7 +32299,10 @@ "security" ], "summary": "Invalidate SAML", - "description": "Submits a SAML LogoutRequest message to Elasticsearch for consumption.", + "description": "Submit a SAML LogoutRequest message to Elasticsearch for consumption.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe logout request comes from the SAML IdP during an IdP initiated Single Logout.\nThe custom web application can use this API to have Elasticsearch process the `LogoutRequest`.\nAfter successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message.\nThus the user can be redirected back to their IdP.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-stack.html" + }, "operationId": "security-saml-invalidate", "requestBody": { "content": { @@ -32293,15 +32311,15 @@ "type": "object", "properties": { "acs": { - "description": "The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter.", + "description": "The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the `realm` parameter.", "type": "string" }, "query_string": { - "description": "The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout.\nThis query should include a single parameter named SAMLRequest that contains a SAML logout request that is deflated and Base64 encoded.\nIf the SAML IdP has signed the logout request, the URL should include two extra parameters named SigAlg and Signature that contain the algorithm used for the signature and the signature value itself.\nIn order for Elasticsearch to be able to verify the IdP’s signature, the value of the query_string field must be an exact match to the string provided by the browser.\nThe client application must not attempt to parse or process the string in any way.", + "description": "The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout.\nThis query should include a single parameter named `SAMLRequest` that contains a SAML logout request that is deflated and Base64 encoded.\nIf the SAML IdP has signed the logout request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value itself.\nIn order for Elasticsearch to be able to verify the IdP's signature, the value of the `query_string` field must be an exact match to the string provided by the browser.\nThe client application must not attempt to parse or process the string in any way.", "type": "string" }, "realm": { - "description": "The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter.", + "description": "The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the `acs` parameter.", "type": "string" } }, @@ -32322,12 +32340,15 @@ "type": "object", "properties": { "invalidated": { + "description": "The number of tokens that were invalidated as part of this logout.", "type": "number" }, "realm": { + "description": "The realm name of the SAML realm in Elasticsearch that authenticated the user.", "type": "string" }, "redirect": { + "description": "A SAML logout response as a parameter so that the user can be redirected back to the SAML IdP.", "type": "string" } }, @@ -32350,7 +32371,10 @@ "security" ], "summary": "Logout of SAML", - "description": "Submits a request to invalidate an access token and refresh token.", + "description": "Submits a request to invalidate an access token and refresh token.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThis API invalidates the tokens that were generated for a user by the SAML authenticate API.\nIf the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout).", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-stack.html" + }, "operationId": "security-saml-logout", "requestBody": { "content": { @@ -32359,7 +32383,7 @@ "type": "object", "properties": { "token": { - "description": "The access token that was returned as a response to calling the SAML authenticate API.\nAlternatively, the most recent token that was received after refreshing the original one by using a refresh_token.", + "description": "The access token that was returned as a response to calling the SAML authenticate API.\nAlternatively, the most recent token that was received after refreshing the original one by using a `refresh_token`.", "type": "string" }, "refresh_token": { @@ -32384,6 +32408,7 @@ "type": "object", "properties": { "redirect": { + "description": "A URL that contains a SAML logout request as a parameter.\nYou can use this URL to be redirected back to the SAML IdP and to initiate Single Logout.", "type": "string" } }, @@ -32404,7 +32429,10 @@ "security" ], "summary": "Prepare SAML authentication", - "description": "Creates a SAML authentication request (``) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.", + "description": "Create a SAML authentication request (``) as a URL string based on the configuration of the respective SAML realm in Elasticsearch.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThis API returns a URL pointing to the SAML Identity Provider.\nYou can use the URL to redirect the browser of the user in order to continue the authentication process.\nThe URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded.\nIf the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`.\nThese parameters contain the algorithm used for the signature and the signature value itself.\nIt also returns a random string that uniquely identifies this SAML Authentication request.\nThe caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/saml-guide-stack.html" + }, "operationId": "security-saml-prepare-authentication", "requestBody": { "content": { @@ -32413,15 +32441,15 @@ "type": "object", "properties": { "acs": { - "description": "The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch.\nThe realm is used to generate the authentication request. You must specify either this parameter or the realm parameter.", + "description": "The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch.\nThe realm is used to generate the authentication request. You must specify either this parameter or the `realm` parameter.", "type": "string" }, "realm": { - "description": "The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request.\nYou must specify either this parameter or the acs parameter.", + "description": "The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request.\nYou must specify either this parameter or the `acs` parameter.", "type": "string" }, "relay_state": { - "description": "A string that will be included in the redirect URL that this API returns as the RelayState query parameter.\nIf the Authentication Request is signed, this value is used as part of the signature computation.", + "description": "A string that will be included in the redirect URL that this API returns as the `RelayState` query parameter.\nIf the Authentication Request is signed, this value is used as part of the signature computation.", "type": "string" } } @@ -32442,9 +32470,11 @@ "$ref": "#/components/schemas/_types:Id" }, "realm": { + "description": "The name of the Elasticsearch realm that was used to construct the authentication request.", "type": "string" }, "redirect": { + "description": "The URL to redirect the user to.", "type": "string" } }, @@ -32467,7 +32497,7 @@ "security" ], "summary": "Create SAML service provider metadata", - "description": "Generate SAML metadata for a SAML 2.0 Service Provider.", + "description": "Generate SAML metadata for a SAML 2.0 Service Provider.\n\nThe SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file.\nThis API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch.", "operationId": "security-saml-service-provider-metadata", "parameters": [ { @@ -32491,6 +32521,7 @@ "type": "object", "properties": { "metadata": { + "description": "An XML string that contains a SAML Service Provider's metadata for the realm.", "type": "string" } }, @@ -32511,7 +32542,7 @@ "security" ], "summary": "Suggest a user profile", - "description": "Get suggestions for user profiles that match specified search criteria.", + "description": "Get suggestions for user profiles that match specified search criteria.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "operationId": "security-suggest-user-profiles", "parameters": [ { @@ -32533,7 +32564,7 @@ "security" ], "summary": "Suggest a user profile", - "description": "Get suggestions for user profiles that match specified search criteria.", + "description": "Get suggestions for user profiles that match specified search criteria.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "operationId": "security-suggest-user-profiles-1", "parameters": [ { @@ -32626,7 +32657,7 @@ "security" ], "summary": "Update a cross-cluster API key", - "description": "Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.", + "description": "Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.\n\nTo use this API, you must have at least the `manage_security` cluster privilege.\nUsers can only update API keys that they created.\nTo update another user's API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user's credentials are required.\n\nIt's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API.\n\nThis API supports updates to an API key's access scope, metadata, and expiration.\nThe owner user's information, such as the `username` and `realm`, is also updated automatically on every call.\n\nNOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-api-key.html" }, @@ -32697,7 +32728,7 @@ "security" ], "summary": "Update user profile data", - "description": "Update specific data for the user profile that is associated with a unique ID.", + "description": "Update specific data for the user profile that is associated with a unique ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_user_profile` cluster privilege.\n* The `update_profile_data` global privilege for the namespaces that are referenced in the request.\n\nThis API updates the `labels` and `data` fields of an existing user profile document with JSON objects.\nNew keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request.\n\nFor both labels and data, content is namespaced by the top-level fields.\nThe `update_profile_data` global privilege grants privileges for updating only the allowed namespaces.", "operationId": "security-update-user-profile-data", "parameters": [ { @@ -32728,7 +32759,7 @@ "security" ], "summary": "Update user profile data", - "description": "Update specific data for the user profile that is associated with a unique ID.", + "description": "Update specific data for the user profile that is associated with a unique ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_user_profile` cluster privilege.\n* The `update_profile_data` global privilege for the namespaces that are referenced in the request.\n\nThis API updates the `labels` and `data` fields of an existing user profile document with JSON objects.\nNew keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request.\n\nFor both labels and data, content is namespaced by the top-level fields.\nThe `update_profile_data` global privilege grants privileges for updating only the allowed namespaces.", "operationId": "security-update-user-profile-data-1", "parameters": [ { @@ -87651,7 +87682,7 @@ "type": "object", "properties": { "uids": { - "description": "A list of Profile UIDs to match against.", + "description": "A list of profile UIDs to match against.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:UserProfileId" @@ -96531,9 +96562,11 @@ "$ref": "#/components/schemas/security.suggest_user_profiles:TotalUserProfiles" }, "took": { + "description": "The number of milliseconds it took Elasticsearch to run the request.", "type": "number" }, "profiles": { + "description": "A list of profile documents, ordered by relevance, that match the search criteria.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:UserProfile" @@ -105617,7 +105650,7 @@ "security.disable_user_profile#refresh": { "in": "query", "name": "refresh", - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -105648,7 +105681,7 @@ "security.enable_user_profile#uid": { "in": "path", "name": "uid", - "description": "Unique identifier for the user profile.", + "description": "A unique identifier for the user profile.", "required": true, "deprecated": false, "schema": { @@ -105659,7 +105692,7 @@ "security.enable_user_profile#refresh": { "in": "query", "name": "refresh", - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', nothing is done with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -105890,7 +105923,7 @@ "security.suggest_user_profiles#data": { "in": "query", "name": "data", - "description": "List of filters for the `data` field of the profile document.\nTo return all content use `data=*`. To return a subset of content\nuse `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", + "description": "A comma-separated list of filters for the `data` field of the profile document.\nTo return all content use `data=*`.\nTo return a subset of content, use `data=` to retrieve content nested under the specified ``.\nBy default, the API returns no `data` content.\nIt is an error to specify `data` as both the query parameter and the request body field.", "deprecated": false, "schema": { "oneOf": [ @@ -105941,7 +105974,7 @@ "security.update_user_profile_data#refresh": { "in": "query", "name": "refresh", - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', nothing is done with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -109284,15 +109317,15 @@ "type": "object", "properties": { "name": { - "description": "Query string used to match name-related fields in user profile documents.\nName-related fields are the user's `username`, `full_name`, and `email`.", + "description": "A query string used to match name-related fields in user profile documents.\nName-related fields are the user's `username`, `full_name`, and `email`.", "type": "string" }, "size": { - "description": "Number of profiles to return.", + "description": "The number of profiles to return.", "type": "number" }, "data": { - "description": "List of filters for the `data` field of the profile document.\nTo return all content use `data=*`. To return a subset of content\nuse `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", + "description": "A comma-separated list of filters for the `data` field of the profile document.\nTo return all content use `data=*`.\nTo return a subset of content, use `data=` to retrieve content nested under the specified ``.\nBy default, the API returns no `data` content.\nIt is an error to specify `data` as both the query parameter and the request body field.", "oneOf": [ { "type": "string" @@ -109320,14 +109353,14 @@ "type": "object", "properties": { "labels": { - "description": "Searchable data that you want to associate with the user profile. This\nfield supports a nested data structure.", + "description": "Searchable data that you want to associate with the user profile.\nThis field supports a nested data structure.\nWithin the labels object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`).", "type": "object", "additionalProperties": { "type": "object" } }, "data": { - "description": "Non-searchable data that you want to associate with the user profile.\nThis field supports a nested data structure.", + "description": "Non-searchable data that you want to associate with the user profile.\nThis field supports a nested data structure.\nWithin the `data` object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`).\nThe data object is not searchable, but can be retrieved with the get user profile API.", "type": "object", "additionalProperties": { "type": "object" diff --git a/output/schema/schema.json b/output/schema/schema.json index c4791dadd6..26a9266c72 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -15883,7 +15883,7 @@ "stability": "stable" } }, - "description": "Activate a user profile.\n\nCreate or update a user profile on behalf of another user.", + "description": "Activate a user profile.\n\nCreate or update a user profile on behalf of another user.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nThe calling application must have either an `access_token` or a combination of `username` and `password` for the user that the profile document is intended for.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nThis API creates or updates a profile document for end users with information that is extracted from the user's authentication object including `username`, `full_name,` `roles`, and the authentication realm.\nFor example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token.\n\nWhen updating a profile document, the API enables the document if it was disabled.\nAny updates do not change existing content for either the `labels` or `data` fields.", "docId": "security-api-activate-user-profile", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-activate-user-profile.html", "name": "security.activate_user_profile", @@ -16740,8 +16740,9 @@ "stability": "stable" } }, - "description": "Disable a user profile.\n\nDisable user profiles so that they are not visible in user profile searches.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/security-api-disable-user-profile.html", + "description": "Disable a user profile.\n\nDisable user profiles so that they are not visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches.\nTo re-enable a disabled user profile, use the enable user profile API .", + "docId": "security-api-disable-user-profile", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-disable-user-profile.html", "name": "security.disable_user_profile", "privileges": { "cluster": [ @@ -16818,7 +16819,7 @@ "stability": "stable" } }, - "description": "Enable a user profile.\n\nEnable user profiles to make them visible in user profile searches.", + "description": "Enable a user profile.\n\nEnable user profiles to make them visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, it's automatically enabled and visible in user profile searches.\nIf you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again.", "docId": "security-api-enable-user-profile", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-enable-user-profile.html", "name": "security.enable_user_profile", @@ -17425,13 +17426,13 @@ "stability": "stable" } }, - "description": "Get a user profile.\n\nGet a user's profile using the unique profile ID.", + "description": "Get a user profile.\n\nGet a user's profile using the unique profile ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "docId": "security-api-get-user-profile", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-profile.html", "name": "security.get_user_profile", "privileges": { "cluster": [ - "manage_user_profile" + "read_security" ] }, "request": { @@ -17559,7 +17560,7 @@ "stability": "stable" } }, - "description": "Check user profile privileges.\n\nDetermine whether the users associated with the specified user profile IDs have all the requested privileges.", + "description": "Check user profile privileges.\n\nDetermine whether the users associated with the specified user profile IDs have all the requested privileges.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "docId": "security-api-has-privileges-profile", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-has-privileges-user-profile.html", "extDocId": "user-profile", @@ -18111,9 +18112,11 @@ "stability": "stable" } }, - "description": "Authenticate SAML.\n\nSubmits a SAML response message to Elasticsearch for consumption.", + "description": "Authenticate SAML.\n\nSubmit a SAML response message to Elasticsearch for consumption.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe SAML message that is submitted can be:\n\n* A response to a SAML authentication request that was previously created using the SAML prepare authentication API.\n* An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.\n\nIn either case, the SAML message needs to be a base64 encoded XML document with a root element of ``.\n\nAfter successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\nThis API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.", "docId": "security-api-saml-authenticate", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-authenticate.html", + "extDocId": "security-saml-guide", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html", "name": "security.saml_authenticate", "request": { "name": "Request", @@ -18150,9 +18153,11 @@ "stability": "stable" } }, - "description": "Logout of SAML completely.\n\nVerifies the logout response sent from the SAML IdP.", + "description": "Logout of SAML completely.\n\nVerifies the logout response sent from the SAML IdP.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout.\nThis API verifies the response by ensuring the content is relevant and validating its signature.\nAn empty response is returned if the verification process is successful.\nThe response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding.\nThe caller of this API must prepare the request accordingly so that this API can handle either of them.", "docId": "security-api-saml-complete-logout", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-complete-logout.html", + "extDocId": "security-saml-guide", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html", "name": "security.saml_complete_logout", "request": { "name": "Request", @@ -18189,9 +18194,11 @@ "stability": "stable" } }, - "description": "Invalidate SAML.\n\nSubmits a SAML LogoutRequest message to Elasticsearch for consumption.", + "description": "Invalidate SAML.\n\nSubmit a SAML LogoutRequest message to Elasticsearch for consumption.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe logout request comes from the SAML IdP during an IdP initiated Single Logout.\nThe custom web application can use this API to have Elasticsearch process the `LogoutRequest`.\nAfter successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message.\nThus the user can be redirected back to their IdP.", "docId": "security-api-saml-invalidate", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-invalidate.html", + "extDocId": "security-saml-guide", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html", "name": "security.saml_invalidate", "request": { "name": "Request", @@ -18228,9 +18235,11 @@ "stability": "stable" } }, - "description": "Logout of SAML.\n\nSubmits a request to invalidate an access token and refresh token.", + "description": "Logout of SAML.\n\nSubmits a request to invalidate an access token and refresh token.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThis API invalidates the tokens that were generated for a user by the SAML authenticate API.\nIf the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout).", "docId": "security-api-saml-logout", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-logout.html", + "extDocId": "security-saml-guide", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html", "name": "security.saml_logout", "request": { "name": "Request", @@ -18267,9 +18276,11 @@ "stability": "stable" } }, - "description": "Prepare SAML authentication.\n\nCreates a SAML authentication request (``) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.", + "description": "Prepare SAML authentication.\n\nCreate a SAML authentication request (``) as a URL string based on the configuration of the respective SAML realm in Elasticsearch.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThis API returns a URL pointing to the SAML Identity Provider.\nYou can use the URL to redirect the browser of the user in order to continue the authentication process.\nThe URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded.\nIf the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`.\nThese parameters contain the algorithm used for the signature and the signature value itself.\nIt also returns a random string that uniquely identifies this SAML Authentication request.\nThe caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process.", "docId": "security-api-saml-prepare-authentication", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-prepare-authentication.html", + "extDocId": "security-saml-guide", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html", "name": "security.saml_prepare_authentication", "request": { "name": "Request", @@ -18306,7 +18317,7 @@ "stability": "stable" } }, - "description": "Create SAML service provider metadata.\n\nGenerate SAML metadata for a SAML 2.0 Service Provider.", + "description": "Create SAML service provider metadata.\n\nGenerate SAML metadata for a SAML 2.0 Service Provider.\n\nThe SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file.\nThis API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch.", "docId": "security-api-saml-sp-metadata", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-sp-metadata.html", "name": "security.saml_service_provider_metadata", @@ -18345,7 +18356,7 @@ "stability": "stable" } }, - "description": "Suggest a user profile.\n\nGet suggestions for user profiles that match specified search criteria.", + "description": "Suggest a user profile.\n\nGet suggestions for user profiles that match specified search criteria.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "docId": "security-api-suggest", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-suggest-user-profile.html", "name": "security.suggest_user_profiles", @@ -18429,7 +18440,7 @@ "stability": "stable" } }, - "description": "Update a cross-cluster API key.\n\nUpdate the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.", + "description": "Update a cross-cluster API key.\n\nUpdate the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.\n\nTo use this API, you must have at least the `manage_security` cluster privilege.\nUsers can only update API keys that they created.\nTo update another user's API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user's credentials are required.\n\nIt's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API.\n\nThis API supports updates to an API key's access scope, metadata, and expiration.\nThe owner user's information, such as the `username` and `realm`, is also updated automatically on every call.\n\nNOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API.", "docId": "security-api-cross-cluster-key-update", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-cross-cluster-api-key.html", "extDocId": "remote-clusters-api-key", @@ -18471,7 +18482,7 @@ "visibility": "public" } }, - "description": "Update security index settings.\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", + "description": "Update security index settings.\n\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", "docId": "security-api-update-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html", "name": "security.update_settings", @@ -18515,7 +18526,7 @@ "stability": "stable" } }, - "description": "Update user profile data.\n\nUpdate specific data for the user profile that is associated with a unique ID.", + "description": "Update user profile data.\n\nUpdate specific data for the user profile that is associated with a unique ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_user_profile` cluster privilege.\n* The `update_profile_data` global privilege for the namespaces that are referenced in the request.\n\nThis API updates the `labels` and `data` fields of an existing user profile document with JSON objects.\nNew keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request.\n\nFor both labels and data, content is namespaced by the top-level fields.\nThe `update_profile_data` global privilege grants privileges for updating only the allowed namespaces.", "docId": "security-api-update-user-data", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-user-profile-data.html", "name": "security.update_user_profile_data", @@ -193252,7 +193263,7 @@ "name": "password" }, { - "description": "In this type of grant, you must supply an access token that was created by the Elasticsearch token service.", + "description": "In this type of grant, you must supply an access token that was created by the Elasticsearch token service.\nIf you are activating a user profile, you can alternatively supply a JWT (either a JWT `access_token` or a JWT `id_token`).", "name": "access_token" } ], @@ -193260,7 +193271,7 @@ "name": "GrantType", "namespace": "security._types" }, - "specLocation": "security/_types/GrantType.ts#L20-L29" + "specLocation": "security/_types/GrantType.ts#L20-L30" }, { "kind": "enum", @@ -195135,6 +195146,7 @@ "kind": "properties", "properties": [ { + "description": "The user's Elasticsearch access token or JWT.\nBoth `access` and `id` JWT token types are supported and they depend on the underlying JWT realm configuration.\nIf you specify the `access_token` grant type, this parameter is required.\nIt is not valid with other grant types.", "name": "access_token", "required": false, "type": { @@ -195146,6 +195158,7 @@ } }, { + "description": "The type of grant.", "name": "grant_type", "required": true, "type": { @@ -195157,6 +195170,7 @@ } }, { + "description": "The user's password.\nIf you specify the `password` grant type, this parameter is required.\nIt is not valid with other grant types.", "name": "password", "required": false, "type": { @@ -195168,6 +195182,7 @@ } }, { + "description": "The username that identifies the user.\nIf you specify the `password` grant type, this parameter is required.\nIt is not valid with other grant types.", "name": "username", "required": false, "type": { @@ -195180,7 +195195,7 @@ } ] }, - "description": "Activate a user profile.\n\nCreate or update a user profile on behalf of another user.", + "description": "Activate a user profile.\n\nCreate or update a user profile on behalf of another user.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nThe calling application must have either an `access_token` or a combination of `username` and `password` for the user that the profile document is intended for.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nThis API creates or updates a profile document for end users with information that is extracted from the user's authentication object including `username`, `full_name,` `roles`, and the authentication realm.\nFor example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token.\n\nWhen updating a profile document, the API enables the document if it was disabled.\nAny updates do not change existing content for either the `labels` or `data` fields.", "inherits": { "type": { "name": "RequestBase", @@ -195193,7 +195208,7 @@ }, "path": [], "query": [], - "specLocation": "security/activate_user_profile/Request.ts#L23-L46" + "specLocation": "security/activate_user_profile/Request.ts#L23-L76" }, { "kind": "response", @@ -197769,7 +197784,7 @@ "body": { "kind": "no_body" }, - "description": "Disable a user profile.\n\nDisable user profiles so that they are not visible in user profile searches.", + "description": "Disable a user profile.\n\nDisable user profiles so that they are not visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches.\nTo re-enable a disabled user profile, use the enable user profile API .", "inherits": { "type": { "name": "RequestBase", @@ -197796,7 +197811,7 @@ ], "query": [ { - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', it does nothing with refreshes.", "name": "refresh", "required": false, "serverDefault": "false", @@ -197809,7 +197824,7 @@ } } ], - "specLocation": "security/disable_user_profile/Request.ts#L24-L55" + "specLocation": "security/disable_user_profile/Request.ts#L24-L63" }, { "kind": "response", @@ -197898,7 +197913,7 @@ "body": { "kind": "no_body" }, - "description": "Enable a user profile.\n\nEnable user profiles to make them visible in user profile searches.", + "description": "Enable a user profile.\n\nEnable user profiles to make them visible in user profile searches.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nWhen you activate a user profile, it's automatically enabled and visible in user profile searches.\nIf you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again.", "inherits": { "type": { "name": "RequestBase", @@ -197911,7 +197926,7 @@ }, "path": [ { - "description": "Unique identifier for the user profile.", + "description": "A unique identifier for the user profile.", "name": "uid", "required": true, "type": { @@ -197925,7 +197940,7 @@ ], "query": [ { - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', nothing is done with refreshes.", "name": "refresh", "required": false, "serverDefault": "false", @@ -197938,7 +197953,7 @@ } } ], - "specLocation": "security/enable_user_profile/Request.ts#L24-L56" + "specLocation": "security/enable_user_profile/Request.ts#L24-L64" }, { "kind": "response", @@ -199824,7 +199839,7 @@ "body": { "kind": "no_body" }, - "description": "Get a user profile.\n\nGet a user's profile using the unique profile ID.", + "description": "Get a user profile.\n\nGet a user's profile using the unique profile ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "inherits": { "type": { "name": "RequestBase", @@ -199866,7 +199881,7 @@ ], "query": [ { - "description": "List of filters for the `data` field of the profile document.\nTo return all content use `data=*`. To return a subset of content\nuse `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", + "description": "A comma-separated list of filters for the `data` field of the profile document.\nTo return all content use `data=*`.\nTo return a subset of content use `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", "name": "data", "required": false, "type": { @@ -199893,7 +199908,7 @@ } } ], - "specLocation": "security/get_user_profile/Request.ts#L23-L55" + "specLocation": "security/get_user_profile/Request.ts#L23-L59" }, { "kind": "response", @@ -199901,6 +199916,7 @@ "kind": "properties", "properties": [ { + "description": "A successful call returns the JSON representation of the user profile and its internal versioning numbers.\nThe API returns an empty object if no profile document is found for the provided `uid`.\nThe content of the data field is not returned by default to avoid deserializing a potential large payload.", "name": "profiles", "required": true, "type": { @@ -199931,7 +199947,7 @@ "name": "Response", "namespace": "security.get_user_profile" }, - "specLocation": "security/get_user_profile/Response.ts#L23-L28" + "specLocation": "security/get_user_profile/Response.ts#L23-L33" }, { "kind": "enum", @@ -200687,6 +200703,7 @@ } }, { + "description": "An object containing all the privileges to be checked.", "name": "privileges", "required": true, "type": { @@ -200699,7 +200716,7 @@ } ] }, - "description": "Check user profile privileges.\n\nDetermine whether the users associated with the specified user profile IDs have all the requested privileges.", + "description": "Check user profile privileges.\n\nDetermine whether the users associated with the specified user profile IDs have all the requested privileges.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "inherits": { "type": { "name": "RequestBase", @@ -200712,7 +200729,7 @@ }, "path": [], "query": [], - "specLocation": "security/has_privileges_user_profile/Request.ts#L24-L49" + "specLocation": "security/has_privileges_user_profile/Request.ts#L24-L55" }, { "kind": "response", @@ -203799,7 +203816,7 @@ "kind": "properties", "properties": [ { - "description": "The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document.", + "description": "The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document.", "name": "content", "required": true, "type": { @@ -203811,7 +203828,7 @@ } }, { - "description": "A json array with all the valid SAML Request Ids that the caller of the API has for the current user.", + "description": "A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user.", "name": "ids", "required": true, "type": { @@ -203836,7 +203853,7 @@ } ] }, - "description": "Authenticate SAML.\n\nSubmits a SAML response message to Elasticsearch for consumption.", + "description": "Authenticate SAML.\n\nSubmit a SAML response message to Elasticsearch for consumption.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe SAML message that is submitted can be:\n\n* A response to a SAML authentication request that was previously created using the SAML prepare authentication API.\n* An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.\n\nIn either case, the SAML message needs to be a base64 encoded XML document with a root element of ``.\n\nAfter successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\nThis API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.", "inherits": { "type": { "name": "RequestBase", @@ -203849,7 +203866,7 @@ }, "path": [], "query": [], - "specLocation": "security/saml_authenticate/Request.ts#L23-L47" + "specLocation": "security/saml_authenticate/Request.ts#L23-L61" }, { "kind": "response", @@ -203857,6 +203874,7 @@ "kind": "properties", "properties": [ { + "description": "The access token that was generated by Elasticsearch.", "name": "access_token", "required": true, "type": { @@ -203868,6 +203886,7 @@ } }, { + "description": "The authenticated user's name.", "name": "username", "required": true, "type": { @@ -203879,6 +203898,7 @@ } }, { + "description": "The amount of time (in seconds) left until the token expires.", "name": "expires_in", "required": true, "type": { @@ -203890,6 +203910,7 @@ } }, { + "description": "The refresh token that was generated by Elasticsearch.", "name": "refresh_token", "required": true, "type": { @@ -203901,6 +203922,7 @@ } }, { + "description": "The name of the realm where the user was authenticated.", "name": "realm", "required": true, "type": { @@ -203917,7 +203939,7 @@ "name": "Response", "namespace": "security.saml_authenticate" }, - "specLocation": "security/saml_authenticate/Response.ts#L22-L30" + "specLocation": "security/saml_authenticate/Response.ts#L22-L45" }, { "kind": "request", @@ -203940,7 +203962,7 @@ } }, { - "description": "A json array with all the valid SAML Request Ids that the caller of the API has for the current user.", + "description": "A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user.", "name": "ids", "required": true, "type": { @@ -203977,7 +203999,7 @@ } ] }, - "description": "Logout of SAML completely.\n\nVerifies the logout response sent from the SAML IdP.", + "description": "Logout of SAML completely.\n\nVerifies the logout response sent from the SAML IdP.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout.\nThis API verifies the response by ensuring the content is relevant and validating its signature.\nAn empty response is returned if the verification process is successful.\nThe response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding.\nThe caller of this API must prepare the request accordingly so that this API can handle either of them.", "inherits": { "type": { "name": "RequestBase", @@ -203990,7 +204012,7 @@ }, "path": [], "query": [], - "specLocation": "security/saml_complete_logout/Request.ts#L23-L49" + "specLocation": "security/saml_complete_logout/Request.ts#L23-L61" }, { "kind": "response", @@ -204001,7 +204023,7 @@ "name": "Response", "namespace": "security.saml_complete_logout" }, - "specLocation": "security/saml_complete_logout/Response.ts#L22-L24" + "specLocation": "security/saml_complete_logout/Response.ts#L22-L27" }, { "kind": "request", @@ -204012,7 +204034,7 @@ "kind": "properties", "properties": [ { - "description": "The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter.", + "description": "The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the `realm` parameter.", "name": "acs", "required": false, "type": { @@ -204024,7 +204046,7 @@ } }, { - "description": "The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout.\nThis query should include a single parameter named SAMLRequest that contains a SAML logout request that is deflated and Base64 encoded.\nIf the SAML IdP has signed the logout request, the URL should include two extra parameters named SigAlg and Signature that contain the algorithm used for the signature and the signature value itself.\nIn order for Elasticsearch to be able to verify the IdP’s signature, the value of the query_string field must be an exact match to the string provided by the browser.\nThe client application must not attempt to parse or process the string in any way.", + "description": "The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout.\nThis query should include a single parameter named `SAMLRequest` that contains a SAML logout request that is deflated and Base64 encoded.\nIf the SAML IdP has signed the logout request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value itself.\nIn order for Elasticsearch to be able to verify the IdP's signature, the value of the `query_string` field must be an exact match to the string provided by the browser.\nThe client application must not attempt to parse or process the string in any way.", "name": "query_string", "required": true, "type": { @@ -204036,7 +204058,7 @@ } }, { - "description": "The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter.", + "description": "The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the `acs` parameter.", "name": "realm", "required": false, "type": { @@ -204049,7 +204071,7 @@ } ] }, - "description": "Invalidate SAML.\n\nSubmits a SAML LogoutRequest message to Elasticsearch for consumption.", + "description": "Invalidate SAML.\n\nSubmit a SAML LogoutRequest message to Elasticsearch for consumption.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThe logout request comes from the SAML IdP during an IdP initiated Single Logout.\nThe custom web application can use this API to have Elasticsearch process the `LogoutRequest`.\nAfter successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message.\nThus the user can be redirected back to their IdP.", "inherits": { "type": { "name": "RequestBase", @@ -204062,7 +204084,7 @@ }, "path": [], "query": [], - "specLocation": "security/saml_invalidate/Request.ts#L22-L52" + "specLocation": "security/saml_invalidate/Request.ts#L22-L61" }, { "kind": "response", @@ -204070,6 +204092,7 @@ "kind": "properties", "properties": [ { + "description": "The number of tokens that were invalidated as part of this logout.", "name": "invalidated", "required": true, "type": { @@ -204081,6 +204104,7 @@ } }, { + "description": "The realm name of the SAML realm in Elasticsearch that authenticated the user.", "name": "realm", "required": true, "type": { @@ -204092,6 +204116,7 @@ } }, { + "description": "A SAML logout response as a parameter so that the user can be redirected back to the SAML IdP.", "name": "redirect", "required": true, "type": { @@ -204108,7 +204133,7 @@ "name": "Response", "namespace": "security.saml_invalidate" }, - "specLocation": "security/saml_invalidate/Response.ts#L22-L28" + "specLocation": "security/saml_invalidate/Response.ts#L22-L37" }, { "kind": "request", @@ -204119,7 +204144,7 @@ "kind": "properties", "properties": [ { - "description": "The access token that was returned as a response to calling the SAML authenticate API.\nAlternatively, the most recent token that was received after refreshing the original one by using a refresh_token.", + "description": "The access token that was returned as a response to calling the SAML authenticate API.\nAlternatively, the most recent token that was received after refreshing the original one by using a `refresh_token`.", "name": "token", "required": true, "type": { @@ -204144,7 +204169,7 @@ } ] }, - "description": "Logout of SAML.\n\nSubmits a request to invalidate an access token and refresh token.", + "description": "Logout of SAML.\n\nSubmits a request to invalidate an access token and refresh token.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThis API invalidates the tokens that were generated for a user by the SAML authenticate API.\nIf the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout).", "inherits": { "type": { "name": "RequestBase", @@ -204157,7 +204182,7 @@ }, "path": [], "query": [], - "specLocation": "security/saml_logout/Request.ts#L22-L50" + "specLocation": "security/saml_logout/Request.ts#L22-L57" }, { "kind": "response", @@ -204165,6 +204190,7 @@ "kind": "properties", "properties": [ { + "description": "A URL that contains a SAML logout request as a parameter.\nYou can use this URL to be redirected back to the SAML IdP and to initiate Single Logout.", "name": "redirect", "required": true, "type": { @@ -204181,7 +204207,7 @@ "name": "Response", "namespace": "security.saml_logout" }, - "specLocation": "security/saml_logout/Response.ts#L20-L24" + "specLocation": "security/saml_logout/Response.ts#L20-L28" }, { "kind": "request", @@ -204192,7 +204218,7 @@ "kind": "properties", "properties": [ { - "description": "The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch.\nThe realm is used to generate the authentication request. You must specify either this parameter or the realm parameter.", + "description": "The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch.\nThe realm is used to generate the authentication request. You must specify either this parameter or the `realm` parameter.", "name": "acs", "required": false, "type": { @@ -204204,7 +204230,7 @@ } }, { - "description": "The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request.\nYou must specify either this parameter or the acs parameter.", + "description": "The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request.\nYou must specify either this parameter or the `acs` parameter.", "name": "realm", "required": false, "type": { @@ -204216,7 +204242,7 @@ } }, { - "description": "A string that will be included in the redirect URL that this API returns as the RelayState query parameter.\nIf the Authentication Request is signed, this value is used as part of the signature computation.", + "description": "A string that will be included in the redirect URL that this API returns as the `RelayState` query parameter.\nIf the Authentication Request is signed, this value is used as part of the signature computation.", "name": "relay_state", "required": false, "type": { @@ -204229,7 +204255,7 @@ } ] }, - "description": "Prepare SAML authentication.\n\nCreates a SAML authentication request (``) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.", + "description": "Prepare SAML authentication.\n\nCreate a SAML authentication request (``) as a URL string based on the configuration of the respective SAML realm in Elasticsearch.\n\nNOTE: This API is intended for use by custom web applications other than Kibana.\nIf you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.\n\nThis API returns a URL pointing to the SAML Identity Provider.\nYou can use the URL to redirect the browser of the user in order to continue the authentication process.\nThe URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded.\nIf the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`.\nThese parameters contain the algorithm used for the signature and the signature value itself.\nIt also returns a random string that uniquely identifies this SAML Authentication request.\nThe caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process.", "inherits": { "type": { "name": "RequestBase", @@ -204242,7 +204268,7 @@ }, "path": [], "query": [], - "specLocation": "security/saml_prepare_authentication/Request.ts#L22-L55" + "specLocation": "security/saml_prepare_authentication/Request.ts#L22-L67" }, { "kind": "response", @@ -204250,6 +204276,7 @@ "kind": "properties", "properties": [ { + "description": "A unique identifier for the SAML Request to be stored by the caller of the API.", "name": "id", "required": true, "type": { @@ -204261,6 +204288,7 @@ } }, { + "description": "The name of the Elasticsearch realm that was used to construct the authentication request.", "name": "realm", "required": true, "type": { @@ -204272,6 +204300,7 @@ } }, { + "description": "The URL to redirect the user to.", "name": "redirect", "required": true, "type": { @@ -204288,7 +204317,7 @@ "name": "Response", "namespace": "security.saml_prepare_authentication" }, - "specLocation": "security/saml_prepare_authentication/Response.ts#L22-L28" + "specLocation": "security/saml_prepare_authentication/Response.ts#L22-L37" }, { "kind": "request", @@ -204298,7 +204327,7 @@ "body": { "kind": "no_body" }, - "description": "Create SAML service provider metadata.\n\nGenerate SAML metadata for a SAML 2.0 Service Provider.", + "description": "Create SAML service provider metadata.\n\nGenerate SAML metadata for a SAML 2.0 Service Provider.\n\nThe SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file.\nThis API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch.", "inherits": { "type": { "name": "RequestBase", @@ -204324,7 +204353,7 @@ } ], "query": [], - "specLocation": "security/saml_service_provider_metadata/Request.ts#L23-L43" + "specLocation": "security/saml_service_provider_metadata/Request.ts#L23-L46" }, { "kind": "response", @@ -204332,6 +204361,7 @@ "kind": "properties", "properties": [ { + "description": "An XML string that contains a SAML Service Provider's metadata for the realm.", "name": "metadata", "required": true, "type": { @@ -204348,7 +204378,7 @@ "name": "Response", "namespace": "security.saml_service_provider_metadata" }, - "specLocation": "security/saml_service_provider_metadata/Response.ts#L20-L24" + "specLocation": "security/saml_service_provider_metadata/Response.ts#L20-L27" }, { "kind": "interface", @@ -204358,7 +204388,7 @@ }, "properties": [ { - "description": "A list of Profile UIDs to match against.", + "description": "A list of profile UIDs to match against.", "name": "uids", "required": false, "type": { @@ -204422,7 +204452,7 @@ "kind": "properties", "properties": [ { - "description": "Query string used to match name-related fields in user profile documents.\nName-related fields are the user's `username`, `full_name`, and `email`.", + "description": "A query string used to match name-related fields in user profile documents.\nName-related fields are the user's `username`, `full_name`, and `email`.", "name": "name", "required": false, "type": { @@ -204434,7 +204464,7 @@ } }, { - "description": "Number of profiles to return.", + "description": "The number of profiles to return.", "name": "size", "required": false, "serverDefault": 10, @@ -204447,7 +204477,7 @@ } }, { - "description": "List of filters for the `data` field of the profile document.\nTo return all content use `data=*`. To return a subset of content\nuse `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", + "description": "A comma-separated list of filters for the `data` field of the profile document.\nTo return all content use `data=*`.\nTo return a subset of content, use `data=` to retrieve content nested under the specified ``.\nBy default, the API returns no `data` content.\nIt is an error to specify `data` as both the query parameter and the request body field.", "name": "data", "required": false, "type": { @@ -204474,7 +204504,7 @@ } }, { - "description": "Extra search criteria to improve relevance of the suggestion result.\nProfiles matching the spcified hint are ranked higher in the response.\nProfiles not matching the hint don't exclude the profile from the response\nas long as the profile matches the `name` field query.", + "description": "Extra search criteria to improve relevance of the suggestion result.\nProfiles matching the spcified hint are ranked higher in the response.\nProfiles not matching the hint aren't excluded from the response as long as the profile matches the `name` field query.", "name": "hint", "required": false, "type": { @@ -204487,7 +204517,7 @@ } ] }, - "description": "Suggest a user profile.\n\nGet suggestions for user profiles that match specified search criteria.", + "description": "Suggest a user profile.\n\nGet suggestions for user profiles that match specified search criteria.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.", "inherits": { "type": { "name": "RequestBase", @@ -204501,7 +204531,7 @@ "path": [], "query": [ { - "description": "List of filters for the `data` field of the profile document.\nTo return all content use `data=*`. To return a subset of content\nuse `data=` to retrieve content nested under the specified ``.\nBy default returns no `data` content.", + "description": "A comma-separated list of filters for the `data` field of the profile document.\nTo return all content use `data=*`.\nTo return a subset of content, use `data=` to retrieve content nested under the specified ``.\nBy default, the API returns no `data` content.\nIt is an error to specify `data` as both the query parameter and the request body field.", "name": "data", "required": false, "type": { @@ -204528,7 +204558,7 @@ } } ], - "specLocation": "security/suggest_user_profiles/Request.ts#L24-L76" + "specLocation": "security/suggest_user_profiles/Request.ts#L24-L81" }, { "kind": "response", @@ -204536,6 +204566,7 @@ "kind": "properties", "properties": [ { + "description": "Metadata about the number of matching profiles.", "name": "total", "required": true, "type": { @@ -204547,6 +204578,7 @@ } }, { + "description": "The number of milliseconds it took Elasticsearch to run the request.", "name": "took", "required": true, "type": { @@ -204558,6 +204590,7 @@ } }, { + "description": "A list of profile documents, ordered by relevance, that match the search criteria.", "name": "profiles", "required": true, "type": { @@ -204577,7 +204610,7 @@ "name": "Response", "namespace": "security.suggest_user_profiles" }, - "specLocation": "security/suggest_user_profiles/Response.ts#L29-L35" + "specLocation": "security/suggest_user_profiles/Response.ts#L29-L44" }, { "kind": "interface", @@ -204744,7 +204777,7 @@ } }, { - "description": "Expiration time for the API key.\nBy default, API keys never expire. This property can be omitted to leave the value unchanged.", + "description": "The expiration time for the API key.\nBy default, API keys never expire. This property can be omitted to leave the value unchanged.", "name": "expiration", "required": false, "type": { @@ -204769,7 +204802,7 @@ } ] }, - "description": "Update a cross-cluster API key.\n\nUpdate the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.", + "description": "Update a cross-cluster API key.\n\nUpdate the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.\n\nTo use this API, you must have at least the `manage_security` cluster privilege.\nUsers can only update API keys that they created.\nTo update another user's API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user's credentials are required.\n\nIt's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API.\n\nThis API supports updates to an API key's access scope, metadata, and expiration.\nThe owner user's information, such as the `username` and `realm`, is also updated automatically on every call.\n\nNOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API.", "inherits": { "type": { "name": "RequestBase", @@ -204795,7 +204828,7 @@ } ], "query": [], - "specLocation": "security/update_cross_cluster_api_key/UpdateCrossClusterApiKeyRequest.ts#L25-L69" + "specLocation": "security/update_cross_cluster_api_key/UpdateCrossClusterApiKeyRequest.ts#L25-L83" }, { "kind": "response", @@ -204868,7 +204901,7 @@ } ] }, - "description": "Update security index settings.\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", + "description": "Update security index settings.\n\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", "inherits": { "type": { "name": "RequestBase", @@ -204906,7 +204939,7 @@ } } ], - "specLocation": "security/update_settings/SecurityUpdateSettingsRequest.ts#L24-L67" + "specLocation": "security/update_settings/SecurityUpdateSettingsRequest.ts#L24-L68" }, { "kind": "response", @@ -204941,7 +204974,7 @@ "kind": "properties", "properties": [ { - "description": "Searchable data that you want to associate with the user profile. This\nfield supports a nested data structure.", + "description": "Searchable data that you want to associate with the user profile.\nThis field supports a nested data structure.\nWithin the labels object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`).", "name": "labels", "required": false, "type": { @@ -204960,7 +204993,7 @@ } }, { - "description": "Non-searchable data that you want to associate with the user profile.\nThis field supports a nested data structure.", + "description": "Non-searchable data that you want to associate with the user profile.\nThis field supports a nested data structure.\nWithin the `data` object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`).\nThe data object is not searchable, but can be retrieved with the get user profile API.", "name": "data", "required": false, "type": { @@ -204980,7 +205013,7 @@ } ] }, - "description": "Update user profile data.\n\nUpdate specific data for the user profile that is associated with a unique ID.", + "description": "Update user profile data.\n\nUpdate specific data for the user profile that is associated with a unique ID.\n\nNOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.\nIndividual users and external applications should not call this API directly.\nElastic reserves the right to change or remove this feature in future releases without prior notice.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_user_profile` cluster privilege.\n* The `update_profile_data` global privilege for the namespaces that are referenced in the request.\n\nThis API updates the `labels` and `data` fields of an existing user profile document with JSON objects.\nNew keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request.\n\nFor both labels and data, content is namespaced by the top-level fields.\nThe `update_profile_data` global privilege grants privileges for updating only the allowed namespaces.", "inherits": { "type": { "name": "RequestBase", @@ -205031,7 +205064,7 @@ } }, { - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', nothing is done with refreshes.", "name": "refresh", "required": false, "serverDefault": "false", @@ -205044,7 +205077,7 @@ } } ], - "specLocation": "security/update_user_profile_data/Request.ts#L27-L79" + "specLocation": "security/update_user_profile_data/Request.ts#L27-L98" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 028fc625e6..cd936f26a9 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -672,9 +672,10 @@ security-api-suggest,https://www.elastic.co/guide/en/elasticsearch/reference/{br security-api-cross-cluster-key-update,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-cross-cluster-api-key.html security-api-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-api-key.html security-api-update-user-data,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-user-profile-data.html -security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html security-api-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html security-encrypt-internode,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-basic-setup.html#encrypt-internode-communication +security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html +security-saml-guide,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html diff --git a/specification/security/_types/GrantType.ts b/specification/security/_types/GrantType.ts index e3411467c3..0868c96137 100644 --- a/specification/security/_types/GrantType.ts +++ b/specification/security/_types/GrantType.ts @@ -24,6 +24,7 @@ export enum GrantType { password, /** * In this type of grant, you must supply an access token that was created by the Elasticsearch token service. + * If you are activating a user profile, you can alternatively supply a JWT (either a JWT `access_token` or a JWT `id_token`). */ access_token } diff --git a/specification/security/activate_user_profile/Request.ts b/specification/security/activate_user_profile/Request.ts index 55ce17dfdd..0a0c25a840 100644 --- a/specification/security/activate_user_profile/Request.ts +++ b/specification/security/activate_user_profile/Request.ts @@ -24,6 +24,17 @@ import { RequestBase } from '@_types/Base' * Activate a user profile. * * Create or update a user profile on behalf of another user. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + * Individual users and external applications should not call this API directly. + * The calling application must have either an `access_token` or a combination of `username` and `password` for the user that the profile document is intended for. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. + * + * This API creates or updates a profile document for end users with information that is extracted from the user's authentication object including `username`, `full_name,` `roles`, and the authentication realm. + * For example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token. + * + * When updating a profile document, the API enables the document if it was disabled. + * Any updates do not change existing content for either the `labels` or `data` fields. * @rest_spec_name security.activate_user_profile * @availability stack since=8.2.0 stability=stable * @availability serverless stability=stable visibility=private @@ -38,9 +49,28 @@ export interface Request extends RequestBase { } ] body: { + /** + * The user's Elasticsearch access token or JWT. + * Both `access` and `id` JWT token types are supported and they depend on the underlying JWT realm configuration. + * If you specify the `access_token` grant type, this parameter is required. + * It is not valid with other grant types. + */ access_token?: string + /** + * The type of grant. + */ grant_type: GrantType + /** + * The user's password. + * If you specify the `password` grant type, this parameter is required. + * It is not valid with other grant types. + */ password?: string + /** + * The username that identifies the user. + * If you specify the `password` grant type, this parameter is required. + * It is not valid with other grant types. + */ username?: string } } diff --git a/specification/security/activate_user_profile/examples/request/RequestExample1.yaml b/specification/security/activate_user_profile/examples/request/RequestExample1.yaml index ee76cbe16e..c7a0baf0af 100644 --- a/specification/security/activate_user_profile/examples/request/RequestExample1.yaml +++ b/specification/security/activate_user_profile/examples/request/RequestExample1.yaml @@ -1,15 +1,11 @@ # summary: -# method_request: POST /_security/user/jacknich +# method_request: POST /_security/profile/_activate description: > - Run `POST /_security/user/jacknich` to create a user. + Run `POST /_security/profile/_activate` to activate a user profile. # type: request value: |- { - "password" : "l0ng-r4nd0m-p@ssw0rd", - "roles" : [ "admin", "other_role1" ], - "full_name" : "Jack Nicholson", - "email" : "jacknich@example.com", - "metadata" : { - "intelligence" : 7 - } + "grant_type": "password", + "username" : "jacknich", + "password" : "l0ng-r4nd0m-p@ssw0rd" } diff --git a/specification/security/disable_user_profile/Request.ts b/specification/security/disable_user_profile/Request.ts index bc145b4765..ebf6f51b14 100644 --- a/specification/security/disable_user_profile/Request.ts +++ b/specification/security/disable_user_profile/Request.ts @@ -25,10 +25,18 @@ import { Refresh } from '@_types/common' * Disable a user profile. * * Disable user profiles so that they are not visible in user profile searches. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + * Individual users and external applications should not call this API directly. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. + * + * When you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches. + * To re-enable a disabled user profile, use the enable user profile API . * @rest_spec_name security.disable_user_profile * @availability stack since=8.2.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_user_profile + * @doc_id security-api-disable-user-profile */ export interface Request extends RequestBase { urls: [ @@ -45,9 +53,9 @@ export interface Request extends RequestBase { } query_parameters: { /** - * If 'true', Elasticsearch refreshes 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' do nothing with refreshes. + * If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. + * If 'wait_for', it waits for a refresh to make this operation visible to search. + * If 'false', it does nothing with refreshes. * @server_default false */ refresh?: Refresh diff --git a/specification/security/enable_user_profile/Request.ts b/specification/security/enable_user_profile/Request.ts index f087fc0369..ecc937797b 100644 --- a/specification/security/enable_user_profile/Request.ts +++ b/specification/security/enable_user_profile/Request.ts @@ -25,6 +25,13 @@ import { Refresh } from '@_types/common' * Enable a user profile. * * Enable user profiles to make them visible in user profile searches. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + * Individual users and external applications should not call this API directly. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. + * + * When you activate a user profile, it's automatically enabled and visible in user profile searches. + * If you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again. * @rest_spec_name security.enable_user_profile * @availability stack since=8.2.0 stability=stable * @availability serverless stability=stable visibility=private @@ -40,15 +47,16 @@ export interface Request extends RequestBase { ] path_parts: { /** - * Unique identifier for the user profile. + * A unique identifier for the user profile. */ uid: UserProfileId } query_parameters: { /** * If 'true', Elasticsearch refreshes 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' do nothing with refreshes. + * visible to search. + * If 'wait_for', it waits for a refresh to make this operation visible to search. + * If 'false', nothing is done with refreshes. * @server_default false */ refresh?: Refresh diff --git a/specification/security/get_user_profile/Request.ts b/specification/security/get_user_profile/Request.ts index 6414800aa7..6d402326a2 100644 --- a/specification/security/get_user_profile/Request.ts +++ b/specification/security/get_user_profile/Request.ts @@ -24,10 +24,14 @@ import { RequestBase } from '@_types/Base' * Get a user profile. * * Get a user's profile using the unique profile ID. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + * Individual users and external applications should not call this API directly. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. * @rest_spec_name security.get_user_profile * @availability stack since=8.2.0 stability=stable * @availability serverless stability=stable visibility=private - * @cluster_privileges manage_user_profile + * @cluster_privileges read_security * @doc_id security-api-get-user-profile */ export interface Request extends RequestBase { @@ -45,9 +49,9 @@ export interface Request extends RequestBase { } query_parameters: { /** - * List of filters for the `data` field of the profile document. - * To return all content use `data=*`. To return a subset of content - * use `data=` to retrieve content nested under the specified ``. + * A comma-separated list of filters for the `data` field of the profile document. + * To return all content use `data=*`. + * To return a subset of content use `data=` to retrieve content nested under the specified ``. * By default returns no `data` content. */ data?: string | string[] diff --git a/specification/security/get_user_profile/Response.ts b/specification/security/get_user_profile/Response.ts index c614d12187..39abc2ec4e 100644 --- a/specification/security/get_user_profile/Response.ts +++ b/specification/security/get_user_profile/Response.ts @@ -22,6 +22,11 @@ import { GetUserProfileErrors } from './types' export class Response { body: { + /** + * A successful call returns the JSON representation of the user profile and its internal versioning numbers. + * The API returns an empty object if no profile document is found for the provided `uid`. + * The content of the data field is not returned by default to avoid deserializing a potential large payload. + */ profiles: UserProfileWithMetadata[] errors?: GetUserProfileErrors } diff --git a/specification/security/has_privileges_user_profile/Request.ts b/specification/security/has_privileges_user_profile/Request.ts index 9c659f1ad6..61fbd869ac 100644 --- a/specification/security/has_privileges_user_profile/Request.ts +++ b/specification/security/has_privileges_user_profile/Request.ts @@ -25,6 +25,9 @@ import { PrivilegesCheck } from './types' * Check user profile privileges. * * Determine whether the users associated with the specified user profile IDs have all the requested privileges. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. * @rest_spec_name security.has_privileges_user_profile * @availability stack since=8.3.0 stability=stable * @availability serverless stability=stable visibility=private @@ -44,6 +47,9 @@ export interface Request extends RequestBase { * A list of profile IDs. The privileges are checked for associated users of the profiles. */ uids: UserProfileId[] + /** + * An object containing all the privileges to be checked. + */ privileges: PrivilegesCheck } } diff --git a/specification/security/has_privileges_user_profile/examples/request/RequestExample1.yaml b/specification/security/has_privileges_user_profile/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..aed6d5b4dc --- /dev/null +++ b/specification/security/has_privileges_user_profile/examples/request/RequestExample1.yaml @@ -0,0 +1,33 @@ +# summary: +# method_request: POST /_security/profile/_has_privileges +description: > + Run `POST /_security/profile/_has_privileges` to check whether the two users associated with the specified profiles have all the requested set of cluster, index, and application privileges. +# type: request +value: |- + { + "uids": [ + "u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0", + "u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1", + "u_does-not-exist_0" + ], + "privileges": { + "cluster": [ "monitor", "create_snapshot", "manage_ml" ], + "index" : [ + { + "names": [ "suppliers", "products" ], + "privileges": [ "create_doc"] + }, + { + "names": [ "inventory" ], + "privileges" : [ "read", "write" ] + } + ], + "application": [ + { + "application": "inventory_manager", + "privileges" : [ "read", "data:write/inventory" ], + "resources" : [ "product/1852563" ] + } + ] + } + } diff --git a/specification/security/has_privileges_user_profile/examples/response/ResponseExample1.yaml b/specification/security/has_privileges_user_profile/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..1d8a647fbd --- /dev/null +++ b/specification/security/has_privileges_user_profile/examples/response/ResponseExample1.yaml @@ -0,0 +1,18 @@ +# summary: +description: > + A response from `POST /_security/profile/_has_privileges` that indicates only one of the three users has all the privileges and one of them is not found. +# type: response +# response_code: +value: |- + { + "has_privilege_uids": ["u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"], + "errors": { + "count": 1, + "details": { + "u_does-not-exist_0": { + "type": "resource_not_found_exception", + "reason": "profile document not found" + } + } + } + } diff --git a/specification/security/saml_authenticate/Request.ts b/specification/security/saml_authenticate/Request.ts index 5785f9444d..203fd5bf30 100644 --- a/specification/security/saml_authenticate/Request.ts +++ b/specification/security/saml_authenticate/Request.ts @@ -23,11 +23,25 @@ import { Ids } from '@_types/common' /** * Authenticate SAML. * - * Submits a SAML response message to Elasticsearch for consumption. + * Submit a SAML response message to Elasticsearch for consumption. + * + * NOTE: This API is intended for use by custom web applications other than Kibana. + * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + * + * The SAML message that is submitted can be: + * + * * A response to a SAML authentication request that was previously created using the SAML prepare authentication API. + * * An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow. + * + * In either case, the SAML message needs to be a base64 encoded XML document with a root element of ``. + * + * After successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. + * This API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch. * @rest_spec_name security.saml_authenticate * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private * @doc_id security-api-saml-authenticate + * @ext_doc_id security-saml-guide */ export interface Request extends RequestBase { urls: [ @@ -37,9 +51,9 @@ export interface Request extends RequestBase { } ] body: { - /** The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document. */ + /** The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document. */ content: string - /** A json array with all the valid SAML Request Ids that the caller of the API has for the current user. */ + /** A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. */ ids: Ids /** The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined. */ realm?: string diff --git a/specification/security/saml_authenticate/Response.ts b/specification/security/saml_authenticate/Response.ts index 21f5546389..3acbf6117e 100644 --- a/specification/security/saml_authenticate/Response.ts +++ b/specification/security/saml_authenticate/Response.ts @@ -21,10 +21,25 @@ import { integer } from '@_types/Numeric' export class Response { body: { + /** + * The access token that was generated by Elasticsearch. + */ access_token: string + /** + * The authenticated user's name. + */ username: string + /** + * The amount of time (in seconds) left until the token expires. + */ expires_in: integer + /** + * The refresh token that was generated by Elasticsearch. + */ refresh_token: string + /** + * The name of the realm where the user was authenticated. + */ realm: string } } diff --git a/specification/security/saml_authenticate/examples/request/RequestExample1.yaml b/specification/security/saml_authenticate/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..ef77f13e2f --- /dev/null +++ b/specification/security/saml_authenticate/examples/request/RequestExample1.yaml @@ -0,0 +1,10 @@ +# summary: +# method_request: POST /_security/saml/authenticate +description: > + Run `POST /_security/saml/authenticate` to exchange a SAML Response indicating a successful authentication at the SAML IdP for an Elasticsearch access token and refresh token to be used in subsequent requests. +# type: request +value: |- + { + "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....", + "ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"] + } diff --git a/specification/security/saml_authenticate/examples/response/ResponseExample1.yaml b/specification/security/saml_authenticate/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..3ae3fd4e7b --- /dev/null +++ b/specification/security/saml_authenticate/examples/response/ResponseExample1.yaml @@ -0,0 +1,12 @@ +# summary: +description: A successful response from `POST /_security/saml/authenticate`. +# type: response +# response_code: +value: |- + { + "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3", + "username" : "Bearer", + "expires_in" : 1200, + "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w", + "realm": "saml1" + } diff --git a/specification/security/saml_complete_logout/Request.ts b/specification/security/saml_complete_logout/Request.ts index dca7a43c76..123972015c 100644 --- a/specification/security/saml_complete_logout/Request.ts +++ b/specification/security/saml_complete_logout/Request.ts @@ -24,10 +24,20 @@ import { Ids } from '@_types/common' * Logout of SAML completely. * * Verifies the logout response sent from the SAML IdP. + * + * NOTE: This API is intended for use by custom web applications other than Kibana. + * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + * + * The SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout. + * This API verifies the response by ensuring the content is relevant and validating its signature. + * An empty response is returned if the verification process is successful. + * The response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding. + * The caller of this API must prepare the request accordingly so that this API can handle either of them. * @rest_spec_name security.saml_complete_logout * @availability stack since=7.14.0 stability=stable * @availability serverless stability=stable visibility=private * @doc_id security-api-saml-complete-logout + * @ext_doc_id security-saml-guide */ export interface Request extends RequestBase { urls: [ @@ -39,9 +49,11 @@ export interface Request extends RequestBase { body: { /** The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response. */ realm: string - /** A json array with all the valid SAML Request Ids that the caller of the API has for the current user. */ + /** A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. */ ids: Ids - /** If the SAML IdP sends the logout response with the HTTP-Redirect binding, this field must be set to the query string of the redirect URI. */ + /** + * If the SAML IdP sends the logout response with the HTTP-Redirect binding, this field must be set to the query string of the redirect URI. + */ query_string?: string /** If the SAML IdP sends the logout response with the HTTP-Post binding, this field must be set to the value of the SAMLResponse form parameter from the logout response. */ content?: string diff --git a/specification/security/saml_complete_logout/Response.ts b/specification/security/saml_complete_logout/Response.ts index cf4f9c0d87..b21dab8cb4 100644 --- a/specification/security/saml_complete_logout/Response.ts +++ b/specification/security/saml_complete_logout/Response.ts @@ -20,5 +20,8 @@ import { Void } from '@spec_utils/VoidValue' export class Response { + /** + * The API returns an empty response on success. + */ body: Void } diff --git a/specification/security/saml_complete_logout/examples/request/RequestExample1.yaml b/specification/security/saml_complete_logout/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..53e8a46361 --- /dev/null +++ b/specification/security/saml_complete_logout/examples/request/RequestExample1.yaml @@ -0,0 +1,11 @@ +summary: HTTP-Redirect binding +# method_request: POST /_security/saml/complete_logout +description: > + Run `POST /_security/saml/complete_logout` to verify the logout response sent by the SAML IdP using the HTTP-Redirect binding. +# type: request +value: |- + { + "realm": "saml1", + "ids": [ "_1c368075e0b3..." ], + "query_string": "SAMLResponse=fZHLasMwEEVbfb1bf...&SigAlg=http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23rsa-sha1&Signature=CuCmFn%2BLqnaZGZJqK..." + } diff --git a/specification/security/saml_complete_logout/examples/request/RequestExample2.yaml b/specification/security/saml_complete_logout/examples/request/RequestExample2.yaml new file mode 100644 index 0000000000..85f97bba29 --- /dev/null +++ b/specification/security/saml_complete_logout/examples/request/RequestExample2.yaml @@ -0,0 +1,11 @@ +summary: HTTP-Post binding +# method_request: POST /_security/saml/complete_logout +description: > + Run `POST /_security/saml/complete_logout` to verify the logout response sent by the SAML IdP using the HTTP-Post binding. +# type: request +value: |- + { + "realm": "saml1", + "ids": [ "_1c368075e0b3..." ], + "content": "PHNhbWxwOkxvZ291dFJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46..." + } diff --git a/specification/security/saml_invalidate/Request.ts b/specification/security/saml_invalidate/Request.ts index 756b7dc3b8..7671a0877b 100644 --- a/specification/security/saml_invalidate/Request.ts +++ b/specification/security/saml_invalidate/Request.ts @@ -22,11 +22,20 @@ import { RequestBase } from '@_types/Base' /** * Invalidate SAML. * - * Submits a SAML LogoutRequest message to Elasticsearch for consumption. + * Submit a SAML LogoutRequest message to Elasticsearch for consumption. + * + * NOTE: This API is intended for use by custom web applications other than Kibana. + * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + * + * The logout request comes from the SAML IdP during an IdP initiated Single Logout. + * The custom web application can use this API to have Elasticsearch process the `LogoutRequest`. + * After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message. + * Thus the user can be redirected back to their IdP. * @rest_spec_name security.saml_invalidate * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private * @doc_id security-api-saml-invalidate + * @ext_doc_id security-saml-guide */ export interface Request extends RequestBase { urls: [ @@ -36,17 +45,17 @@ export interface Request extends RequestBase { } ] body: { - /** The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter. */ + /** The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the `realm` parameter. */ acs?: string /** * The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. - * This query should include a single parameter named SAMLRequest that contains a SAML logout request that is deflated and Base64 encoded. - * If the SAML IdP has signed the logout request, the URL should include two extra parameters named SigAlg and Signature that contain the algorithm used for the signature and the signature value itself. - * In order for Elasticsearch to be able to verify the IdP’s signature, the value of the query_string field must be an exact match to the string provided by the browser. + * This query should include a single parameter named `SAMLRequest` that contains a SAML logout request that is deflated and Base64 encoded. + * If the SAML IdP has signed the logout request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value itself. + * In order for Elasticsearch to be able to verify the IdP's signature, the value of the `query_string` field must be an exact match to the string provided by the browser. * The client application must not attempt to parse or process the string in any way. */ query_string: string - /** The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter. */ + /** The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the `acs` parameter. */ realm?: string } } diff --git a/specification/security/saml_invalidate/Response.ts b/specification/security/saml_invalidate/Response.ts index 4e08a622da..1124806815 100644 --- a/specification/security/saml_invalidate/Response.ts +++ b/specification/security/saml_invalidate/Response.ts @@ -21,8 +21,17 @@ import { integer } from '@_types/Numeric' export class Response { body: { + /** + * The number of tokens that were invalidated as part of this logout. + */ invalidated: integer + /** + * The realm name of the SAML realm in Elasticsearch that authenticated the user. + */ realm: string + /** + * A SAML logout response as a parameter so that the user can be redirected back to the SAML IdP. + */ redirect: string } } diff --git a/specification/security/saml_invalidate/examples/request/RequestExample1.yaml b/specification/security/saml_invalidate/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..d756bef664 --- /dev/null +++ b/specification/security/saml_invalidate/examples/request/RequestExample1.yaml @@ -0,0 +1,10 @@ +# summary: +# method_request: POST /_security/saml/invalidate +description: > + Run `POST /_security/saml/invalidate` to invalidate all the tokens for realm `saml1` pertaining to the user that is identified in the SAML Logout Request. +# type: request +value: |- + { + "query_string" : "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D", + "realm" : "saml1" + } diff --git a/specification/security/saml_invalidate/examples/response/ResponseExample1.yaml b/specification/security/saml_invalidate/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..2899590d6d --- /dev/null +++ b/specification/security/saml_invalidate/examples/response/ResponseExample1.yaml @@ -0,0 +1,10 @@ +# summary: +description: A successful response from `POST /_security/saml/invalidate`. +# type: response +# response_code: +value: |- + { + "redirect" : "https://my-idp.org/logout/SAMLResponse=....", + "invalidated" : 2, + "realm" : "saml1" + } diff --git a/specification/security/saml_logout/Request.ts b/specification/security/saml_logout/Request.ts index 179a0c0e2b..cd687e85e3 100644 --- a/specification/security/saml_logout/Request.ts +++ b/specification/security/saml_logout/Request.ts @@ -23,10 +23,17 @@ import { RequestBase } from '@_types/Base' * Logout of SAML. * * Submits a request to invalidate an access token and refresh token. + * + * NOTE: This API is intended for use by custom web applications other than Kibana. + * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + * + * This API invalidates the tokens that were generated for a user by the SAML authenticate API. + * If the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout). * @rest_spec_name security.saml_logout * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private * @doc_id security-api-saml-logout + * @ext_doc_id security-saml-guide */ export interface Request extends RequestBase { urls: [ @@ -38,7 +45,7 @@ export interface Request extends RequestBase { body: { /** * The access token that was returned as a response to calling the SAML authenticate API. - * Alternatively, the most recent token that was received after refreshing the original one by using a refresh_token. + * Alternatively, the most recent token that was received after refreshing the original one by using a `refresh_token`. */ token: string /** diff --git a/specification/security/saml_logout/Response.ts b/specification/security/saml_logout/Response.ts index 61993b90cd..ac36e974a2 100644 --- a/specification/security/saml_logout/Response.ts +++ b/specification/security/saml_logout/Response.ts @@ -19,6 +19,10 @@ export class Response { body: { + /** + * A URL that contains a SAML logout request as a parameter. + * You can use this URL to be redirected back to the SAML IdP and to initiate Single Logout. + */ redirect: string } } diff --git a/specification/security/saml_logout/examples/request/RequestExample1.yaml b/specification/security/saml_logout/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..0ded95d5bb --- /dev/null +++ b/specification/security/saml_logout/examples/request/RequestExample1.yaml @@ -0,0 +1,10 @@ +# summary: +# method_request: POST /_security/saml/logout +description: > + Run `POST /_security/saml/logout` to invalidate the pair of tokens that were generated by calling the SAML authenticate API with a successful SAML response. +# type: request +value: |- + { + "token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3", + "refresh_token" : "mJdXLtmvTUSpoLwMvdBt_w" + } diff --git a/specification/security/saml_logout/examples/response/ResponseExample1.yaml b/specification/security/saml_logout/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..aeb66c7ff5 --- /dev/null +++ b/specification/security/saml_logout/examples/response/ResponseExample1.yaml @@ -0,0 +1,8 @@ +# summary: +description: A successful response from `POST /_security/saml/logout`. +# type: response +# response_code: +value: |- + { + "redirect" : "https://my-idp.org/logout/SAMLRequest=...." + } diff --git a/specification/security/saml_prepare_authentication/Request.ts b/specification/security/saml_prepare_authentication/Request.ts index d40d2e4c17..410cc0d849 100644 --- a/specification/security/saml_prepare_authentication/Request.ts +++ b/specification/security/saml_prepare_authentication/Request.ts @@ -22,11 +22,23 @@ import { RequestBase } from '@_types/Base' /** * Prepare SAML authentication. * - * Creates a SAML authentication request (``) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch. + * Create a SAML authentication request (``) as a URL string based on the configuration of the respective SAML realm in Elasticsearch. + * + * NOTE: This API is intended for use by custom web applications other than Kibana. + * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + * + * This API returns a URL pointing to the SAML Identity Provider. + * You can use the URL to redirect the browser of the user in order to continue the authentication process. + * The URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded. + * If the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`. + * These parameters contain the algorithm used for the signature and the signature value itself. + * It also returns a random string that uniquely identifies this SAML Authentication request. + * The caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process. * @rest_spec_name security.saml_prepare_authentication * @availability stack since=7.5.0 stability=stable * @availability serverless stability=stable visibility=private * @doc_id security-api-saml-prepare-authentication + * @ext_doc_id security-saml-guide */ export interface Request extends RequestBase { urls: [ @@ -38,16 +50,16 @@ export interface Request extends RequestBase { body: { /** * The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch. - * The realm is used to generate the authentication request. You must specify either this parameter or the realm parameter. + * The realm is used to generate the authentication request. You must specify either this parameter or the `realm` parameter. */ acs?: string /** * The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request. - * You must specify either this parameter or the acs parameter. + * You must specify either this parameter or the `acs` parameter. */ realm?: string /** - * A string that will be included in the redirect URL that this API returns as the RelayState query parameter. + * A string that will be included in the redirect URL that this API returns as the `RelayState` query parameter. * If the Authentication Request is signed, this value is used as part of the signature computation. */ relay_state?: string diff --git a/specification/security/saml_prepare_authentication/Response.ts b/specification/security/saml_prepare_authentication/Response.ts index 841b78ad0c..7efc741866 100644 --- a/specification/security/saml_prepare_authentication/Response.ts +++ b/specification/security/saml_prepare_authentication/Response.ts @@ -21,8 +21,17 @@ import { Id } from '@_types/common' export class Response { body: { + /** + * A unique identifier for the SAML Request to be stored by the caller of the API. + */ id: Id + /** + * The name of the Elasticsearch realm that was used to construct the authentication request. + */ realm: string + /** + * The URL to redirect the user to. + */ redirect: string } } diff --git a/specification/security/saml_prepare_authentication/examples/request/RequestExample1.yaml b/specification/security/saml_prepare_authentication/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..fbefdaf862 --- /dev/null +++ b/specification/security/saml_prepare_authentication/examples/request/RequestExample1.yaml @@ -0,0 +1,9 @@ +summary: Prepare with a realm +# method_request: POST /_security/saml/prepare +description: > + Run `POST /_security/saml/prepare` to generate a SAML authentication request for the SAML realm named `saml1`. +# type: request +value: |- + { + "realm" : "saml1" + } diff --git a/specification/security/saml_prepare_authentication/examples/request/RequestExample2.yaml b/specification/security/saml_prepare_authentication/examples/request/RequestExample2.yaml new file mode 100644 index 0000000000..2ca6dfe1bb --- /dev/null +++ b/specification/security/saml_prepare_authentication/examples/request/RequestExample2.yaml @@ -0,0 +1,9 @@ +summary: Prepare with an ACS +# method_request: POST /_security/saml/prepare +description: > + Run `POST /_security/saml/prepare` to generate a SAML authentication request for the SAML realm with an Assertion Consuming Service (ACS) URL. +# type: request +value: |- + { + "acs" : "https://kibana.org/api/security/saml/callback" + } diff --git a/specification/security/saml_prepare_authentication/examples/response/ResponseExample1.yaml b/specification/security/saml_prepare_authentication/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..9350f0da91 --- /dev/null +++ b/specification/security/saml_prepare_authentication/examples/response/ResponseExample1.yaml @@ -0,0 +1,10 @@ +# summary: +description: A successful response from `POST /_security/saml/prepare`. +# type: response +# response_code: +value: |- + { + "redirect": "https://my-idp.org/login?SAMLRequest=fVJdc6IwFP0rmbwDgUKLGbFDtc462%2B06FX3Yl50rBJsKCZsbrPbXL6J22hdfk%2FNx7zl3eL%2BvK7ITBqVWCfVdRolQuS6k2iR0mU2dmN6Phgh1FTQ8be2rehH%2FWoGWdESF%2FPST0NYorgElcgW1QG5zvkh%2FPfHAZbwx2upcV5SkiMLYzmqsFba1MAthdjIXy5enhL5a23DPOyo6W7kGBa7cwhZ2gO7G8OiW%2BR400kORt0bag7fzezAlk24eqcD2OxxlsNN5O3MdsW9c6CZnbq7rntF4d3s0D7BaHTZhIWN52P%2BcjiuGRbDU6cdj%2BEjJbJLQv4N4ADdhxBiEZbQuWclY4Q8iABbCXczCdSiKMAC%2FgyO2YqbQgrIJDZg%2FcFjsMD%2Fzb3gUcBa5sR%2F9oWR%2BzuJBqlPG14Jbn0DIf2TZ3Jn%2FXmSUrC5ddQB6bob37uZrJdeF4dIDHV3iuhb70Ptq83kOz53ubDLXlcwPJK0q%2FT42AqxIaAkVCkqm2tRgr49yfJGFU%2FZQ3hy3QyuUpd7obPv97kb%2FAQ%3D%3D"}", + "realm": "saml1", + "id": "_989a34500a4f5bf0f00d195aa04a7804b4ed42a1" + } diff --git a/specification/security/saml_service_provider_metadata/Request.ts b/specification/security/saml_service_provider_metadata/Request.ts index d1451bea3b..2c48e2af00 100644 --- a/specification/security/saml_service_provider_metadata/Request.ts +++ b/specification/security/saml_service_provider_metadata/Request.ts @@ -24,6 +24,9 @@ import { Name } from '@_types/common' * Create SAML service provider metadata. * * Generate SAML metadata for a SAML 2.0 Service Provider. + * + * The SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file. + * This API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch. * @rest_spec_name security.saml_service_provider_metadata * @availability stack since=7.11.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/security/saml_service_provider_metadata/Response.ts b/specification/security/saml_service_provider_metadata/Response.ts index f52157b775..3fa79f5d0c 100644 --- a/specification/security/saml_service_provider_metadata/Response.ts +++ b/specification/security/saml_service_provider_metadata/Response.ts @@ -19,6 +19,9 @@ export class Response { body: { + /** + * An XML string that contains a SAML Service Provider's metadata for the realm. + */ metadata: string } } diff --git a/specification/security/saml_service_provider_metadata/examples/response/ResponseExample1.yaml b/specification/security/saml_service_provider_metadata/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..d95c6487f9 --- /dev/null +++ b/specification/security/saml_service_provider_metadata/examples/response/ResponseExample1.yaml @@ -0,0 +1,9 @@ +# summary: +description: > + A successful response from `POST /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0/_data`, which indicates that the request is acknowledged. +# type: response +# response_code: +value: |- + { + "acknowledged": true + } diff --git a/specification/security/suggest_user_profiles/Request.ts b/specification/security/suggest_user_profiles/Request.ts index 8146198bc4..e3d8ea6d50 100644 --- a/specification/security/suggest_user_profiles/Request.ts +++ b/specification/security/suggest_user_profiles/Request.ts @@ -25,6 +25,10 @@ import { Hint } from './types' * Suggest a user profile. * * Get suggestions for user profiles that match specified search criteria. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + * Individual users and external applications should not call this API directly. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. * @rest_spec_name security.suggest_user_profiles * @availability stack since=8.2.0 stability=stable * @availability serverless stability=stable visibility=private @@ -40,36 +44,37 @@ export interface Request extends RequestBase { ] query_parameters: { /** - * List of filters for the `data` field of the profile document. - * To return all content use `data=*`. To return a subset of content - * use `data=` to retrieve content nested under the specified ``. - * By default returns no `data` content. + * A comma-separated list of filters for the `data` field of the profile document. + * To return all content use `data=*`. + * To return a subset of content, use `data=` to retrieve content nested under the specified ``. + * By default, the API returns no `data` content. + * It is an error to specify `data` as both the query parameter and the request body field. */ data?: string | string[] } body: { /** - * Query string used to match name-related fields in user profile documents. + * A query string used to match name-related fields in user profile documents. * Name-related fields are the user's `username`, `full_name`, and `email`. */ name?: string /** - * Number of profiles to return. + * The number of profiles to return. * @server_default 10 */ size?: long /** - * List of filters for the `data` field of the profile document. - * To return all content use `data=*`. To return a subset of content - * use `data=` to retrieve content nested under the specified ``. - * By default returns no `data` content. + * A comma-separated list of filters for the `data` field of the profile document. + * To return all content use `data=*`. + * To return a subset of content, use `data=` to retrieve content nested under the specified ``. + * By default, the API returns no `data` content. + * It is an error to specify `data` as both the query parameter and the request body field. */ data?: string | string[] /** * Extra search criteria to improve relevance of the suggestion result. * Profiles matching the spcified hint are ranked higher in the response. - * Profiles not matching the hint don't exclude the profile from the response - * as long as the profile matches the `name` field query. + * Profiles not matching the hint aren't excluded from the response as long as the profile matches the `name` field query. */ hint?: Hint } diff --git a/specification/security/suggest_user_profiles/Response.ts b/specification/security/suggest_user_profiles/Response.ts index c72c7aec8d..6ba0db2f1f 100644 --- a/specification/security/suggest_user_profiles/Response.ts +++ b/specification/security/suggest_user_profiles/Response.ts @@ -28,8 +28,17 @@ export class TotalUserProfiles { export class Response { body: { + /** + * Metadata about the number of matching profiles. + */ total: TotalUserProfiles + /** + * The number of milliseconds it took Elasticsearch to run the request. + */ took: long + /** + * A list of profile documents, ordered by relevance, that match the search criteria. + */ profiles: UserProfile[] } } diff --git a/specification/security/suggest_user_profiles/examples/request/RequestExample1.yaml b/specification/security/suggest_user_profiles/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..cf6d017092 --- /dev/null +++ b/specification/security/suggest_user_profiles/examples/request/RequestExample1.yaml @@ -0,0 +1,20 @@ +# summary: +# method_request: POST /_security/profile/_suggest +description: > + Run `POST /_security/profile/_suggest` to get suggestions for profile documents with name-related fields matching `jack`. + It specifies both `uids` and `labels` hints for better relevance. + The `labels` hint ranks profiles higher if their `direction` label matches either `north` or `east`. +# type: request +value: |- + { + "name": "jack", + "hint": { + "uids": [ + "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0", + "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" + ], + "labels": { + "direction": ["north", "east"] + } + } + } diff --git a/specification/security/suggest_user_profiles/examples/response/ResponseExample1.yaml b/specification/security/suggest_user_profiles/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..d46fa54586 --- /dev/null +++ b/specification/security/suggest_user_profiles/examples/response/ResponseExample1.yaml @@ -0,0 +1,10 @@ +# summary: +description: > + A successful response from `GET /_security/saml/metadata/saml1`. + It contains the SAML metadata that was generated for the SAML realm as an XML string. +# type: response +# response_code: +value: |- + { + "metadata" : "" + } diff --git a/specification/security/suggest_user_profiles/types.ts b/specification/security/suggest_user_profiles/types.ts index d2eb94cb85..f07634c2e4 100644 --- a/specification/security/suggest_user_profiles/types.ts +++ b/specification/security/suggest_user_profiles/types.ts @@ -22,7 +22,7 @@ import { Dictionary } from '@spec_utils/Dictionary' export class Hint { /** - * A list of Profile UIDs to match against. + * A list of profile UIDs to match against. */ uids?: UserProfileId[] /** diff --git a/specification/security/update_cross_cluster_api_key/UpdateCrossClusterApiKeyRequest.ts b/specification/security/update_cross_cluster_api_key/UpdateCrossClusterApiKeyRequest.ts index a41b463a21..fc65ed8712 100644 --- a/specification/security/update_cross_cluster_api_key/UpdateCrossClusterApiKeyRequest.ts +++ b/specification/security/update_cross_cluster_api_key/UpdateCrossClusterApiKeyRequest.ts @@ -26,6 +26,20 @@ import { Duration } from '@_types/Time' * Update a cross-cluster API key. * * Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. + * + * To use this API, you must have at least the `manage_security` cluster privilege. + * Users can only update API keys that they created. + * 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. + * To update an API key, the owner user's credentials are required. + * + * It's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API. + * + * This API supports updates to an API key's access scope, metadata, and expiration. + * The owner user's information, such as the `username` and `realm`, is also updated automatically on every call. + * + * NOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API. * @rest_spec_name security.update_cross_cluster_api_key * @availability stack stability=stable * @cluster_privileges manage_security @@ -54,7 +68,7 @@ export interface Request extends RequestBase { */ access: Access /** - * Expiration time for the API key. + * The expiration time for the API key. * By default, API keys never expire. This property can be omitted to leave the value unchanged. */ expiration?: Duration diff --git a/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml b/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml new file mode 100644 index 0000000000..37d5973869 --- /dev/null +++ b/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml @@ -0,0 +1,18 @@ +# summary: +# method_request: PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx +description: > + Run `PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx` to update a cross-cluster AsPI key, assigning it new access scope and metadata. +# type: request +value: |- + { + "access": { + "replication": [ + { + "names": ["archive"] + } + ] + }, + "metadata": { + "application": "replication" + } + } diff --git a/specification/security/update_cross_cluster_api_key/examples/response/UpdateCrossClusterApiKeyResponseExample1.yaml b/specification/security/update_cross_cluster_api_key/examples/response/UpdateCrossClusterApiKeyResponseExample1.yaml new file mode 100644 index 0000000000..d60a031197 --- /dev/null +++ b/specification/security/update_cross_cluster_api_key/examples/response/UpdateCrossClusterApiKeyResponseExample1.yaml @@ -0,0 +1,9 @@ +# summary: +description: > + A successful response from `PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx` that indicates that the API key was updated. +# type: response +# response_code: +value: |- + { + "updated": true + } diff --git a/specification/security/update_settings/SecurityUpdateSettingsRequest.ts b/specification/security/update_settings/SecurityUpdateSettingsRequest.ts index f795d47a52..8bf41a8b71 100644 --- a/specification/security/update_settings/SecurityUpdateSettingsRequest.ts +++ b/specification/security/update_settings/SecurityUpdateSettingsRequest.ts @@ -23,6 +23,7 @@ import { Duration } from '@_types/Time' /** * Update security index settings. + * * Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`. * * If a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use. diff --git a/specification/security/update_user_profile_data/Request.ts b/specification/security/update_user_profile_data/Request.ts index 99397e2594..7c4dad1e2e 100644 --- a/specification/security/update_user_profile_data/Request.ts +++ b/specification/security/update_user_profile_data/Request.ts @@ -28,6 +28,21 @@ import { long } from '@_types/Numeric' * Update user profile data. * * Update specific data for the user profile that is associated with a unique ID. + * + * NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + * Individual users and external applications should not call this API directly. + * Elastic reserves the right to change or remove this feature in future releases without prior notice. + * + * To use this API, you must have one of the following privileges: + * + * * The `manage_user_profile` cluster privilege. + * * The `update_profile_data` global privilege for the namespaces that are referenced in the request. + * + * This API updates the `labels` and `data` fields of an existing user profile document with JSON objects. + * New keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request. + * + * For both labels and data, content is namespaced by the top-level fields. + * The `update_profile_data` global privilege grants privileges for updating only the allowed namespaces. * @rest_spec_name security.update_user_profile_data * @availability stack since=8.2.0 stability=stable * @availability serverless stability=stable visibility=private @@ -58,21 +73,25 @@ export interface Request extends RequestBase { if_primary_term?: long /** * If 'true', Elasticsearch refreshes 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' do nothing with refreshes. + * visible to search. + * If 'wait_for', it waits for a refresh to make this operation visible to search. + * If 'false', nothing is done with refreshes. * @server_default false */ refresh?: Refresh } body: { /** - * Searchable data that you want to associate with the user profile. This - * field supports a nested data structure. + * Searchable data that you want to associate with the user profile. + * This field supports a nested data structure. + * Within the labels object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`). */ labels?: Dictionary /** * Non-searchable data that you want to associate with the user profile. * This field supports a nested data structure. + * Within the `data` object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`). + * The data object is not searchable, but can be retrieved with the get user profile API. */ data?: Dictionary } diff --git a/specification/security/update_user_profile_data/examples/request/RequestExample1.yaml b/specification/security/update_user_profile_data/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..ff7cc28f7c --- /dev/null +++ b/specification/security/update_user_profile_data/examples/request/RequestExample1.yaml @@ -0,0 +1,16 @@ +# summary: +# method_request: POST /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0/_data +description: > + Run `POST /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0/_data` to update a profile document for the `u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0` user profile. +# type: request +value: |- + { + "labels": { + "direction": "east" + }, + "data": { + "app1": { + "theme": "default" + } + } + } diff --git a/specification/security/update_user_profile_data/examples/response/ResponseExample1.yaml b/specification/security/update_user_profile_data/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..d95c6487f9 --- /dev/null +++ b/specification/security/update_user_profile_data/examples/response/ResponseExample1.yaml @@ -0,0 +1,9 @@ +# summary: +description: > + A successful response from `POST /_security/profile/u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0/_data`, which indicates that the request is acknowledged. +# type: response +# response_code: +value: |- + { + "acknowledged": true + }