Deploy Joring through your MDM
Download the install files for your MDM, push them, and watch devices and browsers register and sign in with nobody clicking anything.
Managed deployment puts Joring on every machine your MDM manages and signs each one in through your identity provider. Nobody installs anything, approves anything or signs in by hand. It is an Enterprise feature, and it works with the MDM you already run: Jamf Pro, Kandji / Iru, Intune, Mosyle, Addigy, Fleet, Workspace ONE, JumpCloud and Group Policy.
The browser extension and the desktop agent are two separate streams. Push either one alone, or both. Neither waits for the other. Both follow the same path: an install registers with your team the moment it lands, waits for its person, and is signed in once your identity provider has proven them.
Set up single sign-on first
Managed sign-in rides on your identity provider: a machine signs in silently wherever an identity-provider session exists. Verify your email domain and enable a connection under Settings → Single Sign-On (set up single sign-on), and connect SCIM (SCIM provisioning) so people exist in Joring before their machines do. Without SCIM the first sign-in still works; the person is created on the way in.
Know the enrollment token
Every install file carries one enrollment token, the same for the agent and the extension and the same for every machine. Your first download creates one named "Default"; you never have to make one first. If you later revoke every token, downloads wait until you create a new one, so closing enrollment stays closed. A token is a bootstrap credential: it lets an install register its own key with your team and nothing else. It yields no data, no certificate and no session, which is why it may sit in a configuration profile or a browser policy every user of the machine can read.
Under Settings → Devices → Enrollment tokens you can create more tokens (one per site or per rollout wave), give one an expiry or a cap on uses, and rotate or revoke it. With more than one, Install files asks which token the files should carry. Rotate when you suspect a leak; the old token keeps working for a day while your MDM picks up the new files.
Download the install files
The Install files page walks through five numbered steps: what to install (the browser extension or the desktop agent), where it goes (the platform, the MDM and the enrollment token the files carry), the files to download in the order your MDM should push them, where to upload each one in your MDM, and how to check that it worked. The page remembers your choices, so coming back for the next release starts where you left off. The trust certificate, the values for an MDM that builds its own profile or policy, and the individual profiles for an MDM that takes them one by one sit under Advanced at the bottom.
Browser extension. Configuration profiles for Chrome, Edge, Firefox and
Safari on macOS; one registry file for the three browsers on Windows; policy
JSON files for Linux; a Firefox policies.json; a Jamf custom schema; the
Safari declaration your MDM builds its always-on configuration from. These
files force-install the extension and carry your team, your sign-in connection
and the enrollment token. Where your MDM can substitute variables (Jamf Pro,
Kandji, Mosyle, Fleet), they also tell the browser its machine's serial number
and the person's email address, which a browser cannot find out on its own.
Nothing about how the extension behaves is in them.
Desktop agent. On macOS, the installer package and the profiles it needs:
the system extension allowance, the transparent proxy, login items,
Accessibility, notifications, the trust certificate and the agent settings
with the token. On Windows, the policy file first: it carries the token, the
team and the trust certificate's fingerprint, which only policy can, and
every MDM pushes it as system before the machine installer, which then needs
no properties. Then the installer itself, a detection script for Intune, and
Group Policy templates that describe the same policy key. The msiexec
command with the values as properties is for a tool that cannot push policy
first; it does not cover the trust certificate. On Linux, a script that writes the agent's
configuration and installs the package, the configuration file on its own,
the trust certificate, and the .deb and .rpm packages.
Downloading any file that carries the token is recorded in the audit log. A device or browser can register with your team as soon as it presents a valid token, whether it came from these files or from a profile you wrote yourself.
Push profiles before packages
Follow the steps the page shows for your MDM. The order matters on macOS: the profiles go first, so the agent finds the extension approved, the proxy configured and the token in place when the package installs. On Windows the installer runs as system and takes the values along. On Linux the script does both in one run as root.
Watch the rollout
Settings → Devices shows, for the agent and for the extension alike, how many installs registered, how many are waiting for a sign-in and how many are signed in. All devices lists every device and every browser from the moment it registers, with its state: waiting for sign-in and why (no identity provider session yet, not a member of the team, sign-in refused), signed in, needs attention and why, revoked.
Revoking a device or a browser stops it at once: its tokens die, a device gets no more certificates, and the install is told at its next check-in and clears what it holds. A revoked install cannot register again until you delete its row.
An install that registered but never signs in is what a leaked token produces: it holds nothing and uploads nothing, and it stays listed as waiting for sign-in. Rotate the token if you see installs you did not deploy.
When a device needs attention
A managed device that cannot capture shows Needs attention under All devices, with the reason under it. Open the device to see each account's Network extension and Certificate, and what to do.
| Reason | What it means and what to do |
|---|---|
| Network extension waiting for approval | The system extension and network profiles have not reached this Mac yet. Capture starts once they do. |
| Network extension not allowed | The network extension is turned off on this Mac. The system extension profile allows it. |
| Certificate not trusted yet | The device does not trust your team's certificate yet. Check that your MDM sends it the current install files. |
Windows and Linux capture without a network extension, so their devices show it as not used on this platform.
Device keys
Every managed desktop agent signs its requests to Joring with a key of its own. Where the machine has the hardware for it, the key is made and kept there and cannot be copied off the machine: the Secure Enclave on a Mac, the TPM on Windows and Linux. A machine without that hardware gets a software key.
If the hardware key cannot be made, or stops working, the agent moves to a software key and keeps going: a hardware key that fails never stops an install. The device shows its key as Software with the reason under it, and the Key filter under All devices lists the devices on each kind. When the agent updates, a managed device on a software key tries the hardware again; if it works now and Sign people in automatically is on, the device moves to the hardware key and signs in again on its own.
Installs people set up themselves
A member can also install the desktop agent or the browser extension on their own and sign in. Those installs work, and they appear under All devices after the managed ones, marked Not managed, with the person, the platform or browser, the version and when it was last seen. Use the Management filter to list only managed installs or only the ones that are not managed. The overview shows how many there are for each surface.
The settings in the table below do not apply to an install that is not managed, and there is nothing to revoke: it is the person's own sign-in. To bring one under management, push Joring to that computer or browser through your MDM. Once it registers with your team, it is listed as managed.
What managed installs do
One table at the bottom of Settings → Devices sets what a managed install does, separately for the browser extension and the desktop agent. Every setting starts on. Nothing here is written into an install file: each install is told when it registers and at every check-in (the agent every five minutes, the extension every hour), so a change reaches the fleet without a new push.
| Setting | Browser extension | Desktop agent | Effect |
|---|---|---|---|
| Sign people in automatically | Yes | Yes | Signs in through your identity provider without anyone asking. |
| Skip the welcome page | Yes | Not needed | No welcome tab opens on every desk after a fleet install. |
| Skip the sign-in prompt | Yes | Not needed | AI tool pages do not ask people to sign in. |
| Keep people signed in | Yes | Yes | Sign-out is hidden in the extension and refused by the agent. |
| Keep capture on | Not needed | Yes | Hides the agent's stop control. The extension has none. |
| Start capture automatically | Not needed | Yes | Capture starts on its own once the device is set up. |
| Install updates automatically | Not needed | Yes | The agent installs each release. The browser updates the extension. |
Only what an install must know before it can reach Joring stays in the files: the team, the sign-in connection and the enrollment token. If you change the connection the files name, push them again.
The trust certificate
Managed devices intercept with certificates signed by a certificate authority Joring holds for your team. The private key never leaves Joring. Each device receives short-lived certificates only for the AI hosts in your capture catalog, and only once a person is signed in on it.
Devices must trust the authority's root. On macOS the trust certificate profile does that; on Windows and Linux the agent's privileged component trusts the root the configuration pins, and the policy file and the Linux configuration file carry that pin. Rotation is two steps: create the next root, which the install files then carry beside the active one, and retire the old one once devices report the new anchor. Removing the profile stops interception within a minute; nothing is lost, and pushing it again resumes capture.
Managed configuration keys
The desktop agent reads these keys from the place your platform provides:
managed preferences for com.joring.agent.app or
/Library/Application Support/Joring/managed.json on macOS;
HKLM\SOFTWARE\Policies\Joring\Agent, the installer's properties or
C:\ProgramData\Joring\managed.json on Windows; /etc/joring/managed.json on
Linux. Policy wins over installer properties, which win over the file.
| Key | Meaning |
|---|---|
EnrollmentToken | The token the device enrolls with. |
TeamId | Your team. |
ApiUrl | A self-hosted API; only from policy or a root-owned file. |
SsoConnectionId | The sign-in connection to use without discovery. |
UserEmail, SerialNumber | Hints your MDM fills in, for display and routing only. |
AutoStartCapture | Start capture as soon as the prerequisites exist. Overrides the setting. |
LockCapture | Hides the stop control. Applies when either this or the setting says so. |
AllowSignOut | People may sign the agent out, unless the setting keeps them signed in. |
AllowSelfUpdate | The agent installs each release itself; off when your tool owns versions. |
TrustAnchorSha256 | The fingerprint of the root to trust; only from policy or a root-owned file. |
HideAccessibilityStep | Hide the macOS Accessibility step from the setup window. |
AllowDiagnostics | Support may request diagnostics from the agent. |
ConfigVersion | A version you set, shown on the device for troubleshooting. |
The four behaviour keys exist for the management system that wants to decide per device group. A lock set there can only tighten what Joring's setting says; a choice set there (auto-start, self-update) wins over it. Left unset, the settings in Joring apply. The install files Joring generates write none of the four, so a device installed from them follows the settings until you add a key yourself.
The browser extension reads its own policy, written by the browser install
files: teamId, ssoConnectionId, installToken, the optional
serialNumber and userEmail your MDM substitutes, and apiBaseUrl and
appBaseUrl for a self-hosted Joring.
What the platforms still limit
- A standard user on a user-enrolled (not device-enrolled) Mac may see a VPN consent the first time the proxy starts. Device enrollment avoids it.
- Safari's extension stays on by declaration only on supervised Macs running macOS 15 or later; on macOS 14 people allow it on each site the first time.
- A Windows self-serve install needs an administrator once; the MDM stream installs as system and needs nobody.
- Linux packages cover Debian and Ubuntu 22.04 or later, RHEL 9 and Fedora, on x86_64 and arm64, with systemd.
Decide who needs terminal coverage and confirm the data is landing.