cockroach auth-session

On this page Carat arrow pointing down
Warning:
CockroachDB v21.2 is no longer supported. For more details, see the Release Support Policy.

To create and manage web sessions and authentication tokens to the HTTP interface from the command line, use the cockroach auth-session command 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 SQL command-line flags.

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 admin role. The user being authenticated via login or logout does not require any special roles.

Considerations

  • The login subcommand allows users with the admin role 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.
    • 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:

icon/buttons/copy
$ 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:

icon/buttons/copy
$ 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:

icon/buttons/copy
$ 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:

icon/buttons/copy
$ 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:

icon/buttons/copy
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:

icon/buttons/copy
$ 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:

icon/buttons/copy
$ 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


Yes No
On this page

Yes No