Document creating user sessions with the API and CLI (OSS)

[jstirnaman]

Describe creating and managing user sessions, how they relate to authorizations, and how they convey API token permissions.

Example

In my app, I could have a user login to create a session that comes with all the permissions of the users' API tokens and member/owner role information? I know most of the Grace tests create sessions, but didn't know if that was a thing app builders used outside of our UI.

Background

Currently, ‘user’ is mostly a UI-specific concept.
At the API level we understand session authentication, but there are likely few implementations beyond InfluxDB UI.
You can create user sessions with the API and OSS CLI (as of v2.4: influxdata/influx-cli#418).

In OSS, the session login in the CLI inherits the user's auths. Developers can implement that to give their users access. Sessions are only good for ~10 minutes and are only stored in memory (so they die on a restart).
Influx CLI gets around this by either saving the password and getting a new session every command, or prompting for the password every command. An integrating application would likely want to do something similar.

In IDPE, as of multi-org, a user's auths are no longer aggregated from across organizations when creating a session; for a user to be in multiple orgs and a user session to be scoped to a single org, the session must only include auths for a single org.

Relevant URLs

https://influxdata.slack.com/archives/C89G3JD2R/p1661783294199359?thread_ts=1661180085.789819&cid=C89G3JD2R
influxdata/openapi#376