Enrollment

Enrollment is how agent endpoints are added to Ordyn.

What you need

For an endpoint enrollment you need:

• an edge node
• an endpoint enrollment token created in Ordyn

Flow

1. the installer or operator provides edge host and enrollment token
2. the agent creates a keypair and CSR locally
3. the agent sends the enrollment request to the edge node
4. the edge node forwards it to Ordyn
5. Ordyn validates the token and CSR
6. Ordyn creates or claims the endpoint record
7. Ordyn issues the endpoint certificate
8. the agent stores the returned certificate material locally
9. the endpoint enters pending approval or is automatically approved, depending on the admin selection.

Enrollment tokens

Ordyn uses enrollment tokens for endpoint and service-client enrollment.

Endpoint enrollment tokens

You may create as many enrollment tokens as you need in Ordyn. Enrollment tokens can have an expiration date or limited uses. Tokens can also use automatic approval, which approves the endpoint after successful enrollment.

Bound enrollment tokens

A bound enrollment token is tied to one specific prepared endpoint.

Use this when:

• you created the endpoint record first
• you want one install to claim exactly that record

In the UI this is exposed as Create bound enrollment token on the prepared endpoint.

Service-client enrollment tokens

A service-client enrollment token is scoped to one configured service client.

Create the service client first, then issue an enrollment token from the enrollment tokens page:

1. Select Service client as the token purpose.
2. Select the service-client type.
3. Select the edge service.
4. Select the eligible service client.
5. Create the token and copy the plaintext value shown once.
6. Run the service client's enrollment command and provide the token.

The service client stores its certificate state locally after enrollment.

Service-client certificate lifetime and renewal

Service-client certificates authenticate enrolled service clients such as SNMP, Telematik, Webhooks, Package Discovery, and Net. The service-client detail page shows the current certificate serial and expiration date.

The default certificate lifetime is 10 years unless the Ordyn server is configured with a different service-client certificate validity period.

Renewal is an operator task. Plan renewal before the expiration date shown in Ordyn:

1. Create a service-client enrollment token for the same service client.
2. Run the service client's enrollment command with that token.
3. Restart the service container so it uses the refreshed certificate state.
4. Confirm that the service-client detail page shows a later certificate expiration and an active connection.

When a service-client certificate expires, the service client cannot authenticate to Edge with that certificate. The service appears disconnected or reports connection errors until it is enrolled again.

Revoking a service-client certificate has the same operational recovery path. Issue a scoped service-client enrollment token, run enrollment again, restart the service container, and confirm the updated certificate state in Ordyn.

Supported agent operating systems

Endpoint agent enrollment is supported on these operating systems:

Operating system	Architecture
Windows Server 2016	x64
Windows Server 2019	x64
Windows Server 2022	x64
Windows Server 2025	x64
Windows 11 24H2	x64
Windows 11 25H2	x64
Debian 12	x64, ARM64, ARMHF
Debian 13	x64, ARM64, ARMHF

Debian enrollment

Install the package:

dpkg -i dist/ordyn-agent_<version>~<codename>_<arch>.deb

For noninteractive enrollment during install, provide both environment variables:

ORDYN_EDGE_HOST=ordyn-edge.example.com \
  ORDYN_ENROLLMENT_TOKEN=<token> \
  dpkg -i dist/ordyn-agent_<version>~<codename>_<arch>.deb

If both values are present and no state file already exists, the package post-install flow automatically enrolls the endpoint.

Windows enrollment

Windows agents are enrolled through the MSI installer. It prompts the user for an enrollment token and edge host.

The MSI also supports noninteractive installation through public MSI properties:

msiexec /i .\dist\ordyn-agent_<version>_x64.msi `
  ORDYN_EDGE_HOST=ordyn-edge.example.com `
  ORDYN_ENROLLMENT_TOKEN=<token>

If both properties are provided and no existing state file is present, setup skips the enrollment dialog and enrolls automatically during installation.

PowerShell security controls

Several built-in Windows operations and the endpoint script feature launch PowerShell. Endpoint security controls must permit the PowerShell processes and scripts started by Ordyn. This includes applicable PowerShell execution policies, AppLocker rules, App Control for Business policies, attack-surface reduction rules, and EDR application controls.

These products use different matching and exclusion mechanisms. Configure the narrowest allowance supported by the product for the Ordyn agent, the required PowerShell activity, and the execution identities selected for endpoint scripts. Do not disable PowerShell security controls globally.

If the required allowance is missing, PowerShell-backed jobs and configuration profiles can fail even though the Ordyn agent itself is permitted to run. Using the endpoint script feature requires policies that allow the submitted script content and its selected execution context.

Approval after enrollment

Successful enrollment does not automatically allow the endpoint to connect to Ordyn.

If the enrollment token is configured to automatically approve the endpoint, this step is approved automatically; otherwise, an operator has to approve the endpoint manually.

See Pending Endpoints for the approval and rejection workflow.

Prepared and PXE-related enrollment

Prepared endpoint + bound token

If you pre-create an endpoint, a bound enrollment token can claim exactly that record.

PXE and OS-install flow

For PXE-based provisioning, claim can also happen through the install workflow driven by ordyn-net. This allows devices that are created manually with their MAC address to be enrolled automatically after PXE installation completes.