# idra CLI (https://docs.idra.zone/docs/cli)

SSH into servers with short-lived certificates issued by IdRa (Privileged Access).

`idra` is a small command-line client for **Privileged Access**. It signs you in with the OAuth device flow, generates a throwaway SSH key, asks IdRa for a certificate valid for at most 10 minutes, and runs `ssh` with it. There are no long-lived keys on your machine and no agent on the servers.

## Requirements

- [`bun`](https://bun.sh) and `ssh` / `ssh-keygen` (OpenSSH) on your machine.
- The CLI source: it ships in the IdRa repository as `src/cli/idra.ts` (also the `idra` bin of the package).
- An administrator has registered the server in **Privileged Access → Servers** and given you access through a group.

## Commands

| Command | What it does |
| --- | --- |
| `idra login` | Device-flow sign-in. Prints a URL and a code; open it, confirm the code and complete MFA in the browser. |
| `idra ssh [user@]host [command…]` | Gets a certificate for `host` and connects. Signs you in first when needed. |
| `idra logout` | Deletes the stored token. |

```sh
export IDRA_URL=https://idra.example.com   # your IdRa address; remembered after the first login
bun src/cli/idra.ts login
bun src/cli/idra.ts ssh deploy@db-1.prod.internal
bun src/cli/idra.ts ssh db-1.prod.internal uptime   # no user: the first allowed principal is used
```

## How it works

1. `idra login` uses the device authorization grant (RFC 8628) with the built-in `idra-cli` client. You approve it at `/device` on IdRa.
2. The access token is stored in `~/.config/idra/token.json` (or `$XDG_CONFIG_HOME/idra/token.json`), readable only by you.
3. `idra ssh` creates an ephemeral ed25519 key in a temporary directory and sends its public key and the host name to `POST /api/pam/ssh/cert`.
4. IdRa matches the host against the server rules, checks your group membership (including time-bound access granted through **Request Access**) and, unless the server opts out, that you completed MFA recently.
5. The certificate lists the allowed principals and lasts at most 10 minutes. The temporary key is deleted when `ssh` exits.

## Messages

| Message | Meaning |
| --- | --- |
| `This server needs a fresh MFA verification.` | The server requires recent MFA; the CLI signs you in again. |
| `Your IdRa session expired.` | The token expired; the CLI signs you in again. |
| `no IdRa server rule matches <host>` | No server in IdRa lists that host name. |
| `you don't have access to <host>` | You're not in the server's group. Request access from your IdRa dashboard (**Requests**). |

**Fresh MFA**

  The CLI never uses refresh tokens: a refreshed token can't prove recent MFA, so it simply signs in
  again. "Fresh" means the token is at most 10 minutes old and you did MFA at most 5 minutes before
  it was issued.

## Server setup

Servers trust IdRa's SSH certificate authority instead of individual keys; there is no agent to install. Each server's page in **Privileged Access → Servers** shows a copy-paste setup script. It amounts to:

```sh
# the CA public key(s) from Privileged Access → Certificate Authority
sudo tee /etc/ssh/idra_user_ca.pub
# one file per principal, naming who may log in as that account
sudo install -d -m 755 /etc/ssh/auth_principals
echo deploy | sudo tee /etc/ssh/auth_principals/deploy
# /etc/ssh/sshd_config.d/idra.conf
TrustedUserCAKeys /etc/ssh/idra_user_ca.pub
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
```

Then reload `sshd`. **Rotate** on the Certificate Authority page signs new certificates with a new CA immediately; the old key stays listed for 7 days, so roll the updated `TrustedUserCAKeys` file out to your servers first.