Grants and Access

Needs a fleet, which is on the Pro and Enterprise plans. See Fleets to create one.

What a grant is#

A grant is one line of policy on one fleet: this subject may reach these devices. Nothing else is implied, and nothing is allowed that a grant does not name.

A subject is a role, a person or a machine. The devices are named directly, either as one exact name, as a prefix, or as everything on the fleet.

Grants are written against the identity, never against a certificate. A machine that renews its certificate, is rebuilt, or moves to new hardware under the same name keeps the access you gave it, and changing what an identity reaches never means reissuing a certificate.

A grant can also name a machine that does not exist yet. It starts working the moment that machine first connects.

Grants live on one fleet at a time. An identity granted access on one fleet reaches another only once you write a grant there too.

Give access#

Open the fleet, select the Access tab, then Give access. The panel asks three questions in order, and each answer collapses to a single line once you have given it.

Type is Role, Member or Machine.

Who is the specific subject, from a list matching that type. Role offers Everyone in this team, Owners, Admins and Developers, each with the number of people it covers today. Member searches your team directory. Machine searches the identities your team has issued credentials for, marked Active, Pending or Inactive.

Access is the set of devices. A single switch reads All devices, and turning it off gives you a searchable list of the fleet's roster. A running count underneath states the result as you build it, in the form Reaching 14 of 180 devices.

Select Give access to and the grant is live. Nothing has to be restarted or reissued.

The panel flags two cases as you build the grant. A grant naming no devices is refused at save. A role grant nobody currently holds is accepted, and starts working when somebody takes that role.

Choosing a subject#

Everyone in this team sits at the top of the Role list and is the widest grant available. It covers every current member and everyone who joins afterwards.

A role grant is evaluated against whoever holds the role at the time of the connection. Adding a member, removing one or changing a role updates every fleet in the team automatically, so off-boarding is a single action in Members.

Grants add up. A person covered by a Developers grant reaching device* and a personal grant reaching db-01 reaches both sets. There are no deny rules, so an individual grant can only widen what a role grant already gave. To give one person less than their role has, narrow the role grant.

Choosing devices#

A grant names devices in one of three forms:

A trailing star is the only wildcard, and there are no tags to maintain.

Plan your device names around prefixes. Naming machines device1, device2 and device3 means one grant on device* covers every device added later, with no edit to the grant. Typing in the device list offers the matching prefix as the first row, with a live count of how many devices it reaches.

A device covered by a prefix shows as selected, with the prefix named beside it, and cannot be unticked on its own. To stop reaching one machine inside a prefix, narrow the prefix or name the devices individually.

One grant may name up to 200 devices and prefixes. Use a prefix to cover more.

The grants table#

The Access tab lists every grant on the fleet.

Filter by kind to answer a specific question, such as which machines can reach this fleet, or which grants are role-based. Each row also opens Recent access, a live crop of what that subject has actually connected to, and Access log for the full trail. See Access Log.

To see it from the other direction, open a device's menu on the Devices tab and choose Who can reach. That lists everything reaching that one machine and says why each entry does, whether the device was named outright or swept up by a prefix.

Change or take back access#

Edit on a grant row reopens the device list. The panel states the result as a sentence before you save, and flags a change that removes access. When it does, the button reads Save and disconnect, and every connection the grant covered closes as soon as you save.

Narrowing counts as removing. Tightening a grant from device* to device1 drops every other device it covered and cuts those connections, even though nothing was deleted from the list.

Remove access in the row menu deletes the grant entirely. That subject stops reaching the fleet, and its open connections close.

Widening disturbs nothing. Adding a device to a grant leaves every open connection running.

Removing a grant does not touch the certificate. The credential stays valid and keeps working wherever else it is granted. Use it to trim one fleet without off-boarding the machine. To stop a credential everywhere at once, revoke the certificate instead. See Certificates.

Writing, editing and removing grants needs the admin or owner role. Members with the developer role can read the Access tab without changing it.

What a refused caller sees#

The connection is refused during the TLS handshake, so nothing reaches your device and nothing is proxied.

Under TLS 1.3 the client sends its certificate after the server has finished, so the connection appears to open and the refusal arrives on the first read. The agent reports it and names what the holder can check:

device1-example.eu.localport.dev refused the certificate presented for this connection.
  Check in the dashboard that this identity has been given access to the device you are reaching,
  and that its certificate is still valid and has not been revoked.
  `localport identity list` shows what this machine holds

The message does not say which of the three it was. The exact reason is in the access log, where only your team can read it.

Frequently asked questions#

What to read next#

• Certificates - how a caller gets an identity to grant
• Fleets - the devices a grant names
• Access Log - what each identity actually reached
• Setup Keys - give a machine an identity of its own
• Member Access - give a teammate one
• Certificate Authorities - bring your own PKI