# PAM Launch JIT

## PAM Launch — Just-in-Time (JIT) Access

Just-in-time (JIT) access for `pam launch` provisions credentials or elevated privilege only for the duration of a session and reverses those changes when the session ends. That reduces standing privilege and limits how long credentials remain valid on the target system when paired with Keeper’s PAM Gateway.

***

### Overview

JIT access in Commander is an opt-in enhancement to `pam launch`. When you pass `-j` / `--jit`, Commander reads `pamSettings.options.jit_settings` from the **pamMachine** record and tells the Gateway to apply one or both of these behaviors for the session:

* **Ephemeral account** — The Gateway creates a short-lived account on the target for the session and removes it on disconnect (`create_ephemeral: true` in JIT settings).
* **Privilege elevation** — The Gateway adds the linked credential to an elevated group or role for the session and reverts on disconnect (`elevate: true`).

You can use **both** together: an ephemeral account is provisioned and immediately elevated for the session.

This model supports zero standing privilege patterns: credentials or elevated membership exist only while the interactive session is active.

**What Commander does when JIT is enabled**

Commander reads `jit_settings` from the pamMachine record. With `-j` / `--jit`, it emits `credentialType='ephemeral'` to the Gateway when ephemeral provisioning is in play, along with optional `jitSettings` and `jitElevation` payloads as required by the mode. The Gateway is responsible for creating accounts, applying elevation, and cleaning up on disconnect.

***

### Prerequisites

JIT behavior is driven entirely by configuration on the **pamMachine** record under:

`pamSettings.options.jit_settings`

Before using `--jit`, ensure that object defines the flags and fields that match the mode you want (ephemeral, elevation, or both). Commander does not invent JIT settings; it forwards what is on the record when `-j` is supplied.

**Checklist (same fields as the Record configuration section below)**

* Set `create_ephemeral` / `ephemeral_account_type` (and domain-only fields) if you need an ephemeral account.
* Set `elevate`, `elevation_method`, and `elevation_string` if you need temporary privilege elevation.
* For **domain** ephemeral accounts, set `pam_directory_uid_ref` and, where applicable, `base_distinguished_name`.

Domain-mode ephemeral provisioning additionally requires `pam_directory_uid_ref` on the record when `ephemeral_account_type` is `domain` (see Limitations and requirements).

**Compliance with vault rules**

`ephemeral_account_type == 'domain'` must satisfy the same `pam_directory_uid_ref` requirement enforced by the declarative validator on the record.

***

### JIT modes

| Mode                    | When it applies                                   | Effect                                                                                                     |
| ----------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Ephemeral account**   | `create_ephemeral: true` in `jit_settings`        | Gateway creates a short-lived account for the session and deletes it on disconnect.                        |
| **Privilege elevation** | `elevate: true` in `jit_settings`                 | Gateway adds the linked credential to an elevated group or role for the session and reverts on disconnect. |
| **Both combined**       | Both `create_ephemeral: true` and `elevate: true` | Ephemeral account is provisioned **and** immediately elevated for the session.                             |

**Interaction between modes**

* **Ephemeral only** — Short-lived account lifecycle is tied to the session; no elevation payload is required unless `elevate` is also `true`.
* **Elevation only** — The linked credential is elevated for the session; `credentialType` follows the elevation wire row (`linked` with `userRecordUid`).
* **Both** — Provisioning uses the ephemeral path (`credentialType` is `ephemeral`), while elevation metadata is supplied alongside via `jitElevation`.

***

### Record configuration (`jit_settings`)

All JIT options live on the pamMachine record at `pamSettings.options.jit_settings`:

| Field                     | Type / values                     | Description                                                                                                                      |
| ------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `create_ephemeral`        | boolean                           | When `true`, Gateway creates an ephemeral account for the session and removes it when the session ends.                          |
| `ephemeral_account_type`  | `"local"` \| `"domain"`           | Whether the ephemeral account is local or domain-backed.                                                                         |
| `base_distinguished_name` | string (DN)                       | Base distinguished name; used in **domain** mode only.                                                                           |
| `pam_directory_uid_ref`   | UID string                        | Reference to the directory configuration; **required** when `ephemeral_account_type` is `domain`, per the declarative validator. |
| `elevate`                 | boolean                           | When `true`, Gateway elevates the linked credential for the session and reverts on disconnect.                                   |
| `elevation_method`        | `"sudo"` \| `"group"` \| `"role"` | How elevation is applied (for example sudo, group membership, or role).                                                          |
| `elevation_string`        | string                            | Target value for the chosen method (for example sudo group name or role name).                                                   |

***

### Using `--jit` (`-j`)

**Flag**

| Short | Long    | Description                                                                                                                                                       |
| ----- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-j`  | `--jit` | Opt in to JIT provisioning for this launch. Commander emits the appropriate `credentialType` and optional `jitSettings` / `jitElevation` payloads to the Gateway. |

**Syntax (conceptual)**

```
pam launch -r <record-uid> -j [--additional launch options]
```

Records that define `jit_settings` do **not** automatically use JIT; you must pass `-j` / `--jit` explicitly.

**Examples**

Basic JIT launch:

```bash
My Vault> pam launch -r <record-uid> -j
```

JIT with a specific gateway:

```bash
My Vault> pam launch -r <record-uid> -j -g <gateway-uid>
```

Mutually exclusive options (these combinations are rejected; see next section):

```bash
My Vault> pam launch -r <record-uid> -j -cr admin
```

`allowSupplyHost` on the record is also incompatible with `-j` (clear error).

JIT with `allowSupplyHost` (rejected — illustrative):

```bash
My Vault> pam launch -r <record-uid> -j
# Rejected when allowSupplyHost is set on the record (clear error from Commander).
```

***

### Precedence and mutual exclusivity

**Credential precedence** (aligned with the web vault):

1. `allowSupplyHost`
2. JIT
3. `allowSupplyUser`
4. linked

**Validation rules**

* `-j` / `--jit` is **rejected** when the record has `allowSupplyHost` (Commander returns a clear error).
* `-j` is **mutually exclusive** with `-cr`, `-H`, and `-hr`, because JIT provisions the credential (or ephemeral account) itself.
* `ephemeral_account_type == 'domain'` requires `pam_directory_uid_ref` on the record, consistent with the declarative validator.

**Mutually exclusive flags**

| Flag / option | Relation to `-j`                                                     |
| ------------- | -------------------------------------------------------------------- |
| `-cr`         | Mutually exclusive with `-j` (JIT provisions the credential itself). |
| `-H`          | Mutually exclusive with `-j` (JIT provisions the credential itself). |
| `-hr`         | Mutually exclusive with `-j` (JIT provisions the credential itself). |

***

### How it works

#### End-to-end flow

1. Commander reads `pamSettings.options.jit_settings` from the pamMachine record.
2. When `-j` / `--jit` is passed, Commander validates precedence and flag combinations, then builds the Gateway input dictionary:
   * For **ephemeral** (including “both”), it sets `credentialType` to `ephemeral` and sends `jitSettings` with `create_ephemeral`, `ephemeral_account_type`, and optionally `base_distinguished_name` and `pam_directory_uid_ref`.
   * For **elevation** used with a linked credential path, the contract uses `credentialType` of `linked` plus `userRecordUid`, and sends `jitElevation` with `elevate`, `elevation_method`, and `elevation_string`.
   * When **both** ephemeral and elevation apply, `credentialType` is `ephemeral` and **both** `jitSettings` and `jitElevation` are sent.
3. For ephemeral mode, guacd connection settings intentionally leave username and password empty so the Gateway’s server-side credential injection wins.
4. The Gateway provisions (and optionally elevates) for the session; on disconnect it tears down the ephemeral account and/or reverses elevation.

#### Commander and Gateway responsibilities

* **Commander** publishes `credentialType`, optional `jitSettings`, and optional `jitElevation` according to the record’s `jit_settings` and the selected launch flags. It performs the validation described in Precedence and mutual exclusivity before opening the session path that reaches guacd / WebRTC.
* **Gateway** performs account creation and deletion for ephemeral mode, applies and removes elevation for elevation mode, and executes the combined behavior when both flags are enabled on the record.

#### Ephemeral credential injection (guacd)

In ephemeral mode the guacd connection settings leave **username** and **password** empty on purpose. The Gateway injects the correct short-lived credentials server-side so the interactive session still authenticates without Commander embedding those secrets in the client-side guacd parameters.

#### Wire contract (Gateway inputs)

| Mode      | `credentialType`           | Extra payload                                                                                                                      |
| --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Ephemeral | `ephemeral`                | `jitSettings` — `create_ephemeral`, `ephemeral_account_type`, optional `base_distinguished_name`, optional `pam_directory_uid_ref` |
| Elevation | `linked` + `userRecordUid` | `jitElevation` — `elevate`, `elevation_method`, `elevation_string`                                                                 |
| Both      | `ephemeral`                | `jitSettings` **and** `jitElevation`                                                                                               |

**List form (same contract)**

* **Ephemeral** — `credentialType` = `ephemeral`; includes `jitSettings` with `create_ephemeral`, `ephemeral_account_type`, and optionally `base_distinguished_name` and `pam_directory_uid_ref`.
* **Elevation** — `credentialType` = `linked` with `userRecordUid`; includes `jitElevation` with `elevate`, `elevation_method`, and `elevation_string`.
* **Both** — `credentialType` = `ephemeral`; includes both `jitSettings` and `jitElevation` with the fields above.

Commander’s `launch` flow (see PR #1979) reads `jit_settings`, applies `-j` / `--jit` handling in `jit.py` helpers, and funnels `credentialType` plus JIT payloads through `terminal_connection.py` into guacd or WebRTC clients.

***

### Limitations and requirements

| Topic                     | Requirement                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Domain ephemeral accounts | `ephemeral_account_type` set to `domain` requires `pam_directory_uid_ref` on the record (declarative validator). |
| `allowSupplyHost`         | JIT cannot be used on these records; Commander rejects `-j` with a clear error.                                  |
| Conflicting flags         | `-j` cannot be combined with `-cr`, `-H`, or `-hr`; those combinations are rejected.                             |
| Opt-in behavior           | `jit_settings` on the record does not auto-trigger JIT; every launch needs `-j` / `--jit` explicitly.            |

***

### Backward compatibility

JIT is strictly opt-in: existing `pam launch` behavior is unchanged unless you pass `-j` / `--jit`. Records may contain `jit_settings` without affecting launches until you explicitly enable JIT on the command line.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/commander-cli/command-reference/keeperpam-commands/pam-launch-jit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.