Remote Sessions Setup
Remote sessions let users open RDP and SSH sessions to your servers in a browser tab, through GrantFlow. Users need no VPN and no local client, and you open no inbound firewall rule from the internet: the tunnel agents connect out to GrantFlow. Inside your network, each target must still accept RDP or SSH from the zone's tunnel agents. A user can only reach a machine that one of their roles grants, and only while that access is active. How users connect is described in Remote Sessions.
This page explains how sessions reach your network, and walks you through setting up a zone and its tunnel agents. Adding the machines users connect to is covered in Session Targets, and recordings in Session Recordings.
You manage everything under Admin → Sessions, which needs tenant admin rights. If you don't see Sessions in the admin menu, remote sessions are not enabled for your tenant yet. Contact info@grantflow.cloud.
How Sessions Reach Your Network
A zone stands for one network segment, such as a Tier 0 subnet or a DMZ. You bound each zone by its CIDR ranges, and you add the machines inside it as session targets. A tunnel agent runs on a host inside the segment and carries session traffic to the targets in its zone.
The tunnel agent only ever dials out. It keeps a connection to GrantFlow for its instructions, and for each session it connects outbound to a GrantFlow relay. The relay pairs that connection with the user's browser session, which GrantFlow's session gateway turns into RDP or SSH. The traffic between the session gateway and the agent is encrypted end to end, so the relay only forwards it.
What an agent may reach is fixed by the zone's allowlist. GrantFlow builds it from the zone's enabled targets, signs it, and delivers it to the zone's agents. An agent opens a connection only to a host and port on that list, and only after the host name resolves to an address inside the zone's CIDRs. That check stops a name from being pointed at an address outside the zone, such as the agent's own host. It sets a network boundary only: it does not prove which machine inside the zone's ranges answers. To narrow a host to specific addresses, use Allowlist Pins, and to verify the server itself, keep Server Identity checks on.
Access always comes from roles
A zone, an agent or a target on its own grants nothing. Users see a target only when a role they can activate grants it, and a session lasts no longer than the activation or checkout behind it. See Grant Targets Through a Role.
The Overview Tab
Admin → Sessions → Overview shows where setup stands. Four tiles count your Zones, the Agents online, the Zones awaiting push, and the enabled Targets. A tile that needs attention is highlighted, and clicking a tile opens its tab.
Below the tiles, the Setup checklist lists what sessions need, in the order to do it:
- Define a zone and its network bounds. Without CIDRs an agent refuses every session in the zone.
- Enroll a tunnel agent in each zone. Sessions reach the network only through an agent inside it.
- Add the machines users connect to. A target is what users open and what the zone allows.
- Deliver the allowlist to the agents. Agents enforce only what was delivered to them.
- Grant targets through a role. Users see only targets that a role they can activate grants.
- Choose who may watch recordings. Admins are not viewers automatically.
Each step shows Done or To do, with what is still open, and the next step to do carries the button that takes you there. Once every step is done, the list folds into Setup complete.
Tenant-Wide Settings
The Session & Recording Settings section of the Overview holds the defaults for every zone. Sessions per user in a zone limits how many sessions one user may hold at once in any one zone, so a single user cannot fill it. It accepts 1 to 100, and a zone may override it. The recording settings in the same section are described in Session Recordings. Click Save to apply your changes.
Create a Zone
On the Zones tab, click New Zone. The dialog has the following fields:
| Field | What it does |
|---|---|
| Name and Description | How the zone appears to admins and on the users' Sessions page filters. |
| Network bounds (CIDRs, at least one) | One CIDR per line, such as 10.20.0.0/16, up to 32. A target's host name must resolve inside these ranges. A zone without CIDRs cannot be saved. |
| Max concurrent sessions | The most sessions the whole zone carries at once, up to 10,000. 0 means no zone cap. The hint below the field compares it with what the zone's agents can carry. |
| Sessions per user | How many of this zone's sessions one user may hold at once, 1 to 100. Empty inherits the tenant default. |
| Recording retention (days) | How long recordings of this zone's sessions are kept, 30 to 365. Empty inherits the tenant default. |
| Session Feature Defaults | Clipboard, file transfer and audio for the zone's targets. See Session Feature Defaults. |
Click Create Zone to save. Each zone card then shows its CIDRs, allowlist state, agents, session limits, retention, and badges for the session features that are turned on. Click Edit on the card to change the zone, and Save Zone to apply.
Session Feature Defaults
Each of these features can move data out of a session, so all three are off until you turn them on:
| Feature | Values |
|---|---|
| Clipboard | Off, To remote only, From remote only, Both directions |
| File transfer | Off, Upload only, Download only, Upload and download |
| Audio | On or off. Plays the remote machine's sound in the browser. |
The zone's values apply to every target in it that does not override them. A target overrides all three together, as described in Session Features. A session keeps the features it opened with, so a change applies to the next session. For what file transfer allows on RDP and SSH, see Session File Transfer.
The Zone Allowlist
GrantFlow rebuilds a zone's allowlist and delivers it to the zone's agents automatically whenever you add, change or remove a target, or change the zone's CIDRs. An agent that is offline receives the current list when it next connects. The Allowlist line on the zone card shows where the list stands:
- Delivered vN: the agents have the current list, at version N.
- Awaiting push: the list changed and has not reached the agents yet. Until it does, they keep enforcing the previous list, including hosts that were removed since.
- Nothing to deliver: the zone has no enabled targets yet, so its agents refuse every session.
If a zone stays at Awaiting push, click the Push now icon on its card to deliver the list again. GrantFlow reports how many agents received it, for example Delivered to 2 of 2 agents. When a push fails, the card explains why, such as a zone without CIDRs or two targets on one host with different pins. Click the What this zone allows icon to see the exact list: the CIDRs, and each host with its ports, protocol and pins.
A zone's allowlist holds up to 256 hosts.
Delete a Zone
Click the Delete zone icon on the zone card and confirm. GrantFlow first tells the zone's agents to allow nothing, then deletes the zone. A zone that still holds targets cannot be deleted: GrantFlow names what is left, and you move or delete those targets first.
Enroll a Tunnel Agent
A tunnel agent is the same GrantFlow agent you use for Active Directory, enrolled as its own identity for one zone. It never performs directory operations. It runs as its own service, GrantFlowAgent-Tunnel, so a directory agent can run on the same host. Tunnel agents need agent version 0.3.5 or later.
On the Tunnel Agents tab, click Enroll Agent and fill in the dialog:
| Field | What it does |
|---|---|
| Display Name | A name that identifies the agent, such as Segment Tunnel Agent 01. |
| Zone | The network segment the agent reaches. It bounds what the agent may dial. |
| Allowlist | Read-only. Shows the zone's allowlist state, which the agent receives when it first connects. |
| Capabilities | Session Tunnel is always selected. |
| Max concurrent sessions | How many connections the agent carries at once, 1 to 1,000. Prefilled with 50. |
| Bandwidth for the whole agent | Unlimited, or a cap from 2 Mbit/s to 100 Mbit/s shared by every session on the agent. |
| Allowed Source IPs (Optional) | IP addresses or CIDR ranges, one per line, from which the agent may connect to GrantFlow. Empty means no restriction. |
Before you enroll, make sure the agent host may connect out on two paths: TCP 443 to enrollment.grantflow.cloud for the one-time enrollment, and TCP 8443–8453 to agents.grantflow.cloud for the control channel and the session relays. Nothing inbound from the internet is needed. See Network Requirements for the details.
Click Create Agent. The dialog then shows the enrollment steps for the agent host. Choose Windows or Linux under Agent host, and follow the five steps:
- Download the agent. Use Download Agent on the Tunnel Agents tab, and save it in a directory of its own, such as
C:\ProgramData\GrantFlow\tunnelor/opt/grantflow-tunnel. Run every following command there, from an elevated PowerShell or as root. - Enroll it. Run the enrollment command the dialog shows. It contains a one-time enrollment token.
- Trust the allowlist key. Run the command the dialog shows, which adds GrantFlow's allowlist signing key to the agent's configuration. Compare each fingerprint with the one GrantFlow publishes first. Without a trusted key, the agent refuses every session.
- Install and start the service. Run the two service commands the dialog shows.
- Open egress. Confirm that outbound TCP 8443–8453 from this host to the GrantFlow agents host is allowed, so the service can reach the control channel and every relay port. See Tunnel Agent Hosts for the port details.
Save the enrollment token now
The enrollment token is shown once. Copy it before you close the dialog.
For the general enrollment procedure and agent updates, see Active Directory Agents.
Agent Cards and Details
Each agent appears as a card on the Tunnel Agents tab, which you can filter by zone. Click a card to open its details: its zone, its limits, and the allowlist key it must trust. The details dialog also offers the same actions as for directory agents, such as revoking or deleting the agent and forcing a certificate renewal.
Tunnel Limits
Click Edit limits on an agent card to change its Max concurrent sessions and its Bandwidth for the whole agent. An agent with no cap set carries 8 connections at once. A bandwidth change applies to running sessions too. A lower session cap does not end sessions that are already running.
Size each zone so its agents can carry the sessions you expect. An SSH session with file transfer uses two connections on an agent, as described in Agent Capacity.
Relay Ports
Each tunnel agent checks that it can reach every relay port. When a port fails, its card shows a warning such as 2 relay ports unreachable, with Details. The Relay Ports dialog lists each relay address as Reachable or Failed, and names the host and ports to allow outbound from the agent's host.
Session Limits
A session opens only when it fits every limit that applies to it:
- Per user in a zone: Sessions per user on the zone, or the tenant's Sessions per user in a zone.
- Per zone: the zone's Max concurrent sessions, when set.
- Per agent: each agent's Max concurrent sessions in its tunnel limits.
- Per organization: a ceiling for all your zones together, which GrantFlow sets for your tenant.
When a limit is reached, the user's session does not open. They can try again once another session ends.
Monitor and End Live Sessions
Admin → Sessions → Live Sessions lists every session that still holds access, from the moment it is requested until it closes. For each session you see the target, the user, its state, when it started and when it ends. You can filter the list by zone. An SSH session with a file transfer connection carries an SFTP badge.
To end a session, click Terminate this session on its row, enter a reason, and confirm with Terminate. The session ends at once, on the agent and in the user's browser. The reason, up to 500 characters, is written to the audit log. The activation that authorized the session stays active, so to remove the user's access as well, end the activation.
Troubleshooting
Every Session in a Zone Is Refused
Check the zone's card on the Zones tab. An agent refuses every session when the zone has no CIDRs, when nothing has been delivered yet (Nothing to deliver), or when the agent does not trust the allowlist key. If you skipped step 3 of the enrollment, open the agent's details, copy the key, and add it to the agent's configuration.
A Change Has No Effect
If the zone shows Awaiting push, its agents still enforce the previous list. Click Push now, and read the reason on the card if the push fails.
No Agent Is Online
The Overview names zones that have targets and no agent online. Check that the GrantFlowAgent-Tunnel service is running on the agent host, and that outbound TCP 8443–8453 is open. Enroll another agent only if the existing ones are gone.
Audit Events
Zone and agent changes, and every session, are recorded in the audit log:
| Event | When |
|---|---|
| Zone Created, Zone Updated, Zone Deleted | A zone was created, changed or deleted. |
| Zone Allowlist Pushed | A zone's allowlist was delivered to its agents, automatically or with Push now, with the outcome. |
| Tunnel Agent Limits Set | An agent's tunnel limits were changed. |
| Session Settings Updated | The tenant-wide session or recording settings were saved. |
| Session Requested, Session Opened, Session Closed | A user asked for a session, it opened, and it ended. |
| Session Denied | A session was refused, with the reason. |
| Session Terminated by Admin | An admin ended a session, with the reason. |
For the full list of audit events, see Audit Events.