Document PKI authentication provider. #43572
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
azasypkin
added
Team:Docs
blocked
Team:Security
|
Pinging @elastic/kibana-docs |
|
Pinging @elastic/kibana-security |
azasypkin
added
the
release_note:skip
azasypkin
commented
Aug 20, 2019
| 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. |
There was a problem hiding this comment.
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 🤷♂️ .
7 tasks
azasypkin
commented
Aug 20, 2019
| @@ -44,6 +45,31 @@ The token authentication provider can be used in conjunction with the basic auth | |||
| xpack.security.authc.providers: [token, basic] | |||
| -------------------------------------------------------------------------------- | |||
|
|
|||
| [[pki-authentication]] | |||
There was a problem hiding this comment.
note: I'll double check all the links once ES documentation PR I reference to lands.
There was a problem hiding this comment.
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 😬
There was a problem hiding this comment.
Sure thing, there was no plan to merge this before ES docs change reaches upstream master 😛
💔 Build Failed |
gchaps
reviewed
Aug 20, 2019
| [[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. |
There was a problem hiding this comment.
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. |
|
|
||
| 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. |
There was a problem hiding this comment.
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. |
|
|
||
| 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`: |
There was a problem hiding this comment.
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`: |
| 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. |
There was a problem hiding this comment.
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
reviewed
Aug 20, 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. |
There was a problem hiding this comment.
These links to the Elasticsearch reference are broken:
- configuring-pki-realm.html
- delegate-pki-authentication.html
There was a problem hiding this comment.
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.
|
Thanks a lot for review @gchaps, everything should be handled now! |
💔 Build Failed |
|
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. |
💔 Build Failed |
|
retest |
💔 Build Failed |
kobelb
approved these changes
Aug 26, 2019
💔 Build Failed |
💚 Build Succeeded |
gchaps
reviewed
Aug 27, 2019
Co-Authored-By: gchaps <[email protected]>
|
Thanks @gchaps, applied all your suggestions! |
💔 Build Failed |
💚 Build Succeeded |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Document PKI authentication provider.
Blocked by: #42606, elastic/elasticsearch#45906