Limit session duration for Tailscale PAM services

Tailscale PAM lets you set a maximum duration for a session. When the limit is reached, the session ends, and the user must start a new session to continue working.

Session duration limits are useful when you want to bound how long privileged access lasts. For example, you can allow a support engineer to open an SSH session for troubleshooting, but make sure that session can't stay open indefinitely.

You set the limit using the max_session_duration_seconds field in a Tailscale PAM grant in your tailnet policy file.

You need to be an Owner, Admin, or Network admin of a tailnet to edit the tailnet policy file. For information about editing a tailnet policy file, refer to Edit ACLs.

How session duration works

The max_session_duration_seconds field is an integer that sets the maximum allowed duration, in seconds, for a session granted by the permission that contains it.

The field is optional. If you omit it, Tailscale PAM doesn't apply a duration limit from that permission. If you do specify it, the value must be greater than 0.

Where you set the field depends on the service type:

• For SSH services, set it inside the ssh permission, as a sibling of allowed_usernames.
• For database services, set it inside the database permission, as a sibling of allowed_databases.

Because grants are additive, review every grant that can match a source and destination. If another matching grant provides the same access without a duration limit, that access isn't limited.

Limit SSH session duration

To limit how long an SSH session can last, add max_session_duration_seconds to the ssh permission.

The following grant lets the group:support group open shell, exec, and SFTP sessions to svc:production-ssh as the support user, and ends any session after one hour:

{
  "grants": [
    {
      "src": ["group:support"],
      "dst": ["svc:production-ssh"],
      "ip": ["*"],
      "app": {
        "tailscale.com/cap/pam": [
          {
            "version": "v1",
            "permissions": {
              "ssh": {
                "shell": {},
                "exec": {},
                "sftp": {},
                "allowed_usernames": ["support"],
                "max_session_duration_seconds": 3600,
              }
            }
          }
        ]
      }
    }
  ]
}

For more information about the other SSH permissions in this example, refer to Control SSH access.

Limit database session duration

To limit how long a database session can last, add max_session_duration_seconds to the database permission.

The following grant gives the group:platform group read-only access to every database on svc:production-database, plus DELETE access to the books database, and ends any session after 30 minutes:

{
  "grants": [
    {
      "src": ["group:platform"],
      "dst": ["svc:production-database"],
      "ip": ["*"],
      "app": {
        "tailscale.com/cap/pam": [
          {
            "version": "v1",
            "permissions": {
              "database": {
                "allowed_databases": [
                  {
                    "database": "*",
                    "allowed_query_types": ["ReadOnly"]
                  },
                  {
                    "database": "books",
                    "allowed_query_types": ["ReadOnly", "DELETE"]
                  }
                ],
                "max_session_duration_seconds": 1800,
              }
            }
          }
        ]
      }
    }
  ]
}

The limit applies to the session as a whole, not to individual queries.

For more information about the other database permissions in this example, refer to Control database access.

Limit SSH and database sessions in one grant

A single grant can contain permissions for multiple Tailscale PAM service types, and each permission can carry its own session duration limit. Tailscale PAM applies the limit that matches the destination service.

The following grant gives the group:platform group SSH access to svc:production-ssh with a one-hour limit, and read-only database access to svc:production-database with a 15-minute limit:

{
  "grants": [
    {
      "src": ["group:platform"],
      "dst": ["svc:production-ssh", "svc:production-database"],
      "ip": ["*"],
      "app": {
        "tailscale.com/cap/pam": [
          {
            "version": "v1",
            "permissions": {
              "ssh": {
                "shell": {},
                "exec": {},
                "sftp": {},
                "max_session_duration_seconds": 3600
              },
              "database": {
                "allowed_databases": [
                  {
                    "database": "*",
                    "allowed_query_types": ["ReadOnly"]
                  }
                ],
                "max_session_duration_seconds": 900
              }
            }
          }
        ]
      }
    }
  ]
}

Choose a duration

When choosing a value, balance security against interrupting work in progress:

• Shorter limits reduce how long privileged access stays open, which is useful for recovery scenarios or vendor access.
• Longer limits suit sessions where an interruption is disruptive, such as a long-running database migration or a file transfer over SFTP.

Tailscale PAM ends the session when the limit is reached, so a user can lose unsaved work in an interactive shell or an in-progress transfer. Set a limit that gives users enough time to finish a typical task, and let them start a new session when they need more time.

Verify the limit

After you save the policy, confirm that the limit applies:

1. Connect to the service as a user matching the grant's src.
2. Leave the session open past the configured duration.
3. Confirm that Tailscale PAM ends the session.

You can review the session, including when it started and ended, on the Sessions page of the admin console. For more information, refer to Tailscale PAM session logs.

If a session outlasts the limit you set, check whether another grant matches the same source and destination and provides the same access without a max_session_duration_seconds field. For more troubleshooting steps, refer to Troubleshoot PAM access.