Skip to content

Commit

Permalink
[DOCS] Add examples for security user profile and SAML APIs (#3520)
Browse files Browse the repository at this point in the history
(cherry picked from commit 72c9fef)
  • Loading branch information
lcawl committed Jan 15, 2025
1 parent b628c5a commit 9f771c9
Show file tree
Hide file tree
Showing 49 changed files with 750 additions and 177 deletions.
111 changes: 72 additions & 39 deletions output/openapi/elasticsearch-openapi.json

Large diffs are not rendered by default.

231 changes: 138 additions & 93 deletions output/schema/schema.json

Large diffs are not rendered by default.

12 changes: 11 additions & 1 deletion specification/_doc_ids/table.csv
Original file line number Diff line number Diff line change
Expand Up @@ -609,14 +609,17 @@ security-api-clear-role-cache,https://www.elastic.co/guide/en/elasticsearch/refe
security-api-clear-service-token-caches,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-clear-service-token-caches.html
security-api-create-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-api-key.html
security-api-create-service-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-service-token.html
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-delegate-pki,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delegate-pki-authentication.html
security-api-delete-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-privilege.html
security-api-delete-role-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-role-mapping.html
security-api-delete-role,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-role.html
security-api-delete-service-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-service-token.html
security-api-delete-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-user.html
security-api-disable-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-disable-user.html
security-api-disable-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-disable-user-profile.html
security-api-enable-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-enable-user.html
security-api-enable-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user-profile.html
security-api-get-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-api-key.html
security-api-get-builtin-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-builtin-privileges.html
security-api-get-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-privileges.html
Expand All @@ -628,8 +631,10 @@ security-api-get-settings,https://www.elastic.co/guide/en/elasticsearch/referenc
security-api-get-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-token.html
security-api-get-user-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-privileges.html
security-api-get-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user.html
security-api-get-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-profile.html
security-api-grant-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-grant-api-key.html
security-api-has-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-has-privileges.html
security-api-has-privileges-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-has-privileges-user-profile.html
security-api-invalidate-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-invalidate-api-key.html
security-api-invalidate-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-invalidate-token.html
security-api-kibana-enrollment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-kibana-enrollment.html
Expand All @@ -649,8 +654,13 @@ security-api-saml-logout,https://www.elastic.co/guide/en/elasticsearch/reference
security-api-saml-prepare-authentication,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-prepare-authentication.html
security-api-saml-sp-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-sp-metadata.html
security-api-ssl,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-ssl.html
security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
security-api-suggest,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-suggest-user-profile.html
security-api-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-api-key.html
security-api-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html
security-api-update-user-data,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-user-profile-data.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
Expand Down
1 change: 1 addition & 0 deletions specification/security/_types/GrantType.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
30 changes: 30 additions & 0 deletions specification/security/activate_user_profile/Request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,46 @@ 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
* @cluster_privileges manage_user_profile
*/
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
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# summary:
# method_request: POST /_security/profile/_activate
description: >
Run `POST /_security/profile/_activate` to activate a user profile.
# type: request
value: |-
{
"grant_type": "password",
"username" : "jacknich",
"password" : "l0ng-r4nd0m-p@ssw0rd"
}
14 changes: 11 additions & 3 deletions specification/security/disable_user_profile/Request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
path_parts: {
Expand All @@ -39,9 +47,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
Expand Down
15 changes: 12 additions & 3 deletions specification/security/enable_user_profile/Request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,32 @@ 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
* @cluster_privileges manage_user_profile
* @doc_id security-api-enable-user-profile
*/
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
Expand Down
13 changes: 9 additions & 4 deletions specification/security/get_user_profile/Request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,15 @@ 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 {
path_parts: {
Expand All @@ -38,9 +43,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=<key>` to retrieve content nested under the specified `<key>`.
* 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=<key>` to retrieve content nested under the specified `<key>`.
* By default returns no `data` content.
*/
data?: string | string[]
Expand Down
5 changes: 5 additions & 0 deletions specification/security/get_user_profile/Response.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down
7 changes: 7 additions & 0 deletions specification/security/has_privileges_user_profile/Request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,14 @@ 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
* @cluster_privileges manage_user_profile
* @doc_id security-api-has-privileges-user-profile
* @ext_doc_id user-profile
*/
export interface Request extends RequestBase {
Expand All @@ -37,6 +41,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
}
}
Original file line number Diff line number Diff line change
@@ -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" ]
}
]
}
}
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
21 changes: 18 additions & 3 deletions specification/security/saml_authenticate/Request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,16 +23,31 @@ 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 `<Response>`.
*
* 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 {
body: {
/** The SAML response as it was sent by the users 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
Expand Down
15 changes: 15 additions & 0 deletions specification/security/saml_authenticate/Response.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
}
Original file line number Diff line number Diff line change
@@ -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"]
}
Loading

0 comments on commit 9f771c9

Please sign in to comment.