Document PKI authentication provider. by azasypkin · Pull Request #43572 · elastic/kibana

azasypkin · 2019-08-20T09:33:43Z

Document PKI authentication provider.

~~Blocked by: #42606, elastic/elasticsearch#45906~~

elasticmachine · 2019-08-20T09:33:45Z

Pinging @elastic/kibana-docs

elasticmachine · 2019-08-20T09:33:46Z

Pinging @elastic/kibana-security

azasypkin · 2019-08-20T09:35:50Z

docs/security/authentication/index.asciidoc

+xpack.security.authc.providers: [pki, basic]
+--------------------------------------------------------------------------------
+
+Please, note that with `server.ssl.clientAuthentication` set to `required` user will be asked to provide a valid client certificate even if they want to authenticate with username and password. Depending on the security policies it may or may not be desired, and if it's not `server.ssl.clientAuthentication` can be set to `optional`. In this case {kib} will still request a client certificate but the client won't be required to present one. The `optional` client authentication mode can also be needed in some other cases, e.g. when PKI authentication is used in conjunction with Reporting.


note: I was initially planning to put the last sentence somewhere here, but I don't see that it mentions other limitations we have with Reporting + SAML/OIDC/Token so went the simplest route 🤷‍♂️ .

azasypkin · 2019-08-20T09:38:46Z

docs/security/authentication/index.asciidoc

 xpack.security.authc.providers: [token, basic]
 --------------------------------------------------------------------------------

+[[pki-authentication]]


note: I'll double check all the links once ES documentation PR I reference to lands.

We'll want to ensure the doc links work before merging this PR. There's a step that is ran by the docs CI which will start failing their build if the links don't work 😬

Sure thing, there was no plan to merge this before ES docs change reaches upstream master 😛

elasticmachine · 2019-08-20T10:34:28Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request

gchaps · 2019-08-20T20:06:54Z

docs/security/authentication/index.asciidoc

+[[pki-authentication]]
+==== Public Key Infrastructure (PKI) Authentication
+
+PKI authentication allows users to login into {kib} using X.509 client certificates that should be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on {es}'s {ref}/delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. And all subsequent requests to {es}'s APIs on behalf of the users will be authenticated using these access tokens.


Suggested change

PKI authentication allows users to login into {kib} using X.509 client certificates that should be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on {es}'s {ref}/delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. And all subsequent requests to {es}'s APIs on behalf of the users will be authenticated using these access tokens.

PKI authentication allows users to log in to {kib} using X.509 client certificates that must be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on {es}'s {ref}/delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. And all subsequent requests to {es}'s APIs on behalf of the users will be authenticated using these access tokens.

gchaps · 2019-08-20T20:09:31Z

docs/security/authentication/index.asciidoc

+
+PKI authentication allows users to login into {kib} using X.509 client certificates that should be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on {es}'s {ref}/delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. And all subsequent requests to {es}'s APIs on behalf of the users will be authenticated using these access tokens.
+
+Prior to configuring {kib}, ensure that PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.


Suggested change

Prior to configuring {kib}, ensure that PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.

Prior to configuring {kib}, ensure that the PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.

gchaps · 2019-08-20T20:11:35Z

docs/security/authentication/index.asciidoc

+
+Prior to configuring {kib}, ensure that PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.
+
+To enable the PKI authentication provider in {kib}, you first need to <<configuring-tls,configure {kib} to encrypt communications between browser and {kib} server>>. Once it's done you need to additionally enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into list of CAs trusted by {kib} in your `kibana.yml`:


Suggested change

To enable the PKI authentication provider in {kib}, you first need to <<configuring-tls,configure {kib} to encrypt communications between browser and {kib} server>>. Once it's done you need to additionally enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into list of CAs trusted by {kib} in your `kibana.yml`:

To enable the PKI authentication provider in {kib}, you first need to <<configuring-tls,configure {kib} to encrypt communications between the browser and {kib} server>>. Once it's done, you need to additionally enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into a list of CAs trusted by {kib} in your `kibana.yml`:

gchaps · 2019-08-20T20:13:11Z

docs/security/authentication/index.asciidoc

+xpack.security.authc.providers: [pki, basic]
+--------------------------------------------------------------------------------
+
+Please, note that with `server.ssl.clientAuthentication` set to `required` user will be asked to provide a valid client certificate even if they want to authenticate with username and password. Depending on the security policies it may or may not be desired, and if it's not `server.ssl.clientAuthentication` can be set to `optional`. In this case {kib} will still request a client certificate but the client won't be required to present one. The `optional` client authentication mode can also be needed in some other cases, e.g. when PKI authentication is used in conjunction with Reporting.


Suggested change

Please, note that with `server.ssl.clientAuthentication` set to `required` user will be asked to provide a valid client certificate even if they want to authenticate with username and password. Depending on the security policies it may or may not be desired, and if it's not `server.ssl.clientAuthentication` can be set to `optional`. In this case {kib} will still request a client certificate but the client won't be required to present one. The `optional` client authentication mode can also be needed in some other cases, e.g. when PKI authentication is used in conjunction with Reporting.

Please note that with `server.ssl.clientAuthentication` set to `required`, users will be asked to provide a valid client certificate even if they want to authenticate with username and password. Depending on the security policies, it may or may not be desired, and if not, `server.ssl.clientAuthentication` can be set to `optional`. In this case {kib} will still request a client certificate but the client won't be required to present one. The `optional` client authentication mode can also be needed in some other cases, e.g. when PKI authentication is used in conjunction with Reporting.

gchaps · 2019-08-20T20:25:57Z

docs/security/authentication/index.asciidoc

+
+PKI authentication allows users to login into {kib} using X.509 client certificates that should be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on {es}'s {ref}/delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. And all subsequent requests to {es}'s APIs on behalf of the users will be authenticated using these access tokens.
+
+Prior to configuring {kib}, ensure that PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.


These links to the Elasticsearch reference are broken:

configuring-pki-realm.html

delegate-pki-authentication.html

Yeah, we're still waiting for ES docs PR: ttps://github.com/elastic/elasticsearch/pull/45259. Will double check that links work as soon as ES PR lands.

azasypkin · 2019-08-21T08:23:09Z

Thanks a lot for review @gchaps, everything should be handled now!

elasticmachine · 2019-08-21T09:21:32Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request

kobelb · 2019-08-21T17:21:38Z

Should we add any disclaimers about http layer reverse-proxies preventing the ability to request the client's certificates?

azasypkin · 2019-08-22T08:02:47Z

Should we add any disclaimers about http layer reverse-proxies preventing the ability to request the client's certificates?

Hmm, I think it's a good idea, thanks! I don't see ES PKI docs expand on this though, but I'd agree that proxies are usually used with Kibana than ES.

elasticmachine · 2019-08-22T08:32:47Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request

azasypkin · 2019-08-22T08:34:04Z

retest

elasticmachine · 2019-08-22T08:35:05Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request

azasypkin · 2019-08-26T17:03:00Z

@kobelb @gchaps ES documentation PR has landed and I've corrected the links. PR is ready for another pass, thanks!

elasticmachine · 2019-08-26T18:48:13Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request

elasticmachine · 2019-08-27T18:13:51Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request

docs/security/authentication/index.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

azasypkin · 2019-08-27T22:23:35Z

Thanks @gchaps, applied all your suggestions!

elasticmachine · 2019-08-28T00:00:24Z

💔 Build Failed

continuous-integration/kibana-ci/pull-request

elasticmachine · 2019-08-29T17:33:09Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request

gchaps

Built locally. LGTM

azasypkin · 2019-08-30T19:33:13Z

7.4/7.4.0: f60cd27
7.x/7.5.0: e8a68ef

Document PKI authentication provider.

b0bbd70

azasypkin added Team:Docs blocked Team:Security Platform Security: Auth, Users, Roles, Spaces, Audit Logging, etc t// Feature:Security/Authentication Platform Security - Authentication v7.4.0 labels Aug 20, 2019

azasypkin requested a review from kobelb August 20, 2019 09:33

azasypkin added the release_note:skip Skip the PR/issue when compiling release notes label Aug 20, 2019

azasypkin commented Aug 20, 2019

View reviewed changes

azasypkin mentioned this pull request Aug 20, 2019

Introduce PKI authentication provider. #42606

Merged

7 tasks

azasypkin commented Aug 20, 2019

View reviewed changes

gchaps reviewed Aug 20, 2019

View reviewed changes

azasypkin added 2 commits August 21, 2019 09:45

Merge branch 'master' into issue-xxx-pki-docs

b58e111

Review#1: handle review feedback from Gail.

ea33b71

azasypkin added 2 commits August 22, 2019 10:03

Merge branch 'master' into issue-xxx-pki-docs

4056994

Review#2: add a note about TLS termination reverse proxies.

1361aad

azasypkin added 2 commits August 26, 2019 18:46

Merge branch 'master' into issue-xxx-pki-docs

83e6f74

Fix links.

b652b5b

azasypkin requested a review from gchaps August 26, 2019 17:01

kobelb approved these changes Aug 26, 2019

View reviewed changes

azasypkin removed the blocked label Aug 27, 2019

Merge branch 'master' into issue-xxx-pki-docs

18f5631

gchaps reviewed Aug 27, 2019

View reviewed changes

Apply suggestions from code review

1d53b43

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

azasypkin requested a review from gchaps August 28, 2019 06:22

Merge branch 'master' into issue-xxx-pki-docs

a4f8a6c

azasypkin added the v7.5.0 label Aug 30, 2019

gchaps approved these changes Aug 30, 2019

View reviewed changes

azasypkin merged commit 7fa4860 into elastic:master Aug 30, 2019

azasypkin deleted the issue-xxx-pki-docs branch August 30, 2019 17:33

azasypkin mentioned this pull request Aug 30, 2019

[7.x] Document PKI authentication provider. (#43572) #44523

Merged

azasypkin added the backport pending label Aug 30, 2019

azasypkin added a commit to azasypkin/kibana that referenced this pull request Aug 30, 2019

Document PKI authentication provider. (elastic#43572)

71787ca

azasypkin mentioned this pull request Aug 30, 2019

[7.4] Document PKI authentication provider. (#43572) #44524

Merged

azasypkin added backported and removed backport pending labels Aug 30, 2019


		PKI authentication allows users to login into {kib} using X.509 client certificates that should be presented while connecting to {kib}. The certificates must first be accepted for authentication on the {kib} TLS layer and then they are further validated by an {es} PKI realm. The PKI authentication provider relies on {es}'s {ref}/delegate-pki-authentication.html[Delegate PKI authentication API] to exchange X.509 client certificates to access tokens. And all subsequent requests to {es}'s APIs on behalf of the users will be authenticated using these access tokens.

		Prior to configuring {kib}, ensure that PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.


		Prior to configuring {kib}, ensure that PKI realm is enabled in {es} and configured to permit delegation. See {xpack-ref}/configuring-pki-realm.html[Configuring a PKI realm] for more information.

		To enable the PKI authentication provider in {kib}, you first need to <<configuring-tls,configure {kib} to encrypt communications between browser and {kib} server>>. Once it's done you need to additionally enable TLS client authentication and include the certificate authority (CA) used to sign client certificates into list of CAs trusted by {kib} in your `kibana.yml`:

Conversation

azasypkin commented Aug 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elasticmachine commented Aug 20, 2019

Uh oh!

elasticmachine commented Aug 20, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Aug 20, 2019

💔 Build Failed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azasypkin commented Aug 21, 2019

Uh oh!

elasticmachine commented Aug 21, 2019

💔 Build Failed

Uh oh!

kobelb commented Aug 21, 2019

Uh oh!

azasypkin commented Aug 22, 2019

Uh oh!

elasticmachine commented Aug 22, 2019

💔 Build Failed

Uh oh!

azasypkin commented Aug 22, 2019

Uh oh!

elasticmachine commented Aug 22, 2019

💔 Build Failed

Uh oh!

azasypkin commented Aug 26, 2019

Uh oh!

elasticmachine commented Aug 26, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Aug 27, 2019

💚 Build Succeeded

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

azasypkin commented Aug 27, 2019

Uh oh!

elasticmachine commented Aug 28, 2019

💔 Build Failed

Uh oh!

elasticmachine commented Aug 29, 2019

💚 Build Succeeded

Uh oh!

gchaps left a comment

Choose a reason for hiding this comment

Uh oh!

azasypkin commented Aug 30, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

azasypkin commented Aug 20, 2019 •

edited

Loading