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
loginsubcommand allows users with theadminrole to create HTTP authentication tokens with an arbitrary duration. If operational policy requires stricter control of authentication sessions, you can:- Monitor the
system.web_sessionstable for all current and recent HTTP sessions. If you monitor this table regularly, consider adjusting theserver.log_gc.periodandserver.log_gc.max_deletions_per_cyclecluster settings to fine tune garbage collection for this table. - Revoke HTTP authentication tokens as needed with the
logoutsubcommand. See the example. - Set the
--expire-afterflag with a shorter duration. See the example.
- Monitor the
The
logoutsubcommand 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-afterflag 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.
