cockroach auth-session

On this page

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

$ 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

$ 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