Update docs for api authentication usage #66819

EricDavisX · 2020-05-15T20:39:22Z

Hi, if it is helpful, I put this up for review.

I'm uncertain if this is language we would want to keep, butt, even as a new Elastic employee, and a junior API user, this confused me when I tried to use Kibana via API so it seemed a spot we could try to improve. I expect we wish to avoid citation of specific HTTP tools, which I understand but this is an attempt to inform users as possible.

Checklist

The only checklist item I think might be internationalization. ...I don't know how to i18n this, but am happy to research and add it if the base English text is deemed acceptable.

For maintainers

n/a

I'm uncertain if this is an appropriate doc note to add. But, even as a new Elastic employee, this confused me when I tried to use the API so it seemed a spot we could try to improve. I expect we wish to avoid citation of specific HTTP tools, which I understand but this is an attempt to inform users as possible.

EricDavisX · 2020-05-18T22:09:14Z

Adding @LeeDr in for seniority QA opinion, do you think this is a useful API usage addition?

LeeDr · 2020-05-19T19:14:04Z

Adding a link to the master docs for reference; https://www.elastic.co/guide/en/kibana/master/using-api.html

I see the example shows passing the username and password;

curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana...

But I guess the part you're trying to elaborate on is that some specific tools may have an option for "basic authentication".

We usually only show examples in curl, so I would tend to not add something like this in the docs. The other issue is that Kibana also supports SAML, PKI, and other authentication mechanisms https://www.elastic.co/guide/en/kibana/master/kibana-authentication.html
So I'm concerned that all our existing curl examples only show basic auth.

EricDavisX · 2020-05-20T18:23:52Z

Thanks so much for the time Lee. I think it could be helpful as is, but I totally see its a little out of the normal. If we choose to close this down, no harm no worries. Just glad to ask and help with ideas.

KOTungseth

I made a small change, but otherwise, LGTM!

docs/api/using-api.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* master: Update known-plugins.asciidoc (elastic#69370) [ML] Anomaly Explorer swim lane pagination (elastic#70063) [Ingest Manager] Update asset paths to use _ instead of - (elastic#70320) Fix discover, tsvb and Lens chart theming issues (elastic#69695) Allow Saved Object type mappings to set a field's `doc_values` property (elastic#70433) [S&R] Support data streams (elastic#68078) [Maps] Add styling and tooltip support to mapbox mvt vector tile sources (elastic#64488) redirect to default app if hash can not be forwarded (elastic#70417) [APM] Don't fetch dynamic index pattern in setupRequest (elastic#70308) [Security_Solution][Endpoint] Leveraging msearch and ancestry array for resolver (elastic#70134) Update docs for api authentication usage (elastic#66819) chore(NA): disable alerts_detection_rules cypress suites (elastic#70577) add getVisibleTypes API to SO type registry (elastic#70559)

kibanamachine · 2020-07-06T11:58:44Z