Client policies

The Pia desktop app reads an enterprise policy at startup: a JSON document that presets some settings and pins others, greying out the matching control in Pia’s own settings. Traditionally that document is a policy.json file placed on each managed device.

A client policy is the same document, written once here — on the Client Policies page (/admin/client-policies) — and published to members through the ordinary sync. Groups do not hold a copy: a group points at a policy, so one document can govern the whole company and be corrected in one place.

Client policies are stored and delivered in plaintext

A group-scoped document cannot be wrapped with any one user’s key, so it is never end-to-end encrypted — not even for accounts that have E2EE enabled. Treat it as configuration, not as somewhere to put secrets. The editor carries the same warning permanently, and it cannot be dismissed.

The list

Three tiles sit above the grid: Total policies, Published (assigned to at least one group), and Not in use.

Not in use counts policies no group points at — written, valid, and reaching nobody. A policy you are still drafting belongs there. But if a colleague says a setting never got pinned, read this tile first: the Groups column below says which policies have an audience and which do not.

Writing a policy

1. New policy, then give it a name colleagues will recognise in the group dropdown (“Field tablets”, “Call centre”). The description is for you.

2. Write the document. Two optional sections, both shaped like Pia’s settings:

   {
     "defaults": { "uiLanguage": "DE" },
     "enforce": { "assistantFileToolsEnabled": false }
   }

   defaults presets a value the member can still change afterwards. enforce pins it and greys out the control in Pia’s settings.

3. The editor colours the document as you type — keys, text, numbers and true/false/null each get their own colour, and anything JSON has no place for is underlined in red. Format then re-indents what you typed and tells you where the JSON breaks, before you save.

4. Save, then publish it: open the group under Groups, pick the policy in Client Policy, and save.

Keys are the camelCase names of Pia’s own settings — the full list is in the desktop Enterprise Policy reference.

The server checks the document’s shape: one JSON object, no sections besides defaults and enforce (lower case), each of them an object, under 64 KB. It does not check setting names — the desktop client owns that schema, and a second copy here would drift out of date. A key Pia does not recognise is ignored and logged on the client.

A change applies at the member's next start

Pia reads policy once at launch. A policy you save now reaches a running client on its next sync and applies the next time that member starts Pia — not mid-session.

Keys the server cannot set

serverUrl, syncEnabled and trustSelfSignedCertificates are refused with an error naming the key. They are what a client needs in order to reach this server at all, and a server policy outranks the device’s own file — so one wrong value here would disconnect an entire group from the only place that could correct it. Set those three in the device’s policy.json, which is also how you constrain a device before it has ever reached a server.

The server also refuses to write Pia’s own bookkeeping: sign-in credentials, sync cursors, encryption state, migration markers, window geometry and draft text.

Sharing one policy between groups

Any number of groups can point at the same policy, and that is the usual case: one company-wide document, plus a stricter one for the groups that need it. The editor’s Published to card lists every group currently using the policy, so you can see the blast radius of an edit before you make it — and an edit reaches all of them at once.

Where two groups genuinely need different values, write two policies. A group publishes one policy or none; there is no merging of several.

Removing a policy

Two different actions, and the difference matters:

You want	Do this	Members get
This group to stop following any policy	Set Client Policy to (none) on the group	Nothing pinned; their own settings apply again
This policy to pin nothing, everywhere	Empty the document and save	Nothing pinned, in every group pointing at it
The policy gone from the catalog	Delete on the policy	—

Delete is refused while any group still publishes the policy, and the message names those groups. Point them elsewhere first. That guard exists because there is no per-policy tombstone on the wire: a policy deleted out from under a group would silently unpin every setting for its members, with nothing on screen to explain why.

What members receive

Each member’s own group decides which policy they get. A user with no group of their own follows the default group, which is the normal case for a fresh sign-up.

Members receive the document over the ordinary sync pull. It is cached on the device, so it keeps applying offline and across restarts, and Pia discards the cache on sign-out — the next person to sign in on that machine does not inherit the previous user’s policy.

Auditing

Catalog writes are recorded in the audit log as ClientPolicy.Created / ClientPolicy.Updated / ClientPolicy.Deleted. A group changing which policy it publishes is a separate entry, Group.ClientPolicyUpdated — deliberately not folded into Group.Updated, because that one write changes what reaches every member’s device.

Licensing

Viewing policies needs only an administrator account. Creating, editing, deleting and assigning them need the Group Management licence feature; without it the pages open read-only.