Expose session invalidation API.

docs/api/session-management.asciidoc

@@ -0,0 +1,11 @@
+[role="xpack"]
+[[session-management-api]]
+== {kib} session management APIs
+
+Allows managing {kib} <<xpack-security-session-management, user sessions>>.
+
+The following {kib} session management APIs are available:
+
+* <<session-management-api-invalidate, Invalidate sessions API>> to invalidate {kib} user sessions
+
+include::session-management/invalidate.asciidoc[]

docs/api/session-management/invalidate.asciidoc

@@ -0,0 +1,108 @@
+[[session-management-api-invalidate]]
+=== Invalidate sessions API
+++++
+<titleabbrev>Invalidate sessions</titleabbrev>
+++++
+
+experimental[] Invalidates {kib} user sessions that match provided query.
+
+[[session-management-api-invalidate-prereqs]]
+==== Prerequisite
+
+To use the invalidate sessions API, you must be a `superuser`.
+
+[[session-management-api-invalidate-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/security/session/_invalidate`
+
+[role="child_attributes"]
+[[session-management-api-invalidate-request-body]]
+==== Request body
+
+`match`::
+(Required, string) Specifies how {kib} should determine which sessions should be invalidated. Can either be `all` to invalidate all existing sessions, or `query` to only invalidate sessions that match the query specified in the additional `query` parameter.
+
+`query`::
+(Optional, object) Specifies the query that {kib} should use to match the sessions that should be invalidated when `match` parameter is set to `query`. This parameter is forbidden if `match` is set to `all`.
++
+.Properties of `query`
+[%collapsible%open]
+=====
+`provider` :::
+(Required, object) Contains required `type` and optional `name` string properties to match sessions that were created by the specific <<authentication-security-settings, authentication provider>>.
+
+`username` :::
+(Optional, string) If specified, {kib} will only invalidate sessions that belong to a specific user.
+=====
+
+[[session-management-api-invalidate-response-body]]
+==== Response body
+
+`total`::
+(number) The number of successfully invalidated sessions.
+
+[[session-management-api-invalidate-response-codes]]
+==== Response codes
+
+`200`::
+  Indicates a successful call.
+
+`403`::
+  Indicates that the user may not be authorized to invalidate sessions for other users, refer to <<session-management-api-invalidate-prereqs, Prerequisite section>>.
+
+==== Examples
+
+Invalidate all existing sessions:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/security/session/_invalidate
+{
+  "match" : "all"
+}
+--------------------------------------------------
+// KIBANA
+
+Invalidate sessions that were created by any <<saml, SAML authentication providers>> only:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/security/session/_invalidate
+{
+  "match" : "query",
+  "query": {
+    "provider" : { "type": "saml" }
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+Invalidate sessions that were created by the <<saml, SAML authentication provider>> with the name `saml1` only:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/security/session/_invalidate
+{
+  "match" : "query",
+  "query": {
+    "provider" : { "type": "saml", "name": "saml1" }
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+Invalidate sessions that were created by any <<oidc, OpenID Connect authentication providers>> for the user with the name `[email protected]` only:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/security/session/_invalidate
+{
+  "match" : "query",
+  "query": {
+    "provider" : { "type": "oidc" },
+    "username": "[email protected]"
+  }
+}
+--------------------------------------------------
+// KIBANA

docs/user/api.asciidoc

@@ -97,6 +97,7 @@ curl -X POST \
 include::{kib-repo-dir}/api/features.asciidoc[]
 include::{kib-repo-dir}/api/spaces-management.asciidoc[]
 include::{kib-repo-dir}/api/role-management.asciidoc[]
+include::{kib-repo-dir}/api/session-management.asciidoc[]
 include::{kib-repo-dir}/api/saved-objects.asciidoc[]
 include::{kib-repo-dir}/api/alerts.asciidoc[]
 include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[]

docs/user/security/authentication/index.asciidoc

@@ -397,6 +397,14 @@ NOTE: *Public URL* is available only when anonymous access is configured and you
 +
 For more information, refer to <<embedding, Embed {kib} content in a web page>>.
 
+[float]
+[[anonymous-access-session]]
+===== Anonymous access session
+
+{kib} maintains a separate <<xpack-security-session-management, session>> for every anonymous user, as it does for any other authentication mechanism. This way {kib} can maintain a personalized experience even for the users who didn't provide any personal credentials. 
+
+You can configure both <<session-idle-timeout, session idle timeout>> and <<session-lifespan, session lifespan>> for the anonymous sessions as you'd do for any other session with the only exception that idle timeout is explicitly disabled for the anonymous sessions by default. That means that the global <<security-session-and-cookie-settings, `xpack.security.session.idleTimeout`>> setting won't affect anonymous sessions. If you want to change the idle timeout for the anonymous sessions, you must configure the provider-level <<anonymous-authentication-provider-settings, `xpack.security.authc.providers.anonymous.<provider-name>.session.idleTimeout`>> setting instead.
+
 [[http-authentication]]
 ==== HTTP authentication
 

docs/user/security/session-management.asciidoc

@@ -6,6 +6,8 @@ When you log in, {kib} creates a session that is used to authenticate subsequent
 
 When your session expires, or you log out, {kib} will invalidate your cookie and remove session information from the index. {kib} also periodically invalidates and removes any expired sessions that weren't explicitly invalidated.
 
+To manage user sessions programmatically, {kib} exposes a set of <<session-management-api, session management APIs>>.
+
 [[session-idle-timeout]]
 ==== Session idle timeout
 

x-pack/plugins/security/server/authentication/authenticator.test.ts

@@ -585,8 +585,8 @@ describe('Authenticator', () => {
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalledWith(request);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledTimes(1);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledWith(request, { match: 'current' });
     });
 
     it('clears session if provider asked to do so in `succeeded` result.', async () => {
@@ -605,8 +605,8 @@ describe('Authenticator', () => {
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalledWith(request);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledTimes(1);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledWith(request, { match: 'current' });
     });
 
     it('clears session if provider asked to do so in `redirected` result.', async () => {
@@ -624,8 +624,8 @@ describe('Authenticator', () => {
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalledWith(request);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledTimes(1);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledWith(request, { match: 'current' });
     });
 
     describe('with Access Agreement', () => {
@@ -1191,7 +1191,7 @@ describe('Authenticator', () => {
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('extends session for non-system API calls.', async () => {
@@ -1213,7 +1213,7 @@ describe('Authenticator', () => {
       expect(mockOptions.session.extend).toHaveBeenCalledWith(request, mockSessVal);
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('does not touch session for system API calls if authentication fails with non-401 reason.', async () => {
@@ -1234,7 +1234,7 @@ describe('Authenticator', () => {
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('does not touch session for non-system API calls if authentication fails with non-401 reason.', async () => {
@@ -1255,7 +1255,7 @@ describe('Authenticator', () => {
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('replaces existing session with the one returned by authentication provider for system API requests', async () => {
@@ -1281,7 +1281,7 @@ describe('Authenticator', () => {
       });
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('replaces existing session with the one returned by authentication provider for non-system API requests', async () => {
@@ -1307,7 +1307,7 @@ describe('Authenticator', () => {
       });
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('clears session if provider failed to authenticate system API request with 401 with active session.', async () => {
@@ -1324,8 +1324,8 @@ describe('Authenticator', () => {
         AuthenticationResult.failed(Boom.unauthorized())
       );
 
-      expect(mockOptions.session.clear).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalledWith(request);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledTimes(1);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledWith(request, { match: 'current' });
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
@@ -1345,8 +1345,8 @@ describe('Authenticator', () => {
         AuthenticationResult.failed(Boom.unauthorized())
       );
 
-      expect(mockOptions.session.clear).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalledWith(request);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledTimes(1);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledWith(request, { match: 'current' });
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
@@ -1364,8 +1364,8 @@ describe('Authenticator', () => {
         AuthenticationResult.redirectTo('some-url', { state: null })
       );
 
-      expect(mockOptions.session.clear).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalledWith(request);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledTimes(1);
+      expect(mockOptions.session.invalidate).toHaveBeenCalledWith(request, { match: 'current' });
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
@@ -1382,7 +1382,7 @@ describe('Authenticator', () => {
         AuthenticationResult.notHandled()
       );
 
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
@@ -1399,7 +1399,7 @@ describe('Authenticator', () => {
         AuthenticationResult.notHandled()
       );
 
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
       expect(mockOptions.session.create).not.toHaveBeenCalled();
       expect(mockOptions.session.update).not.toHaveBeenCalled();
       expect(mockOptions.session.extend).not.toHaveBeenCalled();
@@ -1789,7 +1789,7 @@ describe('Authenticator', () => {
         DeauthenticationResult.notHandled()
       );
 
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('clears session and returns whatever authentication provider returns.', async () => {
@@ -1804,7 +1804,7 @@ describe('Authenticator', () => {
       );
 
       expect(mockBasicAuthenticationProvider.logout).toHaveBeenCalledTimes(1);
-      expect(mockOptions.session.clear).toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).toHaveBeenCalled();
     });
 
     it('if session does not exist but provider name is valid, returns whatever authentication provider returns.', async () => {
@@ -1823,7 +1823,7 @@ describe('Authenticator', () => {
 
       expect(mockBasicAuthenticationProvider.logout).toHaveBeenCalledTimes(1);
       expect(mockBasicAuthenticationProvider.logout).toHaveBeenCalledWith(request, null);
-      expect(mockOptions.session.clear).toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).toHaveBeenCalled();
     });
 
     it('if session does not exist and provider name is not available, returns whatever authentication provider returns.', async () => {
@@ -1840,7 +1840,7 @@ describe('Authenticator', () => {
 
       expect(mockBasicAuthenticationProvider.logout).toHaveBeenCalledTimes(1);
       expect(mockBasicAuthenticationProvider.logout).toHaveBeenCalledWith(request);
-      expect(mockOptions.session.clear).not.toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).not.toHaveBeenCalled();
     });
 
     it('returns `notHandled` if session does not exist and provider name is invalid', async () => {
@@ -1852,7 +1852,7 @@ describe('Authenticator', () => {
       );
 
       expect(mockBasicAuthenticationProvider.logout).not.toHaveBeenCalled();
-      expect(mockOptions.session.clear).toHaveBeenCalled();
+      expect(mockOptions.session.invalidate).toHaveBeenCalled();
     });
   });