Certificates

Q: PEM or PKCS#12: which do I need?

Take the PEM bundle for the Localport agent, curl , nginx or anything else that reads PEM files. Take PKCS#12 for a Java keystore, for Windows, or for an appliance that imports one encrypted archive. Both carry the same certificate and the same key.

Summary

A client certificate is what a caller presents to reach a fleet. Your team can hold as many as it needs, from four different origins, and every one of them appears in a single list you can search, filter and revoke from. We never hold the private key for any of them.

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

Where certificates come from#

Every certificate carries an identity: a short, permanent name such as deploy-prod, or a teammate's username. Access is granted to that name, so a certificate can be replaced without touching anything you decided about access.

Certificates come from four places. The Certificates table labels each row with the one that issued it.

Origin	Issued to	Obtained by	Guide
Sign-in	A team member	Signing in from the terminal and approving a code in a browser	Member Access
Setup key	A server or appliance	Spending a single-use key once, then renewing automatically	Setup Keys
CI pipeline	A build or deploy job	Presenting the workload token the CI platform mints	CI/CD with OIDC
Dashboard	Anything that cannot run the agent	Creating it here and downloading a file	Below

The first three involve no files. Use the fourth when a browser, a Java keystore, curl, nginx or an appliance has to present the certificate itself.

We hold no private keys#

All four paths are certificate requests. The key pair is generated where the certificate will be used, the private half stays there, and only the request reaches us.

The dashboard download works the same way. Your browser generates the key, signs a request with it, and sends only the request. The private key is written into the file you save and exists nowhere else, so a lost file means issuing a replacement.

To generate the key outside the browser, turn on Bring your own key and paste a request built where the key will live:

openssl req -new -newkey ec:<(openssl ecparam -name prime256v1) -nodes \
  -subj "/CN=build-server" -keyout key.pem -out req.csr

Paste req.csr and leave key.pem where it is. Requests are accepted for ECDSA P-256, ECDSA P-384 and Ed25519 keys.

The Certificates tab#

Open Identities in the sidebar under Remote Access. The page is titled Credentials and holds three tabs: Certificates, Authorities and Setup keys.

Certificates are team-wide. One certificate is recognised by every fleet in the team, so this list shows everything a revocation would affect.

Column	Holds
Identity	The person's name, or the machine's name with its identity beside it
Kind	Member, Machine or External CA
Origin	Sign-in, Setup key, CI pipeline or Dashboard
Expires	The date, or the time left once a certificate is inside its last 30 days
Status	Active, Expired or Revoked

Search by identity, name or serial, and filter by status. Anything inside its last 30 days is coloured in the Expires column, so certificates about to lapse are visible at a glance.

Each row's menu opens What this reached, the access log filtered to that identity. It stays available after a certificate is revoked.

Machines can be renamed from here. Renaming changes the display label only, and the identity, the grants and the access log keep using the original.

Credentials, Certificates tab: who holds one, where it came from, and what expires next.

Create a certificate in the dashboard#

Select Issue certificate on the Certificates tab. This uses your team's managed authority, since a registered authority holds no key we can sign with.

Name is the display label, such as Build server. It is free text and does not have to be unique.
Identity fills itself in from the Name, as build-server. Grants are written against it and it survives every reissue. Lowercase letters, numbers and dashes, up to 48 characters, unique among your team's active certificates.
Valid for is 30 or 90 days.
Bring your own key switches from browser generation to pasting your own request.

Download the files on the next screen. The certificate stays listed afterwards, but the private key is not recoverable.

Issue a certificate: name it, watch the identity fill itself in, choose how long it lives.

Which file to download#

The same certificate is offered two ways.

PEM bundle is one file holding the certificate, its chain and the private key, in the order the --pem flag reads them. Use it for the Localport agent, curl, or anything that reads PEM.

nginx, HAProxy and most servers want the two halves separately, so the same tab offers Certificate + chain and Private key as separate files.

PKCS#12 is a single encrypted archive of the same material, for a Java keystore, Windows or an appliance. You set the password and the archive is encrypted with it in your browser, so we never receive it. A forgotten password means issuing a replacement.

Tighten the permissions before using the file. Browsers save downloads world-readable, and the agent refuses a key file any other account on the machine can read:

chmod 600 build-server*.pem

The refusal is explicit, reporting has too-open permissions 0644 (want 0600 or stricter).

How long a certificate lasts#

Lifetime follows the origin, and none of it is configurable per certificate.

Origin	Lifetime	What happens at the end
Sign-in	8 hours	Nothing renews it. Run `localport login` again
Setup key	30 days	The agent renews itself at two thirds of the lifetime
CI pipeline	15 minutes	The job ends first. The certificate is held in memory and never written to disk
Dashboard	30 or 90 days	Nothing renews it. Issue a replacement before it lapses

A machine set up with a setup key renews on its own, with no long-lived secret on disk. The agent proves it still holds the current certificate's private key and asks for a replacement.

Renewal is refused in four cases: the identity holds no grant anywhere in the team, the certificate was revoked, the setup key behind it was revoked, or that key has passed its Access ends date. Each takes effect within one renewal cycle, with no need to touch the machine.

Renewal does not check whether the old certificate has expired, so a machine that was switched off for a month renews on its own when it returns.

One identity may hold several live certificates at once, so the old one keeps working until its own expiry and the rollover overlaps.

Revoke a certificate#

Revoke certificate in the row menu takes it out of service immediately, across the whole team. Connections using it close on every fleet, it stops renewing, and the row stays in the list marked Revoked.

Revoking does not remove the grants written for that identity. A replacement issued under the same name inherits the access you already configured, so replacing a compromised key is a single action. To remove the access as well, delete the grant on each fleet. See Grants and Access.

Revoking a certificate and revoking a setup key do different things. Revoking the key stops new certificates being issued and stops existing ones renewing, while certificates already issued keep working until they expire. Revoking a certificate stops that certificate immediately.

Issuing and revoking certificates needs the admin or owner role.

Credentials on the machine#

A machine set up from the CLI keeps its credential under ~/.localport/identity/, one directory per identity, with directories at 0700 and keys at 0600. Set LOCALPORT_HOME to keep them somewhere else.

localport identity list     # what this machine holds, with expiry and renewal
localport identity renew    # force a renewal now
localport identity remove   # delete a credential from this machine

localport access presents the stored credential with no flags at all. When a machine holds several, name one:

localport access https://device1-example.eu.localport.dev -p 3001 --identity device1

Removing a credential locally does not revoke it. The certificate stays valid until you revoke it in the dashboard.

Frequently asked questions#

Where is my private key stored?

Wherever the certificate will be used, and nowhere else. Every issuance path generates the key pair locally and sends only a certificate request, so we hold no private key for any certificate on your account. The dashboard download is no exception: the browser generates that key and writes it into the file you save.

I closed the download screen. Can I get the certificate again?

No. The private key existed only in your browser and was never sent to us, so there is nothing to hand back. Issue a replacement under the same identity, take the files, and revoke the old certificate. Access is granted to the identity, so the replacement reaches everything the original did with no grant to edit.

PEM or PKCS#12: which do I need?

Take the PEM bundle for the Localport agent, curl, nginx or anything else that reads PEM files. Take PKCS#12 for a Java keystore, for Windows, or for an appliance that imports one encrypted archive. Both carry the same certificate and the same key.

How long do certificates last?

It depends on how they were obtained. A sign-in certificate lasts 8 hours and does not renew. A machine set up with a setup key gets 30 days and renews itself at two thirds of that. A CI pipeline gets 15 minutes, held in memory. A certificate you download from the dashboard lasts 30 or 90 days, and nothing renews it.

What happens when I revoke a certificate?

It stops working immediately, everywhere. Connections using it close on every fleet in the team at that moment, and it can no longer be renewed. The row stays in the Certificates list marked Revoked so the credential's history is still attributable, and its access log entries stay readable.

Can I use a key I generated myself?

Yes. Turn on Bring your own key when creating the certificate and paste a certificate request built where the key lives. The dashboard shows the openssl command that produces one. ECDSA P-256, ECDSA P-384 and Ed25519 keys are accepted, and RSA is not.

Does issuing a certificate give it access to anything?

No. A new certificate reaches nothing until a grant on some fleet names its identity. The issuing screens finish on the grant step for exactly that reason, and access can be added or changed later from any fleet's Access tab.

How does a machine renew without a stored secret?

It proves it still holds the current certificate's private key. The agent signs a request with that key and asks for a replacement, so no setup key, API key or password has to stay on the machine after the first setup. Renewal is refused if the identity has lost its grants, if the certificate was revoked, or if the setup key behind it has been revoked or has reached its end date.

Who can see and revoke certificates?

Issuing and revoking need the admin or owner role. Every certificate in the team appears in one list, so you can see what a revocation affects before making it.

Can I use certificates my own certificate authority issued?

Yes. Register the authority's public chain and Localport verifies callers against it, without ever receiving your signing key. You keep issuing device certificates with your own tooling, and their identities are namespaced under your trust domain. See Certificate Authorities.