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 theadmin
role to create HTTP authentication tokens with an arbitrary duration. If operational policy requires stricter control of authentication sessions, you can: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.