> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH access with IAM

> Use individual Linux logins and revocable SSH credentials for people and automation.

Add an SSH public key to your profile or a service account, then grant that
identity permission to access the instance. A key has no permissions of its
own, and you do not attach it to each instance.

People use the Linux username shown in their profile, such as `bsu_200123`.
Service accounts have their own username, such as `bsa_200124`. The UID and
primary GID stay the same when keys are rotated. A person's identity is shared
across instances in the same organization. Removing and later readding that
person to the organization allocates a new identity.

## Add your public key

Keep the private key on your computer. Upload the single OpenSSH public-key
line from its `.pub` file. Each identity supports up to 50 keys, with an optional
expiry. Expiration and revocation prevent new logins without rebuilding the VM.

<Tabs>
  <Tab title="Console">
    Open your account profile and find **SSH Keys**. Choose **Add SSH Key**,
    enter a **Name**, and paste the public key. Your **Linux Identity** shows
    the username, UID and GID for the selected organization.
  </Tab>

  <Tab title="API">
    ```http theme={null}
    POST https://iam.basaltic.sh/v1/auth/ssh-keys
    Content-Type: application/json

    {
      "name": "workstation",
      "public_key": "ssh-ed25519 <your-public-key>"
    }
    ```

    Use your human login session. Personal SSH credentials cannot be managed
    using a service-account or assumed-role credential.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic iam ssh-key create --name workstation --public-key "$(cat ~/.ssh/id_ed25519.pub)"
    basaltic iam auth get-linux-identity
    ```

    Use a profile authenticated as your user.
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    key, err := iam.New(cfg).CreatePersonalSSHKey(ctx, &iam.SSHKeyCreateRequest{
        Name: "workstation",
        PublicKey: publicKey,
    })
    ```

    Configure the client with your human session. `publicKey` contains the
    OpenSSH public-key line, never the private key.
  </Tab>
</Tabs>

For automation, manage SSH credentials on the service account's page. Its
`ssh-keys` and `linux-identity` API routes are under
`/v1/service-accounts/{service_account_id}`. Managing those credentials requires
`iam:ManageCredentials` on that service account. SSH does not issue API
credentials to the guest or give its workloads the login identity.

## Grant login and sudo separately

A person has one effective IAM role in each account, including roles assigned
through groups. Several groups may assign the same role. A conflicting second
role is rejected. SSH uses that current account role; there is no role selector
on an SSH key.

Grant these actions on the intended instance CRNs:

| Action | Access |
| - | - |
| `compute:SSHLogin` | Open an SSH session as the identity's Linux user |
| `compute:SSHAdminLogin` | Use sudo; also requires `compute:SSHLogin` |

For example, this policy allows ordinary login to one instance:

```json theme={null}
{
  "version": "2024-01-01",
  "statements": [{
    "effect": "allow",
    "actions": ["compute:SSHLogin"],
    "resources": ["crn:compute:sa-saopaulo-1:my-account:instance/web"]
  }]
}
```

Attach the policy to the human's account role or directly to the automation
service account. Role trust, current group membership, resource tag conditions,
permission boundaries and explicit denies continue to apply. The instance's
workload IAM role is separate from SSH login authority.

## Enable an existing guest

IAM SSH integration supports Debian 11, 12 and 13, and Ubuntu 20.04, 22.04 and
24.04. New instances created from these platform images enable IAM SSH during
their first boot. You do not need to select a legacy compute keypair.

For an existing VM, upgrade the guest agent from the configured Basaltic package
repository to version 1.9.0-1 or later. Retain a working administration session
while enabling the integration:

```sh theme={null}
sudo -n /usr/bin/basaltic-guest-agent ssh-install
sudo -n systemctl daemon-reload
sudo -n systemctl restart basaltic-guest-agent.service
sudo -n systemctl reload ssh.service
```

Then verify a fresh connection with the Linux username from your profile or
service account. The first successful login creates its home directory.
Enabling named access does not migrate an existing `basaltic` login or change
the ownership of its files.

<Note>
  Enforcing SELinux, authselect-managed configuration, other distributions, and
  custom SSH Match configurations need a separately validated integration.
  The installer refuses configurations it cannot safely manage. Do not disable
  guest security controls to force activation.
</Note>

## Revocation and existing sessions

Key lookup, login and sudo checks consult current IAM state. Removing a key,
disabling its identity, or removing its applicable permission blocks new SSH
logins. A control-plane or metadata outage also blocks new access because a
permission cannot be verified.

Already established SSH sessions and root shells continue. Revocation does not
terminate existing processes. Sudo rechecks current login/admin permissions and
whether the identity is enabled. Revoking a key alone does not remove those
permissions from an already authenticated session.

## Legacy compute keypairs

Compute keypairs are copied into the `basaltic` account at instance creation.
Deleting the compute keypair record does not remove that copy. These credentials
remain separate from IAM until the guest is migrated.

Keep the original login until you have verified its replacement. Migrate each
automation credential to a service account with access scoped to the original
instances. Preserve the old Linux UID and file ownership, and remove retired
authorized-key copies and their provisioning sources after cutover. Contact
support for migration of an existing shared `basaltic` account.

Customized command-restricted sudo needs a separate migration plan.
`compute:SSHAdminLogin` grants unrestricted sudo to the named IAM identity;
it is not a replacement for a command allowlist.