Skip to content

[8.18] Add minimal user session management API docs (#212576) #214033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lcawl merged 1 commit into from
Mar 13, 2025
Merged

[8.18] Add minimal user session management API docs (#212576) #214033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 110 additions & 1 deletion oas_docs/output/kibana.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,9 @@ tags:
- name: system
x-displayName: System
description: |
Get information about the system status, resource usage, and installed plugins.
Get information about the system status, resource usage, features, and installed plugins.
- name: user session
x-displayName: User session management
paths:
/api/actions:
get:
Expand Down Expand Up @@ -21352,6 +21354,113 @@ paths:
summary: Create or update roles
tags:
- roles
/api/security/session/_invalidate:
post:
description: |
Invalidate user sessions that match a query. To use this API, you must be a superuser.
operationId: post-security-session-invalidate
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
invalidateRequestExample1:
description: Run `POST api/security/session/_invalidate` to invalidate all existing sessions.
summary: Invalidate all sessions
value: |-
{
"match" : "all"
}
invalidateRequestExample2:
description: Run `POST api/security/session/_invalidate` to invalidate sessions that were created by any SAML authentication provider.
summary: Invalidate all SAML sessions
value: |-
{
"match" : "query",
"query": {
"provider" : { "type": "saml" }
}
}
invalidateRequestExample3:
description: Run `POST api/security/session/_invalidate` to invalidate sessions that were created by the SAML authentication provider named `saml1`.
summary: Invalidate sessions for a provider
value: |-
{
"match" : "query",
"query": {
"provider" : { "type": "saml", "name": "saml1" }
}
}
invalidateRequestExample4:
description: Run `POST api/security/session/_invalidate` to invalidate sessions that were created by any OpenID Connect authentication provider for the user with the username `user@my-oidc-sso.com`.
summary: Invalidate sessions for a user
value: |-
{
"match" : "query",
"query": {
"provider" : { "type": "oidc" },
"username": "user@my-oidc-sso.com"
}
}
schema:
type: object
properties:
match:
description: |
The method Kibana uses to determine which sessions to invalidate. If it is `all`, all existing sessions will be invalidated. If it is `query`, only the sessions that match the query will be invalidated.
enum:
- all
- query
type: string
query:
description: |
The query that Kibana uses to match the sessions to invalidate when the `match` parameter is set to `query`.
type: object
properties:
provider:
description: The authentication providers that will have their user sessions invalidated.
type: object
properties:
name:
description: The authentication provider name.
type: string
type:
description: |
The authentication provide type. For example: `basic`, `token`, `saml`, `oidc`, `kerberos`, or `pki`.
type: string
required:
- type
username:
description: The username that will have its sessions invalidated.
type: string
required:
- provider
required:
- match
responses:
'200':
content:
application/json:
schema:
type: object
properties:
total:
description: The number of sessions that were successfully invalidated.
type: integer
description: Indicates a successful call
'403':
description: Indicates that the user may not be authorized to invalidate sessions for other users.
summary: Invalidate user sessions
tags:
- user session
x-state: Technical Preview
/api/spaces/_copy_saved_objects:
post:
description: 'It also allows you to automatically copy related objects, so when you copy a dashboard, this can automatically copy over the associated visualizations, data views, and saved Discover sessions, as required. You can request to overwrite any objects that already exist in the target space if they share an identifier or you can use the resolve copy saved objects conflicts API to do this on a per-object basis.<br/><br/>[Required authorization] Route required privileges: ALL of [copySavedObjectsToSpaces].'
Expand Down
6 changes: 5 additions & 1 deletion oas_docs/overlays/kibana.overlays.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,11 @@ actions:
update:
x-displayName: "System"
description: >
Get information about the system status, resource usage, and installed plugins.
Get information about the system status, resource usage, features, and installed plugins.
- target: '$.tags[?(@.name=="user session")]'
description: Change displayName
update:
x-displayName: "User session management"
# Remove extra tags from operations
- target: "$.paths[*][*].tags[1:]"
description: Remove all but first tag from operations
Expand Down
2 changes: 2 additions & 0 deletions oas_docs/scripts/merge_ess_oas.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ const { REPO_ROOT } = require('@kbn/repo-info');
`${REPO_ROOT}/x-pack/platform/plugins/shared/ml/common/openapi/ml_apis.yaml`,
`${REPO_ROOT}/src/core/packages/saved-objects/docs/openapi/bundled.yaml`,
`${REPO_ROOT}/x-pack/plugins/fleet/common/openapi/bundled.yaml`,
`${REPO_ROOT}/x-pack/platform/plugins/private/upgrade_assistant/docs/openapi/upgrade_apis.yaml`,
`${REPO_ROOT}/x-pack/platform/plugins/shared/security/docs/openapi/user_session_apis.yaml`,

// Observability Solution
`${REPO_ROOT}/x-pack/solutions/observability/plugins/apm/docs/openapi/apm/bundled.yaml`,
Expand Down
7 changes: 7 additions & 0 deletions x-pack/platform/plugins/shared/security/docs/openapi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# OpenAPI (Experimental)

The current self-contained spec file can be used for online tools like those found at https://openapi.tools/. This spec is experimental and may be incomplete or change later.

A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).

These files are joined with the rest of the Kibana APIs per `oas_docs/README.md`
125 changes: 125 additions & 0 deletions x-pack/platform/plugins/shared/security/docs/openapi/user_session_apis.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
openapi: 3.0.3
info:
title: User session management APIs
description: Kibana APIs for user session management
version: "1.0.1"
license:
name: Elastic License 2.0
url: https://www.elastic.co/licensing/elastic-license
tags:
- name: user session
x-displayName: User session management
servers:
- url: /
paths:
/api/security/session/_invalidate:
post:
summary: Invalidate user sessions
tags:
- user session
x-state: Technical Preview
description: >
Invalidate user sessions that match a query.
To use this API, you must be a superuser.
operationId: post-security-session-invalidate
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- match
properties:
match:
enum:
- all
- query
type: string
description: >
The method Kibana uses to determine which sessions to invalidate.
If it is `all`, all existing sessions will be invalidated.
If it is `query`, only the sessions that match the query will be invalidated.
query:
type: object
description: >
The query that Kibana uses to match the sessions to invalidate when the `match` parameter is set to `query`.
required:
- provider
properties:
provider:
type: object
description: The authentication providers that will have their user sessions invalidated.
properties:
name:
type: string
description: The authentication provider name.
type:
type: string
description: >
The authentication provide type.
For example: `basic`, `token`, `saml`, `oidc`, `kerberos`, or `pki`.
required:
- type
username:
type: string
description: The username that will have its sessions invalidated.
examples:
invalidateRequestExample1:
summary: Invalidate all sessions
description: Run `POST api/security/session/_invalidate` to invalidate all existing sessions.
value: |-
{
"match" : "all"
}
invalidateRequestExample2:
summary: Invalidate all SAML sessions
description: Run `POST api/security/session/_invalidate` to invalidate sessions that were created by any SAML authentication provider.
value: |-
{
"match" : "query",
"query": {
"provider" : { "type": "saml" }
}
}
invalidateRequestExample3:
summary: Invalidate sessions for a provider
description: Run `POST api/security/session/_invalidate` to invalidate sessions that were created by the SAML authentication provider named `saml1`.
value: |-
{
"match" : "query",
"query": {
"provider" : { "type": "saml", "name": "saml1" }
}
}
invalidateRequestExample4:
summary: Invalidate sessions for a user
description: Run `POST api/security/session/_invalidate` to invalidate sessions that were created by any OpenID Connect authentication provider for the user with the username `user@my-oidc-sso.com`.
value: |-
{
"match" : "query",
"query": {
"provider" : { "type": "oidc" },
"username": "user@my-oidc-sso.com"
}
}
responses:
'200':
description: Indicates a successful call
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description: The number of sessions that were successfully invalidated.
'403':
description: Indicates that the user may not be authorized to invalidate sessions for other users.