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

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 all commits
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 the order of the provider in the authentication chain and on the Login Selector UI. This setting is mandatory.
<3> Specifies the settings for the SAML authentication provider with a `saml1` name.
<4> Specifies the settings for the SAML authentication provider with a `saml2` name.

The valid settings in the `xpack.security.authc.providers` namespace vary depending on the authentication provider type. For more information, refer to <<kibana-authentication>>.

[float]
[[authentication-provider-settings]]
===== Valid settings for all authentication providers

[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 the authentication provider should be enabled. By default, {kib} enables the provider as soon as you configure any of its properties.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.order`
| Order of the provider in the authentication chain and on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.description`
| Custom description of the provider entry displayed on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.hint`
| Custom hint for the provider entry displayed on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.icon`
| Custom icon for the provider entry displayed on the Login Selector UI.

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.showInSelector`
| Flag that indicates if the provider should have an entry on the Login Selector UI. Setting this to `false` doesn't remove the provider from the authentication chain.

|===

[NOTE]
============
You are unable to set this setting to `false` for `basic` and `token` authentication providers.
============

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

| `xpack.security.authc.providers.`
`<provider-type>.<provider-name>.accessAgreement.message`
| Access agreement text in Markdown format. For more information, refer to <<xpack-security-access-agreement>>.

|===

[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 authentication SAML handshake. For more information, refer to <<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 the provider should use.

|===

[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, refer to <<http-authentication>>.

[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 UI settings

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

|===

[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 additional help information for the login process.

|===
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

Some work environments require you to acknowledge and accept an agreement before you can access {kib}, which can contain sensitive information. The agreement text supports Markdown format and can be specified using the `xpack.security.authc.providers.<provider-type>.<provider-name>.accessAgreement.message` setting.

[NOTE]
============================================================================
You need to acknowledge the access agreement only once per session, and {kib} reports the acknowledgement in the audit logs.
============================================================================

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 ...)"
--------------------------------------------------------------------------------

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 logs

You can enable auditing to keep track of security-related events such as
authorization success and failures. Logging these events enables you
Expand Down
19 changes: 16 additions & 3 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.

TIP: To provide login instructions to users, use the `xpack.security.loginHelp` setting, which supports Markdown format. When you specify the `xpack.security.loginHelp` setting, the Login Selector UI displays a `Need help?` link that lets users access login help information.

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, refer to <<authentication-security-settings, authentication security settings>>.

[[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 Expand Up @@ -325,4 +338,4 @@ NOTE: Don't forget to explicitly specify default `apikey` scheme when you just w
xpack.security.authc.http.schemes: [apikey, basic, something-custom]
--------------------------------------------------------------------------------

With this configuration, you can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.
With this configuration, you can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.
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[]