cockroach auth-session

To create and manage web sessions and authentication tokens to the HTTP interface from the command line, use the cockroach auth-session with the appropriate subcommands and flags.

Subcommands

Subcommand	Usage
login	Authenticate a user against a running cluster’s HTTP interface, generating an HTTP authentication token (a “cookie”) which can also be used by non-interactive HTTP-based database management tools. Must be used with a valid, existing user. May be used to generate a cookie for the root user.
logout	Revokes all previously-issued HTTP authentication tokens for the given user.
list	List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions.

Synopsis

Log in to the HTTP interface, generating an HTTP authentication token for a given user:

$ cockroach auth-session login {username} [flags]

Log out from the HTTP interface, revoking all active HTTP authentication tokens for a given user:

$ cockroach auth-session logout {username} [flags]

List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions:

$ cockroach auth-session list [flags]

View help:

$ cockroach auth-session --help

$ cockroach auth-session {subcommand} --help

Flags

All three auth-session subcommands accept the standard .

In addition, the auth-session login subcommand supports the following flags.

Flag	Description
--expire-after	Duration of the newly-created HTTP authentication token, after which the token expires. Specify the duration in numeric values suffixed by one or more of h, m, and s to indicate hour, minute, and second duration. See the example. Default: 1h0m0s (1 hour)
--only-cookie	Limits output to only the newly-created HTTP authentication token (the “cookie”) in the response, appropriate for output to other commands. See the example.

Response

The cockroach auth-session subcommands return the following fields.

auth-session login

Field	Description
username	The username of the user authenticated.
session ID	The session ID to the HTTP interface previously established for that user.
authentication cookie	The cookie that may be used from the command line, or from other tools, to authenticate access to the HTTP interface for that user.

auth-session logout

Field	Description
username	The username of the user whose session was revoked.
session ID	The session ID to the HTTP interface previously established for that user.
revoked	The date and time of revocation for that user’s authenticated session.

auth-session list

Field	Description
username	The username of the user authenticated.
session ID	The session ID to the HTTP interface established for that user.
created	The date and time a session was created.
expired	The date and time a session expired.
revoked	The date and time of revocation for that user’s authenticated session. If the session is still active, this will appear as NULL.
last used	The date and time of the last access to the HTTP interface using this session token.

Required roles

To run any of the auth-session subcommands, you must be a member of the . The user being authenticated via login or logout does not require any special roles.

Considerations

• The login subcommand allows users with the to create HTTP authentication tokens with an arbitrary duration. If operational policy requires stricter control of authentication sessions, you can:

  • Monitor the system.web_sessions table for all current and recent HTTP sessions. If you monitor this table regularly, consider adjusting the server.log_gc.period and server.log_gc.max_deletions_per_cycle to fine tune garbage collection for this table.
  • Revoke HTTP authentication tokens as needed with the logout subcommand. See the example.
  • Set the --expire-after flag with a shorter duration. See the example.

• The logout subcommand logs out all sessions for the given user; you cannot target individual sessions for logout. If more granular control of sessions is desired, consider setting the --expire-after flag with a shorter duration. See the example.

Examples

Log in to the HTTP interface

Log in to the HTTP interface, by generating a new HTTP authentication token for the web_user user:

$ cockroach auth-session login web_user

  username |     session ID     |                       authentication cookie
-----------+--------------------+---------------------------------------------------------------------
  web_user | 784445853689282561 | session=CIGAtrWQq7rxChIQTXxYNNQxAYjyLAjHWxgUMQ==; Path=/; HttpOnly; Secure
(1 row)

Log in to the HTTP interface with a custom expiry

Log in to the HTTP interface, by generating a new HTTP authentication token for the web_user user and specifying a token expiry of 4 hours and 30 minutes:

$ cockroach auth-session login web_user --expire-after=4h30m

  username |     session ID     |                       authentication cookie
-----------+--------------------+---------------------------------------------------------------------
  web_user | 784445853689282561 | session=CIGAtrWQq7rxChIQTXxYNNQxAYjyLAjHWxgUMQ==; Path=/; HttpOnly; Secure
(1 row)

Log in to the HTTP interface with limited command output

Log in to the HTTP interface, by generating a new HTTP authentication token for the web_user user, limiting command output to only the generated cookie:

$ cockroach auth-session login web_user --only-cookie

session=CIGA6t2q0LrxChIQV8QCF3vuYSasR7h4LPSfmg==; Path=/; HttpOnly; Secure

This is useful if you intend to use the cookie with other command line tools. For example, you might output the generated cookie to a local file, and then pass that file to curl using its --cookie flag:

$ cockroach auth-session login web_user --certs-dir=certs --only-cookie > $HOME/.cockroachdb_api_key
$ curl --cookie $HOME/.cockroachdb_api_key https://localhost:8080/_status/logfiles/local

Of course you can also provide the cookie directly:

curl --cookie 'session=CIGA8I7/irvxChIQDtZQsMtn3AqpgDko6bldSw==; Path=/; HttpOnly; Secure' https://localhost:8080/_status/logfiles/local

Terminate all active sessions for a user

Terminate all active sessions for the web_user user:

$ cockroach auth-session logout web_user

  username |     session ID     |          revoked
-----------+--------------------+-----------------------------
  web_user | 784445853689282561 | 2022-08-02 18:24:50.819614
  web_user | 784447132063662081 | 2022-08-02 18:24:50.819614
  web_user | 784449147579924481 | 2022-08-02 18:47:20.105254
  web_user | 784449219848241153 | 2022-08-02 18:47:20.105254
(4 rows)

Note that the output may include recently revoked sessions for this user as well.

List all sessions

List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions:

$ cockroach auth-session list

  username |     session ID     |          created           |          expires           |          revoked           |         last used
-----------+--------------------+----------------------------+----------------------------+----------------------------+-----------------------------
  root     | 784428093743988737 | 2022-08-02 16:47:36.342338 | 2022-08-02 17:47:36.341997 | NULL                       | 2022-08-02 16:47:36.342338
  root     | 784428586862215169 | 2022-08-02 16:50:06.830294 | 2022-08-02 17:50:06.829974 | NULL                       | 2022-08-02 16:50:06.830294
  web_user | 784447132063662081 | 2022-08-02 18:24:26.37664  | 2022-08-02 19:24:26.376299 | 2022-08-02 18:24:50.819614 | 2022-08-02 18:24:26.37664
  web_user | 784449147579924481 | 2022-08-02 18:34:41.463345 | 2022-08-02 19:34:41.463006 | 2022-08-02 18:47:20.105254 | 2022-08-02 18:34:41.463345

A value of NULL in the revoked column indicates that the session is still active.

See also