User Profile: Initial beta overview documentations (#83766)

Add initial feature overview documentation pages for User Profile and
Security Domain.

Co-authored-by: Adam Locke <[email protected]>
Co-authored-by: Tim Vernum <[email protected]>
Co-authored-by: Albert Zaharovits <[email protected]>

Author: 4 people

docs/reference/settings/security-settings.asciidoc

@@ -193,6 +193,30 @@ The hashing algorithm that is used for the
 in-memory cached API key credentials. For possible values, see <<cache-hash-algo>>.
 Defaults to `ssha256`.
 
+ifeval::["{release-state}"!="released"]
+[discrete]
+[[security-domain-settings]]
+==== Security domain settings
+// tag::security-domain-settings-description-tag[]
+You configure security domain settings in the `xpack.security.authc.domains`
+namespace in `elasticsearch.yml`.
+
+For example:
+
+[source, yaml]
+------------------------------------------------------------
+xpack:
+  security:
+    authc:
+      domains:
+        my_domain: <1>
+          realms: [ 'default_native', 'saml1' ] <2>
+------------------------------------------------------------
+<1> Specifies the name of the security domain
+<2> Specifies the realms that belong to the domain
+// end::security-domain-settings-description-tag[]
+endif::[]
+
 [discrete]
 [[realm-settings]]
 ==== Realm settings

x-pack/docs/en/rest-api/security.asciidoc

@@ -132,21 +132,21 @@ communicate with a secured {es} cluster.
 * <<security-api-node-enrollment, Enroll a new node>>
 * <<security-api-kibana-enrollment, Enroll a new {kib} instance>>
 
+ifeval::["{release-state}"!="released"]
 [discrete]
 [[security-user-profile-apis]]
 === User Profile
 
 Use the following APIs to retrieve and manage user profiles.
 
-* <<security-api-activiate-user-profile, Activate user profile>>
+* <<security-api-activate-user-profile, Activate user profile>>
 * <<security-api-get-user-profile, Get user profile>>
 * <<security-api-update-user-profile-data, Update user profile data>>
 * <<security-api-enable-user-profile, Enable user profile>>
 * <<security-api-disable-user-profile, Disable user profile>>
 * <<security-api-suggest-user-profile, Suggest user profile>>
+endif::[]
 
-
-include::security/activate-user-profile.asciidoc[]
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
@@ -168,8 +168,6 @@ include::security/delete-service-token.asciidoc[]
 include::security/delete-users.asciidoc[]
 include::security/disable-users.asciidoc[]
 include::security/enable-users.asciidoc[]
-include::security/disable-user-profile.asciidoc[]
-include::security/enable-user-profile.asciidoc[]
 include::security/enroll-kibana.asciidoc[]
 include::security/enroll-node.asciidoc[]
 include::security/get-api-keys.asciidoc[]
@@ -181,7 +179,7 @@ include::security/get-service-accounts.asciidoc[]
 include::security/get-service-credentials.asciidoc[]
 include::security/get-tokens.asciidoc[]
 include::security/get-user-privileges.asciidoc[]
-include::security/get-user-profile.asciidoc[]
+
 include::security/get-users.asciidoc[]
 include::security/grant-api-keys.asciidoc[]
 include::security/has-privileges.asciidoc[]
@@ -198,5 +196,11 @@ include::security/saml-invalidate-api.asciidoc[]
 include::security/saml-complete-logout-api.asciidoc[]
 include::security/saml-sp-metadata.asciidoc[]
 include::security/ssl.asciidoc[]
+ifeval::["{release-state}"!="released"]
+include::security/activate-user-profile.asciidoc[]
+include::security/disable-user-profile.asciidoc[]
+include::security/enable-user-profile.asciidoc[]
+include::security/get-user-profile.asciidoc[]
 include::security/suggest-user-profile.asciidoc[]
 include::security/update-user-profile-data.asciidoc[]
+endif::[]

x-pack/docs/en/rest-api/security/activate-user-profile.asciidoc

@@ -1,5 +1,5 @@
 [role="xpack"]
-[[security-api-activiate-user-profile]]
+[[security-api-activate-user-profile]]
 === Activate user profile API
 ++++
 <titleabbrev>Activate user profile</titleabbrev>

x-pack/docs/en/rest-api/security/disable-user-profile.asciidoc

@@ -25,7 +25,7 @@ To use this API, you must have the `manage_user_profile` cluster privilege.
 [[security-api-disable-user-profile-desc]]
 ==== {api-description-title}
 
-When you <<security-api-activiate-user-profile,activate a user profile>>, it's
+When you <<security-api-activate-user-profile,activate a user profile>>, it's
 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.

x-pack/docs/en/rest-api/security/enable-user-profile.asciidoc

@@ -25,7 +25,7 @@ To use this API, you must have the `manage_user_profile` cluster privilege.
 [[security-api-enable-user-profile-desc]]
 ==== {api-description-title}
 
-When you <<security-api-activiate-user-profile,activate a user profile>>, it's
+When you <<security-api-activate-user-profile,activate a user profile>>, it's
 automatically enabled and visible in user profile searches. If you later
 <<security-api-disable-user-profile,disable the user profile>>, you can use the
 enable user profile API to make the profile visible in these searches again.

x-pack/docs/en/rest-api/security/get-user-profile.asciidoc

@@ -25,7 +25,7 @@ Retrieves a user's profile using the unique profile ID.
 
 The get user profile API returns the user profile document matching a specified
 `uid`, which is generated when
-<<security-api-activiate-user-profile,activating a user profile>>.
+<<security-api-activate-user-profile,activating a user profile>>.
 
 [[security-api-get-user-profile-path-params]]
 ==== {api-path-parms-title}

x-pack/docs/en/security/authentication/overview.asciidoc

@@ -36,8 +36,14 @@ include::built-in-users.asciidoc[][]
 include::service-accounts.asciidoc[]
 include::internal-users.asciidoc[]
 include::token-authentication-services.asciidoc[]
+ifeval::["{release-state}"!="released"]
+include::user-profile.asciidoc[]
+endif::[]
 include::realms.asciidoc[]
 include::realm-chains.asciidoc[]
+ifeval::["{release-state}"!="released"]
+include::security-domain.asciidoc[]
+endif::[]
 include::active-directory-realm.asciidoc[]
 include::file-realm.asciidoc[]
 include::ldap-realm.asciidoc[]

x-pack/docs/en/security/authentication/security-domain.asciidoc

@@ -0,0 +1,97 @@
+[role="xpack"]
+[[security-domain]]
+=== Security domains
+
+beta::[]
+
+Security domains are a method of grouping multiple <<realms,realms>> under the
+same domain so that the {stack} can recognize when a single user authenticates 
+with these realms. Users can authenticate with any of the realms in the domain 
+group, and have access to the same set of resources regardless of which realm 
+they authenticated with.
+
+For example, a single <<user-profile,user profile>> is associated with a user, 
+enabling preferences, notifications, and other user data to be shared across 
+realms. The user can view results from an asynchronous search request or a 
+scrolling search across realms. If the user has the necessary privileges, they 
+can also view and manage API keys across realms.
+
+[[security-domain-resource-sharing]]
+==== Resource sharing across domains
+Some types of resources in {es} are owned by a single user, such as
+<<async-search,async search contexts>>, <<security-api-create-api-key,API keys>>,
+and <<user-profile,user profiles>>. When a user creates a resource, {es}
+captures the user's username and realm information as part of the resource's 
+metadata.
+
+When a user later attempts to access the resource, {es} compares
+the captured username and realm information against those from the accessing
+user. {es} will deny access unless both the realm and username match.
+If {es} detects that a username from two different realms is
+attempting to access a resource, {es} assumes that these users are distinct and
+doesn't allow resources to be shared between those users.
+
+However, there are cases where the same user can authenticate with
+multiple realms and needs to share the same set of resources across realms.
+For example, an <<ldap-realm,LDAP realm>> and a <<saml-realm,SAML realm>> can
+be backed by the same directory service. Additionally,
+<<configuring-authorization-delegation,authorization delegation>> allows one
+realm to delegate authorization to another realm. If both realms authenticate
+users with the same username, it's reasonable to treat these users as the
+same user from a resource ownership perspective.
+
+Security domains make resource sharing across realms possible by grouping those
+realms under the same domain. {es} always enforces the privileges that are 
+associated with the currently authenticated user, which remains true with 
+security domains. Security domains don't bypass
+<<authorization,user authorization>> when resource sharing requires them. For 
+example, a user requires the `manage_own_api_key` privilege to manage their own 
+API keys. If that user doesn't have this privilege when authenticating with one 
+realm, they won't be able to manage API keys while authenticating with another 
+realm.
+
+[[security-domain-realm-roles]]
+===== Managing roles across realms
+{es} provides multiple ways to consistently apply roles across realms. For example, you can use
+<<configuring-authorization-delegation,authorization delegation>> to 
+ensure that a user is assigned the same roles from multiple realms. You can also
+manually configure multiple realms that are backed by the same directory service.
+Though it's possible to configure different <<roles,roles>> for the same user
+when authenticating with different realms, it is _not_ recommended.
+
+[[security-domain-configure]]
+==== Configure a security domain
+
+You configure realms to be under a domain in `elasticsearch.yml`. The realms must
+be defined in `elasticsearch.yml` but do not need to be enabled.
+
+NOTE: The <<file-realm,file realm>> and <<native-realm,native realm>> are
+automatically enabled as `default_file` and `default_native`, respectively,
+without any explicit configuration. You can list these realms under domains even 
+when they are not explicitly defined in `elasticsearch.yml`.
+
+. Add a security domain configuration to `elasticsearch.yml` under the
+`xpack.security.authc.domains` namespace:
++
+[source, yaml]
+----
+xpack:
+  security:
+    authc:
+      domains:
+        my_domain:
+          realms: [ 'default_native', 'saml1' ] <1>
+----
+<1> This configuration defines a security domain called `my_domain`, which
+contains two realms named `default_native` and `saml1`.
+
+. Restart {es}.
+
+[IMPORTANT]
+====
+{es} can fail to start if the domain configuration is invalid, such as:
+
+* A single realm is configured under multiple domains.
+* Any undefined realm, synthetic realm, or the reserved realm is configured to
+be under a domain.
+====

x-pack/docs/en/security/authentication/user-profile.asciidoc

@@ -0,0 +1,93 @@
+[role="xpack"]
+[[user-profile]]
+=== User profiles
+
+beta::[]
+
+Because the {stack} supports externally-managed users (such as users who
+authenticate via SAML, or users stored in an LDAP directory), there's a
+distinction between _users_ and their _profile_.
+
+_Users_ refer to the entities that authenticate requests to the {stack}.
+Each user has a username and a set of privileges (represented by <<roles,roles>>)
+that determine which types of requests they can issue. Users can be ephemeral;
+they might exist only for the duration of a request to an {es} API or for the
+lifetime of a session in {kib}. These users cannot be retrieved after the session
+ends, and can't store preferences across sessions.
+
+_User profiles_ provide persistent and stable representations of users.
+A user profile exists even if the user is offline, so their profile persists across sessions.
+The unique identifier assigned to each profile doesn't change
+throughout the lifetime of a deployment, providing a stable way of referring
+to the associated user. Each profile has a unique identifier, is searchable, and
+can store user data such as format and notification preferences.
+
+The capability of uniquely referring to users regardless of whether they're
+actively online is a critical function that underpins important features like
+personalization and collaboration in {kib}.
+
+
+==== User profiles in {kib}
+
+A user profile is the persistent record that the {stack} stores for each
+interactive user that authenticates to {kib}.
+
+When a user logs in to {kib}, a profile is automatically created for the user,
+or an existing profile is updated to reflect the user's active session.
+By using the unique ID of the user profile, {kib} can store user-level data such as preferences
+separately for each user, which is key to fine-grained levels of customization.
+{kib} uses this unique ID to route messages and notifications to a distinct user,
+regardless of whether they're logged in.
+
+===== Usernames and user profiles
+
+You can use the same username across multiple realms for a single user. In {es},
+it's possible for two different realms to authenticate users with the same username
+and different roles.
+{es} doesn't assume that these users are the same person, and treats
+them as separate individuals with distinct user profiles by default.
+
+NOTE: For use cases where one individual can authenticate against
+multiple realms, you can use the <<security-domain,security domain>> feature
+so that these distinct users are considered to be the same identity
+and share a single user profile.
+
+==== Create and manage user profiles
+
+To create a new user profile or update an existing one, use the
+<<security-api-activate-user-profile,activate user profile API>>. When you
+submit a request, {es} attempts to locate an existing profile document for the
+specified user. If one doesn't exist, {es} creates a new profile document.
+
+In either case, the profile document captures the user's `full_name`, `email`,
+`roles`, and `realms`, and also includes the profile unique ID and timestamp of
+the operation. You can retrieve a user profile with
+the <<security-api-get-user-profile,get user profile API>> by including the
+profile's unique ID (`uid`).
+
+In addition to the user's basic information, you can add data to a profile document
+with the <<security-api-update-user-profile-data,update user profile API>>. For
+example, you can add user-specific preferences as part of the profile data.
+
+Use the <<security-api-suggest-user-profile,search user profile API>> to search profiles
+that match given criteria. This search API is designed to support user-suggestions,
+in collaboration with features such as those found in {kib}.
+However, the search user profile API is not intended to provide a general-purpose search API.
+
+==== Limitations
+
+* Creating a new user profile requires a user's authentication details
+(`username` and `password` or its
+<<token-authentication-services,OAuth2 access token>>).
+This means that a user must authenticate at least one time to create a
+user profile. Users who have never authenticated to {kib}
+(or another profile-aware application) won't have a user profile, and the
+<<security-api-suggest-user-profile,search user profile API>> won't return
+any results for those users.
+
+* User profiles are meant for interactive users, such as a human user who
+interacts with {kib}. Therefore, user profiles don't support API keys or
+<<service-accounts,service accounts>>.
++
+NOTE: <<token-authentication-services,OAuth2 tokens>> that represent an
+interactive end-user are supported.