Skip to content
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

Jump to bottom

Document authentication settings. #69284

Merged
merged 5 commits into from
Jun 18, 2020
Merged

Document authentication settings. #69284

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5e59bb9
Document authentication settings.
azasypkin Jun 16, 2020
0220b73
Apply suggestions from code review
azasypkin Jun 18, 2020
c910eec
Merge branch 'master' into issue-64054-authc-docs
azasypkin Jun 18, 2020
01cea76
Few more suggestions.
azasypkin Jun 18, 2020
e101052
Review#2: handle review feedback.
azasypkin Jun 18, 2020
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
147 changes: 147 additions & 0 deletions docs/settings/security-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,150 @@ You do not need to configure any additional settings to use the

|===

[float]
[[authentication-security-settings]]
==== Authentication security settings

You configure authentication settings in the `xpack.security.authc` namespace in `kibana.yml`.

For example:

[source,yaml]
----------------------------------------
xpack.security.authc:
providers:
basic.basic1: <1>
order: 0 <2>
...

saml.saml1: <3>
order: 1
...

saml.saml2: <4>
order: 2
...

pki.realm3:
order: 3
...
...
----------------------------------------
<1> Specifies the type of authentication provider (for example, `basic`, `token`, `saml`, `oidc`, `kerberos`, `pki`) and the provider name. This setting is mandatory.
<2> Specifies order of the provider in the authentication chain and at the Login Selector UI. This setting is mandatory.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved
<3> Specifies settings for the SAML authentication provider with a `saml1` name.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved
<4> Specifies settings for the SAML authentication provider with a `saml2` name.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

The valid settings in `xpack.security.authc.providers` namespace vary depending on the authentication provider type. For more information, see <<kibana-authentication>>.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

[float]
[[authentication-provider-settings]]
===== Settings valid for all authentication providers
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

[cols="2*<"]
|===
| `xpack.security.authc.providers.`
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: the setting name is super long and it leaves a tiny space for the setting description itself. I didn't manage to find a better way to make it readable. Another alternative I was considering is omitting xpack.security.authc.providers. prefix completely and explaining that all settings in this section are assumed to have one. But it didn't look well with the rest of the settings we describe in this file.

Happy to hear any suggestions!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't worry about the spacing issues in the tables. Gail is changing the tables into definition lists, so the spacing issue should work itself out.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it, thanks! I'll remove my workaround then.

`<provider-type>.<provider-name>.enabled`
| Determines if authentication provider should be enabled. By default, {kib} enables provider as soon as you configure any of its properties.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.order`
| Order of the provider in the authentication chain and in the Login Selector UI.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.description`
| Custom description of the provider entry displayed at the Login Selector UI.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.hint`
| Custom hint for the provider entry displayed at the Login Selector UI.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.icon`
| Custom icon for the provider entry displayed at the Login Selector UI.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.showInSelector`
| Flag indicating if provider should have an entry at the Login Selector UI. Setting this to `false` doesn't remove provider from the authentication chain.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

|===

[NOTE]
============
It's not allowed to set this setting to `false` for `basic` and `token` authentication providers.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved
============

[cols="2*<"]
|===

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.accessAgreement.message`
| Access agreement text in Markdown format. For more information, see <<xpack-security-access-agreement>>.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

|===

[float]
[[saml-authentication-provider-settings]]
===== SAML authentication provider settings

In addition to <<authentication-provider-settings,the settings that are valid for all providers>>, you can specify the following settings:

[cols="2*<"]
|===
| `xpack.security.authc.providers.`
`saml.<provider-name>.realm`
| SAML realm in {es} that provider should use.

| `xpack.security.authc.providers.`
`saml.<provider-name>.maxRedirectURLSize`
| The maximum size of the URL that {kib} is allowed to store during the SAML handshake. See <<security-saml-and-long-urls>>.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| The maximum size of the URL that {kib} is allowed to store during the SAML handshake. See <<security-saml-and-long-urls>>.
| The maximum size of the URL that {kib} is allowed to store during the SAML authentication handshake. See <<security-saml-and-long-urls>>.


|===

[float]
[[oidc-authentication-provider-settings]]
===== OpenID Connect authentication provider settings

In addition to <<authentication-provider-settings,the settings that are valid for all providers>>, you can specify the following settings:

[cols="2*<"]
|===
| `xpack.security.authc.providers.`
`oidc.<provider-name>.realm`
| OpenID Connect realm in {es} that provider should use.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

|===

[float]
[[http-authentication-settings]]
===== HTTP authentication settings

There is a very limited set of cases when you'd want to change these settings. For more information, see <<http-authentication>>.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

[cols="2*<"]
|===
| `xpack.security.authc.http.enabled`
| Determines if HTTP authentication should be enabled. By default, this setting is set to `true`.

| `xpack.security.authc.http.autoSchemesEnabled`
| Determines if HTTP authentication schemes used by the enabled authentication providers should be automatically supported during HTTP authentication. By default, this setting is set to `true`.

| `xpack.security.authc.http.schemes`
| List of HTTP authentication schemes that {kib} HTTP authentication should support. By default, this setting is set to `['apikey']` to support HTTP authentication with <<api-keys, `ApiKey`>> scheme.

|===

[float]
[[login-selector-settings]]
===== Login Selector settings
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

[cols="2*<"]
|===
| `xpack.security.authc.selector.enabled`
| Determines if Login Selector UI should be enabled. By default, this setting is set to `true` if more than one authentication provider is configured.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

|===

[float]
[[security-ui-settings]]
==== User interface security settings
Expand Down Expand Up @@ -96,4 +240,7 @@ string of `<count>[ms|s|m|h|d|w|M|Y]` (e.g. '70ms', '5s', '3d', '1Y').
| `xpack.security.loginAssistanceMessage`
| Adds a message to the login screen. Useful for displaying information about maintenance windows, links to corporate sign up pages etc.

| `xpack.security.loginHelp`
| Adds a message accessible at the Login Selector UI with an additional help information around the login process.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

|===
27 changes: 27 additions & 0 deletions docs/user/security/access-agreement.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
[role="xpack"]
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: didn't find any existing suitable section for this feature, so create a new one.

[[xpack-security-access-agreement]]
=== Access Agreement
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

Some work environments require you to acknowledge and accept an agreement before accessing a product that may contain sensitive information. You can define such an agreement individually for every authentication provider in {kib} as well. The agreement text supports Markdown format and can be specified using `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Some work environments require you to acknowledge and accept an agreement before accessing a product that may contain sensitive information. You can define such an agreement individually for every authentication provider in {kib} as well. The agreement text supports Markdown format and can be specified using `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.
Some work environments require you to acknowledge and accept an agreement before accessing a product that may contain sensitive information. The agreement text supports Markdown format and can be specified using `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Some work environments require you to acknowledge and accept an agreement before accessing a product that may contain sensitive information. You can define such an agreement individually for every authentication provider in {kib} as well. The agreement text supports Markdown format and can be specified using `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.
Some work environments require you to acknowledge and accept an agreement before accessing a product that may contain sensitive information. You can define such an agreement individually for every authentication provider in {kib} as well. The agreement text supports Markdown format and can be specified using the `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.


[NOTE]
============================================================================
Users need to acknowledge access agreement only once per session, and {kib} will record the fact of acknowledgement in the audit logs.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved
============================================================================

Here is how your `kibana.yml` can look like if you define an access agreement:

[source,yaml]
--------------------------------------------------------------------------------
xpack.security.authc.providers:
basic.basic1:
order: 0
accessAgreement:
message: "**You are accessing a system with a sensitive information** \n\n
By logging in, you acknowledge that (shortened ...)"
--------------------------------------------------------------------------------

As a result users that authenticated using `basic.basic1` authentication provider will see the following agreement that they have to acknowledge before they can access anything else in {kib}:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
As a result users that authenticated using `basic.basic1` authentication provider will see the following agreement that they have to acknowledge before they can access anything else in {kib}:
When you authenticate using `basic.basic1`, the authentication provider sees the following agreement that you must acknowledge before you can access {kib}:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about this one. the authentication provider sees the following agreement - I wanted to say that user (or you in this context) sees this UI with the agreement, not the provider. Would this work or there are too many you?:

When you authenticate using `basic.basic1`, you'll see the following agreement that you must acknowledge before you can access {kib}:


[role="screenshot"]
image::user/security/images/access-agreement.png["Access Agreement UI"]
2 changes: 1 addition & 1 deletion docs/user/security/audit-logging.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[role="xpack"]
[[xpack-security-audit-logging]]
=== Audit Logging
=== Audit Logging
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

You can enable auditing to keep track of security-related events such as
authorization success and failures. Logging these events enables you
Expand Down
17 changes: 15 additions & 2 deletions docs/user/security/authentication/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,22 +17,29 @@

Enable multiple authentication mechanisms at the same time specifying a prioritized list of the authentication _providers_ (typically of various types) in the configuration. Providers are consulted in ascending order. Make sure each configured provider has a unique name (e.g. `basic1` or `saml1` in the configuration example) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start.

When two or more providers are configured, you can choose the provider you want to use on the Login Selector UI. The order the providers appear is determined by the order setting. The appearance of the specific provider entry can be customized with the `description` setting.
When two or more providers are configured, you can choose the provider you want to use on the Login Selector UI. The order the providers appear is determined by the `order` setting. The appearance of the specific provider entry can be customized with the `description`, `hint` and `icon` settings.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

TIP: You can also provide users with a more generic guidance on the login process using `xpack.security.loginHelp` setting that supports Markdown format. When you specify this setting Login Selector UI will display a `Need help?` link that will let users to access an additional help information.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: a more generic guidance on the login process sounds .... weird... 🙈 This setting is supposed to explain users what login method to use, maybe provide help/reset-password links etc.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:

To provide login instructions to users, use the xpack.security.loginHelp setting, which support Markdown.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, thanks!

azasypkin marked this conversation as resolved.
Show resolved Hide resolved

If you don't want a specific provider to show up at the Login Selector UI (e.g. to only support third-party initiated login) you can hide it with `showInSelector` setting set to `false`. However, in this case, the provider is presented in the provider chain and may be consulted during authentication based on its `order`. To disable the provider, use the `enabled` setting.

TIP: The Login Selector UI can also be disabled or enabled with `xpack.security.authc.selector.enabled` setting.

Here is how your `kibana.yml` can look like if you deal with multiple authentication providers:
Here is how your `kibana.yml` and Login Selector UI can look like if you deal with multiple authentication providers:

[source,yaml]
--------------------------------------------------------------------------------
xpack.security.loginHelp: "**Help** info with a [link](...)"
xpack.security.authc.providers:
basic.basic1:
order: 0
icon: "logoElasticsearch"
hint: "Typically for administrators"
saml.saml1:
order: 1
realm: saml1
description: "Log in with SSO"
icon: "https://my-company.xyz/saml-logo.svg"
saml.saml2:
order: 2
realm: saml2
Expand All @@ -42,6 +49,11 @@ xpack.security.authc.providers:
enabled: false
--------------------------------------------------------------------------------

[role="screenshot"]
image::user/security/images/kibana-login.png["Login Selector UI"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: given the configuration above, shouldn't I expect to see the Kerberos realm in this screenshot?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope it's enabled: false 🙂

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept it to show that enabled also affects selector (obviously though), but I can remove if it's more confusing than helpful?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I missed that!


For more information, see <<authentication-security-settings, authentication security settings>>.
azasypkin marked this conversation as resolved.
Show resolved Hide resolved

[[basic-authentication]]
==== Basic authentication

Expand Down Expand Up @@ -170,6 +182,7 @@ Basic authentication is supported _only_ if the `basic` authentication provider
To support basic authentication for the applications like `curl` or when the `Authorization: Basic base64(username:password)` HTTP header is included in the request (for example, by reverse proxy), add `Basic` scheme to the list of supported schemes for the <<http-authentication,HTTP authentication>>.

[float]
[[security-saml-and-long-urls]]
===== SAML and long URLs

At the beginning of the SAML handshake, {kib} stores the initial URL in the session cookie, so it can redirect the user back to that URL after successful SAML authentication.
Expand Down
Binary file added docs/user/security/images/access-agreement.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/user/security/images/kibana-login.jpg
View file
Open in desktop
Binary file not shown.
Binary file added docs/user/security/images/kibana-login.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/user/security/securing-kibana.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,4 @@ include::authentication/index.asciidoc[]
include::securing-communications/index.asciidoc[]
include::securing-communications/elasticsearch-mutual-tls.asciidoc[]
include::audit-logging.asciidoc[]
include::access-agreement.asciidoc[]