Certificate Authorities

Q: What is a trust domain, and why is it required?

It is the namespace an authority speaks for, such as acme.corp . Everything that authority signs resolves inside it, so its identities are written acme.corp/build-agent and cannot collide with a name in your own team. Without it, any trusted authority could sign a certificate claiming to be one of your machines.

Q: What SPIFFE ID should my certificates carry?

spiffe:// /client/ , where the trust domain matches what you registered. A certificate naming a domain its issuing authority does not own is refused, so the two have to agree exactly.

Summary

Every client certificate chains to an authority your team trusts. You get one automatically the first time you create a fleet, and you can register your own alongside it. We verify against a registered authority and never receive its signing key.

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

The managed authority#

Your first fleet creates a certificate authority for the team, with nothing to configure. It signs everything Localport issues for you: sign-ins, setup key credentials, pipeline certificates and dashboard downloads.

The authority belongs to the team, not to a fleet. Every fleet verifies against the same one, so a person or machine needs a single credential no matter how many fleets it reaches. What separates one fleet from another is its grants.

Find it under Identities in the sidebar, on the Authorities tab.

When to bring your own#

A corporate PKI already issues certificates to the machines you want to reach.
A compliance requirement keeps the signing key on hardware you control.
A partner or contractor connects under their own organisation's identities.

You upload the public chain. The signing key stays with you, Localport verifies callers against the chain, and you keep issuing certificates with your existing tooling.

A registered authority verifies but cannot issue, since we hold no key for it. Issue certificate and setup keys both need the managed authority, so most teams keep both.

Register an authority#

On the Authorities tab, select Rotate CA, then Bring your own CA.

CA certificate chain (PEM) is the root plus any intermediates. Every certificate in the chain has to be a CA, and a leaf certificate is refused.
Trust domain is the namespace this authority speaks for, such as acme.corp. It is required.
CRL URL is where your revocation list is published, over HTTPS. It is required.
Identity comes from is SPIFFE URI or Common name.

Select Register CA. It joins the trust pool immediately and every fleet in the team starts verifying against it.

Why a trust domain is required#

A team can trust several authorities at once. The trust domain namespaces each one, so everything a registered authority signs resolves inside its own namespace and its identities are written acme.corp/build-agent. Those can never collide with a name in your own team, whose identities stay bare, such as deploy-prod.

Grants for a registered authority's identities therefore name the full form:

acme.corp/build-agent

Why a CRL URL is required#

We cannot revoke a certificate your authority issued. The published list is what lets you cut one machine without removing the whole authority.

Localport polls the URL every 15 minutes and folds your revocations into the same enforcement path as its own. A revoked certificate stops working on every fleet, and connections using it close.

The list has to be your authority's complete CRL. A delta CRL is refused, and so is one scoped to part of the authority's certificates. Active Directory Certificate Services publishes a delta by default, at a URL one character from the base one, so check which of the two you pasted.

A list older than the one already accepted is refused, on both its timestamp and its cRLNumber. A failed poll keeps the last known list, so an unreachable endpoint never un-revokes anything.

SPIFFE URI or common name#

SPIFFE URI is the recommended choice and expects each certificate to carry a URI SAN naming its identity:

spiffe://acme.corp/client/build-agent

The trust domain in that URI has to be the one you registered. A certificate presenting a domain its issuing authority does not own is refused outright, never downgraded to another form of identity.

Common name covers a PKI that cannot reissue its certificates to add SANs. The identity is read from the certificate's common name and namespaced the same way, so CN=build-agent from acme.corp resolves to acme.corp/build-agent.

Use the SPIFFE form for anything new. Any trusted authority can put any string in a common name, and the namespace is what keeps those separate. The dashboard notes this on the Authorities tab once a team trusts more than one.

Identities in a certificate#

Certificates Localport issues carry a SPIFFE URI naming the team, the kind and the identity:

spiffe://<team>.mtls.localport.dev/user/<username>     a person
spiffe://<team>.mtls.localport.dev/client/<identity>   a machine or pipeline

Two properties matter if you match on the path yourself.

The path holds a stable identity and nothing else: no serial, no certificate id, nothing that changes on reissue. Grants therefore outlive every renewal.

The path never encodes access. What an identity reaches is stored server-side and edited in the dashboard, so changing access never means reissuing a certificate.

The managed authority declares its own trust domain in its signed certificate, as a URI SAN with no path, following the SPIFFE X.509-SVID specification.

Rotate without an outage#

Rotate CA with Managed by Localport selected does three things at once: it mints a new authority, makes it the issuing one, and sunsets the previous issuer.

A sunset authority is still trusted, so every certificate already in the field keeps working. New certificates come from the new authority. Once nothing chains to the old one, remove it.

The Issuing badge marks which authority signs your next certificate, and exactly one carries it.

Statuses and removal#

Status	Meaning
Active	Trusted. Certificates chaining to it are accepted
Sunset	Still trusted, no longer used for new certificates
Revoked	No longer trusted

Authorities: everything the team trusts, which one signs, and which is on its way out.

Sunset takes an authority out of issuance and leaves it verifying. Reactivate puts it back. Revoke stops trusting it, and every connection that chained to it closes immediately, on every protocol and every fleet.

A team cannot empty its trust pool. Removing the last usable authority is refused, since a fleet with nothing to verify against would refuse every handshake.

Adding, sunsetting and removing an authority needs the admin or owner role. Members with the developer role can see the list.

Frequently asked questions#

Do I need to set up a certificate authority?

No. Your team gets one automatically the first time you create a fleet, and it signs every credential Localport issues for you. Registering your own is for organisations that need the signing key to stay on their side.

Who holds the signing key?

For the managed authority, we do, so issuing and revoking are one click away in the dashboard. For an authority you register, you do. You upload only the public chain, and we verify callers against it.

Can I still issue certificates from the dashboard with my own CA?

Not from your authority, since we hold no key to sign with. Issuing certificates and creating setup keys both need the managed authority. Teams commonly keep both: the managed one for people and pipelines, and their own for the machines their existing PKI already covers.

Why is a CRL URL required?

We cannot revoke what your authority issued. The published list is how your revocations reach us, polled every 15 minutes and enforced exactly like our own, and it is what lets you cut one machine without removing the whole authority.

My CRL is being refused. What is wrong?

It is most likely a delta CRL or a scoped one. Localport requires the authority's complete list, since it replaces the stored set on every poll and a partial list would un-revoke everything it omits. Active Directory Certificate Services publishes a delta by default, so check that you registered the base distribution point. A list older than one already accepted is also refused.

What is a trust domain, and why is it required?

It is the namespace an authority speaks for, such as acme.corp. Everything that authority signs resolves inside it, so its identities are written acme.corp/build-agent and cannot collide with a name in your own team. Without it, any trusted authority could sign a certificate claiming to be one of your machines.

SPIFFE URI or common name: which should I choose?

SPIFFE URI, for anything you can reissue. It carries the identity explicitly and is bound to the trust domain of the authority that signed it. Common name is the fallback for an existing PKI that cannot add SANs to certificates already in the field, and it is namespaced the same way.

What SPIFFE ID should my certificates carry?

spiffe://<your-trust-domain>/client/<name>, where the trust domain matches what you registered. A certificate naming a domain its issuing authority does not own is refused, so the two have to agree exactly.

Does reissuing a certificate change its identity?

No. The identity in the path is stable and carries no serial or certificate id, so renewing, replacing or rotating a certificate keeps the same identity. Every grant written against it keeps working with no edit.

What happens when I remove an authority?

Every connection that chained to it closes immediately, and nothing it signed is trusted again. Sunset it first if you are rotating, so certificates already in the field keep working while new ones come from the replacement.