diff --git a/docs/settings/security-settings.asciidoc b/docs/settings/security-settings.asciidoc index 7ffb6b66f5a2b..bd714c62ff543 100644 --- a/docs/settings/security-settings.asciidoc +++ b/docs/settings/security-settings.asciidoc @@ -264,7 +264,7 @@ You can configure the following settings in the `kibana.yml` file. this to `true` if SSL is configured outside of {kib} (for example, you are routing requests through a load balancer or proxy). -| `xpack.security.sameSiteCookies` {ess-icon} +| [[xpack-security-sameSiteCookies]] `xpack.security.sameSiteCookies` {ess-icon} | Sets the `SameSite` attribute of the session cookie. This allows you to declare whether your cookie should be restricted to a first-party or same-site context. Valid values are `Strict`, `Lax`, `None`. This is *not set* by default, which modern browsers will treat as `Lax`. If you use Kibana embedded in an iframe in modern browsers, you might need to set it to `None`. Setting this value to `None` requires cookies to be sent over a secure connection by setting <>: `true`. diff --git a/docs/setup/embedding.asciidoc b/docs/setup/embedding.asciidoc new file mode 100644 index 0000000000000..1b20baf66913a --- /dev/null +++ b/docs/setup/embedding.asciidoc @@ -0,0 +1,55 @@ +[[embedding]] +== Embed {kib} content in a web page + +Once you create a dashboard or a visualization, you might want to share it with your colleagues or friends. The easiest way to do this is to share a direct link to your dashboard or visualization. However, some users might not have access to your {kib}. + +With the {kib} embedding functionality, you can display the content you created in {kib} to an internal company website or a personal web page. From *Dashboard* or *Visualize*, open the *Share > Embed code* menu, and then click *Copy iFrame code* to generate an HTML code snippet. You can embed this snippet in your web page, and then add analysis, images, and links to give more context to the object you're sharing. + +image::images/embed-kibana.png[Generate an HTML snippet to embed {kib}, align=center] + +NOTE: Embedding of any other part of {kib} is also generally possible, but you might need to craft the proper HTML code manually. + +[float] +[[embedding-security]] +=== Configure security + +Embedding content through iframes requires careful consideration to minimize security risks. By default, modern web browsers enforce the +https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy[same-origin policy] to restrict the behavior of framed pages. When +{stack-security-features} are enabled on your cluster, you must relax this constraint for cookies as described in <> for {kib} to function +in an iframe. Refer to https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe[iframe] and +https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite cookies] for more information. + +[float] +==== Authentication +If you're embedding {kib} in a website that supports Single Sign-On with SAML, OpenID Connect, Kerberos, or PKI, it's highly advisable to configure {kib} as a part of the Single Sign-On setup. Operating in a single and properly configured security domain provides you with the most secure and seamless user experience. You can read more at <>. + +If you want users to access embedded {kib} by skipping the login step, and Single Sign-On isn't an option for you, consider configuring <>. It is already natively integrated into the workflow for embedding dashboards and visualizations. + +If you have multiple authentication providers enabled, and you want to automatically log in anonymous users when embedding anything other than dashboards and visualizations, then you will need to add the `auth_provider_hint=` query string parameter to the {kib} URL that you're embedding. + +For example, if you craft the iframe code to embed {kib}, it might look like this: + +```html + +``` + +To make this iframe leverage anonymous access automatically, you will need to modify a link to {kib} in the `src` iframe attribute to look like this: + +```html + +``` + +Note that the `auth_provider_hint` query string parameter goes *before* the hash URL fragment. + +[float] +[[embedding-cookies]] +==== Cookies + +Regardless of the authentication type that you're using for the embedded {kib}, you must make sure that the browsers can transmit session cookies to a {kib} server. The setting you need to be aware of is <>. To support modern browsers, you must set it to `None`: + +[source,yaml] +-- +xpack.security.sameSiteCookies: "None" +-- + +For more information about possible values and implications, go to <>. \ No newline at end of file diff --git a/docs/setup/images/embed-kibana.png b/docs/setup/images/embed-kibana.png new file mode 100644 index 0000000000000..f3b0f542361fd Binary files /dev/null and b/docs/setup/images/embed-kibana.png differ diff --git a/docs/user/security/authentication/index.asciidoc b/docs/user/security/authentication/index.asciidoc index c28f5fd1d923b..b3be4d64921cd 100644 --- a/docs/user/security/authentication/index.asciidoc +++ b/docs/user/security/authentication/index.asciidoc @@ -383,21 +383,13 @@ xpack.security.authc.providers: One of the most popular use cases for anonymous access is when you embed {kib} into other applications and don't want to force your users to log in to view it. If you configured {kib} to use anonymous access as the sole authentication mechanism, you don't need to do anything special while embedding {kib}. -If you have multiple authentication providers enabled, and you want to automatically log in anonymous users when embedding, then you will need to add the `auth_provider_hint=` query string parameter to the {kib} URL that you're embedding. +If you have multiple authentication providers enabled, and you want to automatically log in anonymous users when embedding dashboards and visualizations, then toggle *Public URL* in the *Share > Embed code* menu in *Dashboard* or *Visualize*. -For example, if you generate the iframe code to embed {kib}, it will look like this: +You can also use the *Public URL* toggle when you're generating permanent links to dashboards, visualizations, and saved searches. -```html - -``` +NOTE: The *Public URL* toggle is only available if anonymous access is properly configured and your anonymous service account has privileges to access what you want to embed or share. -To make this iframe leverage anonymous access automatically, you will need to modify a link to {kib} in the `src` iframe attribute to look like this: - -```html - -``` - -Note that `auth_provider_hint` query string parameter goes *before* the hash URL fragment. +For more information, refer to <>. [[http-authentication]] ==== HTTP authentication diff --git a/docs/user/setup.asciidoc b/docs/user/setup.asciidoc index 54bdfff8e0bbb..ba848681689b6 100644 --- a/docs/user/setup.asciidoc +++ b/docs/user/setup.asciidoc @@ -59,3 +59,5 @@ include::{kib-repo-dir}/setup/connect-to-elasticsearch.asciidoc[] include::{kib-repo-dir}/setup/production.asciidoc[] include::{kib-repo-dir}/setup/upgrade.asciidoc[] + +include::{kib-repo-dir}/setup/embedding.asciidoc[]