SSH access with IAM

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.

Console
API
CLI
Go

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.

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.

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.

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.

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. 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:

{
  "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:

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.

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.

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.

Get started

Products

Platform

Help

SSH access with IAM

Add your public key

Enable an existing guest

Revocation and existing sessions

Legacy compute keypairs

​Add your public key

​Grant login and sudo separately

​Enable an existing guest

​Revocation and existing sessions

​Legacy compute keypairs

Add your public key

Grant login and sudo separately

Enable an existing guest

Revocation and existing sessions

Legacy compute keypairs