Document new xpack.security.authc.* settings and related 8.0.0 breaking changes.
#61443
Conversation
azasypkin
added
Team:Docs
Team:Security
|
Pinging @elastic/kibana-security (Team:Security) |
|
Pinging @elastic/kibana-docs (Team:Docs) |
azasypkin
added
the
release_note:skip
|
|
||
| [source,yaml] | ||
| -------------------------------------------------------------------------------- | ||
| xpack.security.authc.http.schemes: [apikey, basic, something-custom] |
There was a problem hiding this comment.
note: I intentionally omitted enabled and autoSchemesEnabled settings as we don't really want users to tweak those yet, unless they know what they're doing. We may document these when we decide to set autoSchemesEnabled to false by default, but it's probably 9.0+?
There was a problem hiding this comment.
I only reviewed for technical accuracy so far. I had some grammatical nits along the way, but I decided not to comment on those because @elastic/kibana-docs is probably better suited for that review, and I didn't want you to have to make those adjustments twice (once for my poor review, and once for their better review)
| For more information about basic authentication and built-in users, see | ||
| {ref}/setting-up-authentication.html[User authentication]. | ||
|
|
||
| [[token-authentication]] | ||
| ==== Token authentication | ||
|
|
||
| Token authentication allows users to login using the same {kib} provided login form as basic authentication, and is based on the Native security realm or LDAP security realm that is provided by {es}. The token authentication provider is built on {es} token APIs. The bearer tokens returned by {es}'s {ref}/security-api-get-token.html[get token API] can be used directly with {kib} using the `Authorization` request header with the `Bearer` scheme. | ||
| Token authentication allows users to log in using the same {kib} provided login form as basic authentication, and is based on the Native security realm or LDAP security realm that is provided by {es}. The token authentication provider is built on {es} token APIs. |
There was a problem hiding this comment.
unrelated to your changes, but since we're here, we might as well add AD to the list, since it's technically supported by our basic auth provider.
| Token authentication allows users to log in using the same {kib} provided login form as basic authentication, and is based on the Native security realm or LDAP security realm that is provided by {es}. The token authentication provider is built on {es} token APIs. | |
| Token authentication allows users to log in using the same {kib} provided login form as basic authentication, and is based on the Native, LDAP, or Active Directory security realm that is provided by {es}. The token authentication provider is built on {es} token APIs. |
| [float] | ||
| ===== SAML and basic authentication | ||
|
|
||
| SAML support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both SAML and Basic authentication for the same {kib} instance: | ||
| SAML support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both SAML and Basic authentication for the same {kib} instance. This might be the case for {kib} or {es} admins whose accounts aren't linked to the Single Sign-On users database: |
There was a problem hiding this comment.
SAML support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance.
question Is this still true now that we have the login selector screen? I was thinking that all configured providers could be treated equally now
There was a problem hiding this comment.
Yeah, I was thinking about this too. Let me describe the reason behind the decision to keep this sentence and you'll tell me if it's a reasonable justification or not. The main point is that we still don't/can't handle every use case on the same level as we do when we have a single provider:
- user will still be able to log in with SAML even if selector isn't enabled. In case of multiple providers it will depend on the
order. - and small things like when
overwritten_sessionview is shown only if it's handled by the same SAML authentication provider
That's why I thought encouraging the simplest possible and well-supported scenario would make sense and advanced users will find their way in any case. But I don't really have a strong opinion on this and would appreciate your thoughts.
There was a problem hiding this comment.
Thanks for explaining! I personally think it'll be less confusing if we just omit this sentence altogether. I don't want to discourage folks from using multiple auth providers if it suites their needs, and I expect that most admins who require multiple auth providers are already in the "advanced users" category, so I'm not convinced this adds a lot of value
There was a problem hiding this comment.
Thanks for the input! Let's make it simple then, I'll remove this sentence for SAML and OpenID Connect.
There was a problem hiding this comment.
Done, for SAML, OpenID Connect and PKI.
| -------------------------------------------------------------------------------- | ||
|
|
||
| [float] | ||
| ===== OpenID Connect and basic authentication | ||
|
|
||
| Similar to SAML, OpenID Connect support in {kib} is designed to be the primary (or sole) authentication method for users | ||
| of that {kib} instance. However, you can configure both OpenID Connect and Basic authentication for the same {kib} instance: | ||
| Similar to SAML, OpenID Connect support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both OpenID Connect and Basic authentication for the same {kib} instance. This might be the case for {kib} or {es} admins whose accounts aren't linked to the Single Sign-On users database: |
There was a problem hiding this comment.
Same question here with OIDC being the primary/sole authentication method
| @@ -13,6 +13,34 @@ | |||
| - <<saml>> | |||
| - <<oidc>> | |||
| - <<kerberos>> | |||
| - <<http-authentication>> | |||
|
|
|||
| It is possible to 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. You must make sure each configured provider has a distinct name (e.g. `basic1` or `saml1` in the config example below) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start. | |||
There was a problem hiding this comment.
To match the other sections, I would remove It is possible to, then start with Enable multiple authentication ...
| @@ -13,6 +13,34 @@ | |||
| - <<saml>> | |||
| - <<oidc>> | |||
| - <<kerberos>> | |||
| - <<http-authentication>> | |||
|
|
|||
| It is possible to 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. You must make sure each configured provider has a distinct name (e.g. `basic1` or `saml1` in the config example below) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start. | |||
There was a problem hiding this comment.
For the third sentence, how about:
Make sure each configured provider has a unique name ....
There was a problem hiding this comment.
Yep, sounds much better!
| @@ -13,6 +13,34 @@ | |||
| - <<saml>> | |||
| - <<oidc>> | |||
| - <<kerberos>> | |||
| - <<http-authentication>> | |||
|
|
|||
| It is possible to 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. You must make sure each configured provider has a distinct name (e.g. `basic1` or `saml1` in the config example below) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start. | |||
There was a problem hiding this comment.
To meet accessibility standards, we are removing instances of below from our docs. Could we change this to:
(e.g. basic1 or saml1 in the configuration example)
There was a problem hiding this comment.
Wow, didn't know what, will fix. For my own edification, what is the reason below and above aren't acceptable?
There was a problem hiding this comment.
The issue was recently opened against the docs, so it is a relatively new concept for us too- #55566. From what I understand, we're going to follow these guidelines for spatial references - https://www.w3.org/WAI/WCAG21/quickref/#sensory-characteristics.
There was a problem hiding this comment.
Ah, interesting, thanks for sharing these links!
|
|
||
| It is possible to 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. You must make sure each configured provider has a distinct name (e.g. `basic1` or `saml1` in the config example below) 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 user will be presented with the Login Selector screen where they can choose which provider to use to log in to {kib}. The order provider appears in at the Login Selector screen is determined by its `order` setting. The appearance of the specific provider entry can be customized with the `description` setting. |
There was a problem hiding this comment.
Since you are talking to the user, I would change the first two sentences to:
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.
|
|
||
| When two or more providers are configured user will be presented with the Login Selector screen where they can choose which provider to use to log in to {kib}. The order provider appears in at the Login Selector screen is determined by its `order` setting. The appearance of the specific provider entry can be customized with the `description` setting. | ||
|
|
||
| If you don't want specific provider to show up at the Login Selector screen (e.g. to only support third-party initiated login) you can hide it with `showInSelector` setting set to `false`. However in this case provider will still be presented in the provider chain and may be consulted during authentication based on its `order`. To completely disable provider use `enabled` setting instead. |
There was a problem hiding this comment.
If you don't want specific provider > If you don't want a specific provider
| -------------------------------------------------------------------------------- | ||
|
|
||
| Users will be able to access the login page and use Basic authentication by navigating to the `/login` URL. | ||
| Basic authentication is supported _only_ if `basic` authentication provider is explicitly declared in `xpack.security.authc.providers` setting in addition to `oidc`. |
There was a problem hiding this comment.
_only_ if basic authentication provider > _only_ if the basic authentication provider
| -------------------------------------------------------------------------------- | ||
|
|
||
| Users will be able to access the login page and use Basic authentication by navigating to the `/login` URL. | ||
| Basic authentication is supported _only_ if `basic` authentication provider is explicitly declared in `xpack.security.authc.providers` setting in addition to `oidc`. |
There was a problem hiding this comment.
explicitly declared in xpack.security.authc.providerssetting in addition tooidc. > explicitly declared in the xpack.security.authc.providerssetting, in addition tooidc.
| Users will be able to access the login page and use Basic authentication by navigating to the `/login` URL. | ||
| Basic authentication is supported _only_ if `basic` authentication provider is explicitly declared in `xpack.security.authc.providers` setting in addition to `oidc`. | ||
|
|
||
| However, if you don't need username/password login form and just want 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) then it's recommended to add `Basic` scheme to the list of supported schemes for the <<http-authentication,HTTP authentication>> instead. |
| xpack.security.authc.http.schemes: [apikey, basic, something-custom] | ||
| -------------------------------------------------------------------------------- | ||
|
|
||
| With the configuration above users can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood {kib} will just relay this header to {es} that will try to authenticate request using the credentials provided within the header. |
There was a problem hiding this comment.
To meet accessibility standards, we are removing instances of above from the docs. I would change this to:
With this configuration, you can send requests to...
| xpack.security.authc.http.schemes: [apikey, basic, something-custom] | ||
| -------------------------------------------------------------------------------- | ||
|
|
||
| With the configuration above users can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood {kib} will just relay this header to {es} that will try to authenticate request using the credentials provided within the header. |
There was a problem hiding this comment.
I would split up and shorten the last sentence to:
Under the hood, {kib} relays this header to {es}, then {es} authenticates the request using the credentials in the header.
There was a problem hiding this comment.
Thanks for review @KOTungseth and @legrego! It should be ready for another pass.
@legrego I answered your question, but would like to hear your thoughts before I change anything.
| @@ -13,6 +13,34 @@ | |||
| - <<saml>> | |||
| - <<oidc>> | |||
| - <<kerberos>> | |||
| - <<http-authentication>> | |||
|
|
|||
| It is possible to 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. You must make sure each configured provider has a distinct name (e.g. `basic1` or `saml1` in the config example below) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start. | |||
There was a problem hiding this comment.
Yep, sounds much better!
| @@ -13,6 +13,34 @@ | |||
| - <<saml>> | |||
| - <<oidc>> | |||
| - <<kerberos>> | |||
| - <<http-authentication>> | |||
|
|
|||
| It is possible to 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. You must make sure each configured provider has a distinct name (e.g. `basic1` or `saml1` in the config example below) and `order` setting. In the event that two or more providers have the same name or `order`, {kib} will fail to start. | |||
There was a problem hiding this comment.
Wow, didn't know what, will fix. For my own edification, what is the reason below and above aren't acceptable?
| Basic authentication is supported _only_ if `basic` authentication provider is explicitly declared in `xpack.security.authc.providers` setting in addition to `saml`. | ||
|
|
||
| However, if you don't need username/password login form and just want 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) then it's recommended to add `Basic` scheme to the list of supported schemes for the <<http-authentication,HTTP authentication>> instead. |
| xpack.security.authc.http.schemes: [apikey, basic, something-custom] | ||
| -------------------------------------------------------------------------------- | ||
|
|
||
| With the configuration above users can send requests to {kib} with the `Authorization` header using `ApiKey`, `Basic` or `Something-Custom` HTTP schemes (case insensitive). Under the hood {kib} will just relay this header to {es} that will try to authenticate request using the credentials provided within the header. |
* master: (44 commits) [Alerting] add alerting privileges for uptime and metrics (elastic#61113) Update percy agent to latest version (elastic#62089) [APM] Update central configuration text (elastic#61556) [Fleet] Ouput api key do not need metricbeat* access (elastic#60319) Document new `xpack.security.authc.*` settings and related 8.0.0 breaking changes. (elastic#61443) Migrate test plugins ⇒ NP (kbn_tp_sample_panel_action) (elastic#60749) [Alerting] Add "Start trial" button for connectors (elastic#61774) [ML] Transforms: Fix handling of default and advanced search on step summary view. (elastic#61799) [Task Manager] Change info message "ran out Available Workers" to debug (elastic#62083) [Maps] Highlight selected layer in TOC (elastic#61510) ensure pageIndex is set correclty in analytics list (elastic#62041) [ML] Functional API tests - fix mml request bodies (elastic#62116) Fix validation for index threshold when selecting an index (elastic#61615) [SIEM][Detection Engine] Adds release notes link and updates one UI section [backport] Bump to 5.1.2 (elastic#62117) [APM] .apm-agent-configuration is not created if Kibana is started while ES is not ready (elastic#61610) [Fleet] Enrollment list page (elastic#61346) [ML] Fix maximum default enabled columns for data grid. (elastic#62005) [Home][Tutorial] Add Oracle data UI (elastic#61595) [APM] Ensure telemetry data matches SO/telemetry mapping (elastic#61957) ...
This PR documents a couple of recent changes in
xpack.security.authc.*settings and related 8.0.0 breaking changes.Fixes: #61117