SSH Access Setup Guide

Overview

TigerAccess replaces traditional SSH key-based authentication with short-lived certificates. This approach provides:

No Long-Lived Credentials: Certificates expire automatically (1-12 hours)
Complete Audit Trail: All SSH sessions logged with keystroke playback
No SSH Key Management: No need to distribute, rotate, or revoke SSH keys
Dynamic Access: Just-in-time access based on current role membership

Prerequisites

TigerAccess auth service running and accessible
TigerAccess proxy service configured (will be set up in this guide)
SSH access to target servers for agent installation
Open port 3023 (SSH proxy) and 3024 (reverse tunnel) on proxy server

SSH Architecture

Understanding the TigerAccess SSH architecture:

User (tac cli) → TigerAccess Proxy (port 3023)

↓ Certificate Authentication

TigerAccess Proxy → Target Server (via Agent or Direct)

↓ Reverse Tunnel (port 3024)

TigerAccess Agent → Target SSH Daemon

The proxy validates certificates against the Auth Service CA and routes connections to the appropriate backend server.

Configure SSH Proxy

Configure the TigerAccess proxy service to handle SSH connections.

Update Configuration

Edit /etc/tigeraccess/config.yaml:

proxy:
  enabled: true
  public_addr: "proxy.example.com:3023"

  # SSH Proxy Configuration
  ssh:
    enabled: true
    listen_addr: "0.0.0.0:3023"
    # Optional: Configure host key checking
    check_host_keys: true

  # Reverse Tunnel for Agents
  reverse_tunnel:
    enabled: true
    listen_addr: "0.0.0.0:3024"

  # Session Recording
  recording:
    enabled: true
    mode: "node-sync"  # or "proxy-sync", "proxy-async"
    storage:
      type: "s3"
      bucket: "tigeraccess-recordings"
      region: "us-east-1"

auth:
  # Auth service connection
  auth_servers:
    - "auth.example.com:3025"
  # Enable token-based auth for agents
  auth_token: "YOUR_PROXY_TOKEN"

Start Proxy Service

sudo tigeraccess start --config=/etc/tigeraccess/config.yaml --roles=proxy

Verify Proxy is Running

# Check proxy status
curl https://proxy.example.com:3023/webapi/ping

# Expected output: {"server_version":"v1.0.0","proxy_public_addr":"proxy.example.com:3023"}

Deploy SSH Agents

Deploy TigerAccess agents to your SSH servers. Agents create reverse tunnels to the proxy and handle local SSH connections.

Generate Join Token

On your TigerAccess auth/proxy server:

# Generate a join token for nodes
tac tokens add --type=node --ttl=1h

# Save the output token - you'll need it for each agent

Install Agent on Target Server

On each SSH server you want to manage:

# Download TigerAccess binary
curl -L https://get.tigeraccess.io/install.sh | bash

# Create agent configuration
sudo mkdir -p /etc/tigeraccess-agent
sudo tee /etc/tigeraccess-agent/config.yaml <<EOF
auth_servers:
  - "auth.example.com:3025"
proxy_server: "proxy.example.com:3024"
auth_token: "YOUR_JOIN_TOKEN"
labels:
  env: "production"
  region: "us-east-1"
  team: "backend"
ssh:
  enabled: true
  # Optional: Restrict allowed logins
  allowed_logins: ["ubuntu", "admin"]
log:
  output: "/var/log/tigeraccess-agent.log"
  severity: INFO
EOF

Start Agent

# Start agent
sudo tigeraccess start --config=/etc/tigeraccess-agent/config.yaml --roles=agent

# Or use systemd service
sudo systemctl enable tigeraccess-agent
sudo systemctl start tigeraccess-agent
sudo systemctl status tigeraccess-agent

Verify Agent Connection

# On auth/proxy server, list connected nodes
tac ls

# You should see your agent-connected servers

Configure Nodes

For servers without agents, you can add them as static nodes (agentless mode).

Add Static Node

# Add a server by hostname/IP
tac nodes add web-01 \
  --addr=10.0.1.100:22 \
  --labels=env=production,role=web,team=frontend

# Add with SSH key for initial connection
tac nodes add db-01 \
  --addr=10.0.2.50:22 \
  --labels=env=production,role=database \
  --ssh-key=/path/to/key.pem

Configure Node Labels

Labels are used for RBAC policies. Common label patterns:

# Environment classification
env: production | staging | dev

# Functional role
role: web | api | database | cache

# Team ownership
team: platform | backend | frontend

# Geographic location
region: us-east-1 | eu-west-1 | ap-south-1

# Compliance scope
compliance: pci | hipaa | sox

User Access Configuration

Configure which users can access which servers.

Create User with SSH Access

# Add user with allowed SSH logins
tac users add alice \
  --roles=developer \
  --logins=ubuntu,alice,deploy

# The user can now SSH as any of these logins

Create Role with Node Access

# Create role for production access
tac roles create prod-access --spec - <<EOF
kind: role
version: v7
metadata:
  name: prod-access
spec:
  allow:
    logins: ["ubuntu", "admin"]
    node_labels:
      env: ["production"]
      role: ["web", "api"]
    # Optional: Restrict to specific commands
    ssh_sessions:
      record: true
  deny:
    node_labels:
      role: ["database"]  # Deny database access
EOF

# Assign role to user
tac users update alice --add-role=prod-access

User Login and Connection

# User logs in to get certificate
tac login --proxy=proxy.example.com:3023 --user=alice

# List accessible nodes
tac ls

# Connect to a server
tac ssh ubuntu@web-01

# Or use label selector
tac ssh ubuntu@env=production,role=web

Advanced Features

Per-Session MFA

Require MFA for specific node access:

# Role requiring MFA for production
kind: role
version: v7
metadata:
  name: prod-mfa
spec:
  allow:
    logins: ["ubuntu"]
    node_labels:
      env: ["production"]
  options:
    require_session_mfa: true

SSH Port Forwarding

# Local port forward
tac ssh -L 8080:localhost:80 ubuntu@web-01

# Remote port forward
tac ssh -R 9000:localhost:3000 ubuntu@web-01

# Dynamic SOCKS proxy
tac ssh -D 1080 ubuntu@web-01

Session Joining

Allow users to join active SSH sessions for collaboration:

# List active sessions
tac sessions ls

# Join a session
tac join alice@web-01

Host Key Verification

# Configure trusted host keys
proxy:
  ssh:
    check_host_keys: true
    # Auto-trust on first connection
    host_key_callback: "auto-trust"
    # Or require explicit verification
    # host_key_callback: "strict"

Troubleshooting

Common Issues

Connection Timeout

Check network connectivity and firewall rules:

# Test proxy connectivity
nc -zv proxy.example.com 3023

# Check agent reverse tunnel
nc -zv proxy.example.com 3024

Certificate Validation Failed

Ensure clocks are synchronized:

# Check system time
timedatectl status

# Sync with NTP
sudo systemctl restart systemd-timesyncd

Permission Denied

Verify user has required roles and logins:

# Check user's effective access
tac status

# Verify allowed logins
tac users show alice

Agent Not Connecting

Check agent logs and configuration:

# View agent logs
sudo journalctl -u tigeraccess-agent -f

# Verify token is valid
tac tokens ls

Enable Debug Logging

# Client-side debug
tac ssh -d ubuntu@web-01

# Server-side debug (config.yaml)
log:
  severity: DEBUG