> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# cockroach auth-session
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session login {username} [flags]
```
Log out from the HTTP interface, revoking all active HTTP authentication tokens for a given user:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session logout {username} [flags]
```
List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session list [flags]
```
View help:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session --help
```
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ 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](#log-in-to-the-http-interface-with-a-custom-expiry). **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](#log-in-to-the-http-interface-with-limited-command-output). |
## 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. If you monitor this table regularly, consider adjusting the `server.log_gc.period` and `server.log_gc.max_deletions_per_cycle` cluster settings to fine tune garbage collection for this table.
* Revoke HTTP authentication tokens as needed with the `logout` subcommand. See the [example](#terminate-all-active-sessions-for-a-user).
* Set the `--expire-after` flag with a shorter duration. See the [example](#log-in-to-the-http-interface-with-a-custom-expiry).
* 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](#log-in-to-the-http-interface-with-a-custom-expiry).
## 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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session login web_user
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session login web_user --expire-after=4h30m
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session login web_user --only-cookie
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ 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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session logout web_user
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach auth-session list
```
```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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
* `cockroach` Commands Overview
* DB Console Overview