Skip to content

Issuing Access Passes

<!-- AUTOMATION_METADATA_START screenshot_source_url: https:///dashboard/access AUTOMATION_METADATA_END -->

This guide explains how SSH Teams creates short-lived access passes, called SSH certificates, when you connect from the CLI.

<!-- Automation screenshot source URL: https:///dashboard/access -->

Before You Connect

Make sure you have:

  • Completed device registration with sshteam init.
  • At least one joined server to connect to.
  • A matching access policy.
  • The server configured to trust SSH Teams certificates.

What Happens When You Connect

When you run an SSH command through SSH Teams, the CLI asks the server for a short-lived certificate. The server checks your policy. If you are allowed, it signs the certificate and returns it. The CLI then uses it to connect.

This happens automatically behind the scenes.

Choose How to Use Your Key

SSH Teams gives you three ways to issue a certificate:

  • sshteam sign — use an existing SSH key you already have.
  • sshteam issue — create a temporary key pair for one connection.
  • sshteam agent — load the certificate into your SSH agent.

Sign with an Existing Key

Use this if you already manage SSH keys on your device.

sshteam sign ubuntu@app01.example.net -k ~/.ssh/id_ed25519.pub

To write the certificate to a file:

sshteam sign ubuntu@app01.example.net -k ~/.ssh/id_rsa.pub --type RSA -o ~/.ssh/id_rsa-cert.pub

Issue a Temporary Key Pair

Use this if you want SSH Teams to create a fresh key for each connection.

sshteam issue ubuntu@app01.example.net

For RSA instead of the default:

sshteam issue ubuntu@app01.example.net --type RSA --bits 4096

The command prints the path to the temporary private key. The SSH Teams wrapper uses this flow automatically.

Load Into Your SSH Agent

Use this if you want the certificate added to your SSH agent.

sshteam agent ubuntu@app01.example.net
ssh ubuntu@app01.example.net

You need an SSH agent running on your device.

Choose a Certificate Type

SSH Teams supports two certificate types:

  • ED25519: Smaller and faster. Best for most modern systems.
  • RSA: Use this only if you need compatibility with older systems.

The default is ED25519.

Common Connection Failures

If your connection is denied, check the following:

  • Policy mismatch: Does the policy allow this user, server, and time window?
  • Device problem: Try re-registering with sshteam init https://<hostname>.
  • Invalid proof error: Re-register the device to refresh its credentials.
  • Cannot reach the server: Check the hostname and port.
  • Certificate warning: Use a trusted certificate in production. The -I / --ignore-ssl-trust flag is for testing only.
  • Multiple SSH Teams servers: Use --server to pick the right one.

You can check your registered devices with:

sshteam devices list

Quick Validation Checklist

After setting up or changing a policy, test these scenarios:

  1. A connection that should be allowed succeeds.
  2. A connection that should be denied is blocked.
  3. The default ED25519 certificate works.
  4. The RSA certificate works if your environment needs it.
  5. The default server works without adding --server.
  6. You can still specify --server when needed.
  7. The SSH login completes end to end.
  8. The activity logs show the expected allow and deny events.

If something fails, see the Troubleshooting Handbook.

Tips

Test the Deny Path

Always test both an allowed and a denied connection after changing a policy. This confirms your access boundaries work as expected.

Test Every Command You Plan to Use

If your team uses sign, issue, and agent, test all three. They behave similarly, but each has its own setup requirements.