Skip to content

Managing Policies

This tutorial explains the Policy section of ntkDeploy and shows you how to create and maintain the ABAC rules, people records, attribute definitions, and Trading Partner Attributes (TPA) records that gate every deployment.

What is ABAC and why does it matter for deployment?

Attribute-Based Access Control (ABAC) is an access model where permission decisions are computed from attributes — labels attached to both people (subjects) and devices (resources) — rather than from static role membership.

In ntkDeploy, the Policy Manager V2 API enforces ABAC during preflight: before any configuration artifact can be written to a device, the system checks whether that device's owner has all required attributes. If a required attribute is missing or expired, the preflight returns a blocking finding and deployment is prevented.

The practical effect is:

  • A device without a mapped owner (a Peer ID) cannot be deployed to.
  • A person without the required attributes specified in a policy cannot have their devices deployed to.
  • A policy without a valid resource or peer-ID reference will not match any devices.

Managing policies correctly means keeping people records, attribute definitions, and policy rules in sync with your fleet.

Prerequisites

  • The Policy Manager endpoint is configured and reachable. Open Settings from the sidebar, enter the Policy Manager URL, and click Validate. The connectivity badge in the app header should show a healthy status.
  • If the Policy section shows "Policy management is unavailable", configure the endpoint and click Retry.

Click Policy in the sidebar. The section contains five tabs for core ABAC management, plus five additional TPA tabs that appear only when the Policy Manager reports tradingPartnerAttributes: true:

Tab Purpose
Policies ABAC rule records — each policy links a resource identifier, a Peer ID, and a list of required attributes
People Person registry — display names, Peer IDs, org identifiers, device fingerprints; includes the Enrollment Queue sub-tab
Attributes Attribute definitions — reusable labels with a TTL that can be assigned to people
Assignments Policy-to-resource assignment records
Attribute Templates Reusable attribute bundles and helper templates for faster assignment workflows
My Identity Read-only view of the local organisation identity and keys — capability-gated
TPA Definitions TPA definition records — capability-gated; see Trading Partner Attributes (TPA)
TPA Grants Issued TPA grants and one-time key export — capability-gated
TPA Trusts Trading partner trust relationships and trusted key management — capability-gated
TPA Imports Incoming grant imports from trading partners — capability-gated

The Policies tab

Viewing and filtering policies

The Policies tab lists every policy record fetched from the Policy Manager. Columns:

  • Resource — the resource identifier (for example, a device key or device-group identifier) the policy applies to.
  • Peer ID — the person Peer ID this policy is bound to.
  • Required Attributes — comma-separated list of attribute identifiers that the peer must hold.
  • ID — the server-assigned policy ID (may be empty for locally created records not yet synced).
  • Actions — edit and delete buttons.

Filtering:

  • Type a Peer ID fragment in the Search policies by Peer ID field and press Enter to filter the list.
  • Use the Has ID chip to show only records that have a server ID.
  • Use the Has Attributes chip to show only records with at least one required attribute.
  • Save the current filter combination as a named view using Save view and recall it with the Saved view selector.

Exporting: Click Export CSV to copy a CSV representation of the current page to the clipboard (columns: Resource, Peer ID, Required Attributes, ID).

Creating a policy

  1. Click New (the button with the + icon in the top-right of the Policies tab). A form panel slides in from the right.
  2. Fill in:
  3. Resource — the device or resource identifier this rule applies to.
  4. Peer ID — the person Peer ID to bind. You can copy a Peer ID from the People tab using the copy icon next to any row.
  5. Required Attributes — the attribute identifiers that the peer must hold at deployment time. Select them from the attribute picker that appears. Each attribute must already exist in the Attributes tab.
  6. Click Save. The grid refreshes and the new policy appears.

Tip: If the Peer ID field is unfamiliar, navigate to the People tab first, copy the Peer ID for the relevant person, then return to Policies.

Editing a policy

Click the edit icon (pencil) in the Actions column of any row, or click anywhere on the row to open the detail panel. Inside the panel, click Edit, make changes, and click Save.

Deleting a policy

Click the delete icon (trash) in the Actions column. A confirmation dialog asks:

"Are you sure you want to delete \<resource>?"

Click Delete to confirm. The policy is removed from the Policy Manager and the grid refreshes.

Warning: Deleting a policy that gates active devices will cause those devices to fail preflight on the next deployment. Remove policies only when the corresponding devices are decommissioned or the access requirement has been lifted.

The People tab

Viewing the people registry

The People tab has two sub-tabs: People and Enrollment Queue.

The People sub-tab lists every person record in the Policy Manager. Columns:

  • Display Name — human-readable name.
  • Peer ID — the 32-character hexadecimal identity string. Click the copy icon to copy it.
  • Org Unique ID — organization-specific identifier: login email address.
  • Enrollment — shows Enrolled or Not enrolled with a shield icon. Enrolled means at least one device key fingerprint is associated with this person. A pending enrollment fingerprint appears only in the person detail panel, not as a grid row badge.
  • Status — active or disabled.
  • Tags — free-form labels.

Filtering: Type a display name in the Search people by display name field and press Enter. Use the Active and Disabled chips to filter by status.

Adding a person

  1. Click Add Person in the toolbar.
  2. The person form slides in. Fill in:
  3. Display Name — required.
  4. Peer ID — a 32-character hex string is generated automatically. You may override it, but it must be exactly 32 hex characters.
  5. Org Unique ID — login email address; used for cross-system correlation.
  6. Status — active (default) or disabled. Disabled people are excluded from policy evaluation.
  7. Tags — optional comma-separated labels for grouping or reporting.
  8. Click Save. The record is created in the Policy Manager and the grid refreshes.

Note: The Device Authentication section of the form shows the registered device key fingerprints for this person. A newly added person has no fingerprints and displays the Not enrolled state. Fingerprints are added automatically when an enrollment request is approved — see Device Enrollment.

Editing a person

Click the edit icon in any row or click the row to open the detail panel. Click Edit, update fields, and click Save.

Managing device key fingerprints

The Device Authentication section in the edit panel lists all fingerprints registered to the person. Each fingerprint row shows a truncated fingerprint string and two actions:

Action Description
Copy (clipboard icon) Copies the full fingerprint to the clipboard
Revoke (remove icon) Removes this fingerprint from the person's record

Revoking a fingerprint:

  1. Click Edit to enter edit mode (revoke is disabled when viewing).
  2. Click the Revoke icon on the fingerprint row you want to remove.
  3. A confirmation dialog asks whether you want to revoke the fingerprint. Click Revoke to confirm or Cancel to abort.
  4. The fingerprint is removed from the list and the person record is saved immediately via the Policy Manager API.

If a person has no fingerprints (all revoked or never enrolled), the enrollment status chip shows Not enrolled and the section body shows No device fingerprints registered.

Warning: Revoking a fingerprint unlinks the associated device from this person. That device will fail the connectivity gate check until a new enrollment is approved or the fingerprint is restored.

Deleting a person

Click the delete icon. Confirm in the dialog. Deleting a person removes their Peer ID from all policies that reference it. Audit the Policies tab afterwards for orphaned policy records.

The Attributes tab

Attributes are the labels that policies require. An attribute has a Label (human-readable), an Attribute ID (the identifier used in policy requiredAttributes), and a Default TTL (the number of seconds the attribute remains valid after assignment).

Viewing attributes

Columns: Label, Attribute ID (with copy icon), Default TTL (in seconds), ID, Actions.

Filtering: Search by label using the Search attributes by label field. Use the TTL <= 1h and TTL > 1h chips to filter by duration.

Creating an attribute

  1. Click New in the Attributes toolbar.
  2. Fill in:
  3. Label — human-readable name (for example, corp-device-approved).
  4. Attribute ID — the identifier referenced in policy rules. Once created this cannot be changed without updating every policy that references it.
  5. Default TTL — how long (in seconds) the attribute is valid after being granted to a person. For example, 86400 = 24 hours. Leave blank to use the server default.
  6. Click Save.

Editing and deleting attributes

Use the edit and delete icons in the Actions column. Deleting an attribute that is referenced in active policy records will cause those policies to fail preflight evaluation. Update policies before deleting attributes.

The Assignments tab

The Assignments tab shows policy-to-resource assignment records linking policy rules to specific deployment contexts.

Columns

Column Description
Display Name Human-readable name resolved from the person registry for this row's Peer ID. Shows – when the person cannot be resolved.
Org Unique ID Organization identifier (login email) resolved from the person registry. Shows – when unavailable.
Peer ID The 32-character hex Peer ID this assignment binds.
Attribute Label Human-readable label of the assigned attribute.
Attribute ID The machine identifier of the assigned attribute.
Expiration Timestamp when this assignment expires, or blank if it does not expire.
Actions Edit and delete buttons.

Display Name and Org Unique ID are resolved client-side from the local person metadata cache when the page loads. They are not returned directly by the Policy Manager — they are looked up from the People registry using each row's Peer ID.

Filtering

The assignment grid supports local metadata filtering:

  • Type in the Search field and press Enter to filter rows by Display Name, Org Unique ID, or Peer ID.
  • Use the filter chips in the toolbar to narrow by assignment state (Active or Expired).

Filters on Display Name and Org Unique ID operate on the locally resolved person data. Rows whose person data has not yet loaded show – and are excluded from name/ID filter matches until resolution completes.

Exporting

Click Export CSV to copy a CSV representation of the current page to the clipboard. The export includes these columns in order: Display Name, Org Unique ID, Peer ID, Attribute Label, Attribute ID, Expiration, ID.

Managing assignments

Use this tab to:

  • View which policies are assigned to which resources and who they are bound to.
  • Create new assignment records when a policy needs to be explicitly bound to a resource.
  • Delete stale assignments for decommissioned resources.

Trading Partner Attributes (TPA)

TPA is an advanced capability that lets administrators issue signed attribute grants to trading partners and accept signed grants from partners. The five TPA tabs are visible only when the connected Policy Manager reports tradingPartnerAttributes: true in /capabilities. If the tabs are absent, the server does not support TPA.

Note: TPA is policy-layer functionality, not a provider feature. It is independent of deployment target types (UNC, local, mobile).

For TPA-enabled deployments, ntkDeploy loads the deployment's local organization identity from the Policy Manager's secure identity endpoints. Issuer and local-org values are shown read-only in the grant and trust workflows; operators no longer type those owner-org fields manually.

End-to-end TPA workflow

TPA always involves two organisations: an issuer and a recipient. The two sides must complete their setup steps in the correct order.

Important: Before creating any definitions, grants, or imports, it is highly recommended that both organisations establish trust by exchanging Identity Cards. See the Trading Partner Onboarding (Identity Exchange) tutorial for the primary trust-backed path. An alternative manual onboarding path is available as an advanced fallback.

Issuing a grant to a partner

You are the issuer. You want to delegate a set of permissions to a remote organisation.

  1. Create a TPA Definition — defines the allowed scope types and permissions for this category of grant. (Skip if one already exists.)
  2. Create a TPA Grant under that definition, targeting the partner's organisation.
  3. Export the key package immediately — a non-deferrable dialog appears after creation. Save the tpa-export/v1 JSON file; this is the only opportunity to retrieve the key material.
  4. Send the grant to your partner:
  5. Send the exported JSON package.
  6. (Advanced/Manual path only) If you have not completed the Identity Exchange, you must also send your ML-DSA-44 public key (.pub file from the installer, or the hex text printed during setup). Your partner must manually add this key to their Trust record before they can import your grant.

Receiving a grant from a partner

You are the recipient. A partner has sent you their exported grant package.

Required first step: You must have an active TPA Trust record for the issuing organisation before attempting any import. The server checks the trust during both the advisory validation and the final commit. Without a matching trust record the import will immediately fail with trust_not_found.

  1. Create a TPA Trust for the issuer (see TPA Trusts below). The trust now carries its scope-type and permission policy from the moment it is created:
  2. Recommended Path: Click New Trust and import the partner's Identity Card. The card supplies the issuer's org ID, signing key, and fingerprint; you confirm the fingerprint out-of-band and choose the allowed scope types and permissions in the same panel before clicking Create Trust. See the Identity Exchange tutorial.
  3. Advanced/Manual Path: Use the Advanced: enter partner manually escape hatch to hand-type the issuer's organisation ID, set the scope types and permissions, and upload their ML-DSA-44 public key. Without this trust record, imports from this partner will always fail.
  4. Import the grant package via TPA Imports — load the JSON file, click Validate, review any findings, then commit.

Summary: Trust (with scope + permission policy) -> import, in that order. Setting up the trust first is the only correct path. Every trust_not_found finding means this step was skipped or the remote org ID in the trust does not exactly match the issuer org ID in the grant. A trust with no scope types or permissions will also block successful validation, so make sure those are set when you create it.

TPA Definitions

A TPA Definition describes a reusable grant template: a tpaId (32-character hex), a default TTL in seconds, and the allowed scope types and permissions that grants under this definition may carry.

Creating a TPA Definition

  1. Click TPA Definitions in the Policy section and then click New.
  2. Fill in the form:
  3. Label — a human-readable name for the definition.
  4. TPA ID — a 32-hex-character identifier. Click Generate to fill a cryptographically random value, or enter one manually.
  5. Trading Partner ID — select the partner organisation from the trust-backed partner directory picker.
  6. Default TTL (seconds) — how long grants under this definition remain valid. Range: 60–31,536,000.
  7. Allowed Scope Types — select exactly one from message, thread, workspace, file, dataset.
  8. Allowed Permissions — add the permission strings that grants may include. At least one is required.
  9. Click Save. The definition record is created in the Policy Manager.

TPA Definition records are shown with a distinct badge (secondary container colour) so they are visually separable from internal AttributeDef records.

Editing and deleting TPA Definitions

Click the edit icon or open the detail panel and click Edit. Send the updated record; optimistic concurrency applies — if a version conflict occurs, reload and retry.

Click Delete. Confirm in the dialog. Existing grants that reference the definition are not automatically revoked; they continue to exist but cannot be renewed.

TPA Grants

A TPA Grant is a signed, single-use token that delegates a set of permissions from your organisation to a trading partner for a bounded scope and time window. The grant contains a private tpaKey that must be extracted immediately after creation.

Creating and exporting a grant

The grant creation wizard has seven user-facing steps:

  1. Select Definition — choose a TPA Definition; tpaId is auto-filled from the selected record.
  2. Issuer Details — review the read-only local organization card loaded from the connected Policy Manager. The wizard submits issuerOrgId from that server-authoritative value and shows the local display name plus orgId for confirmation. Choose the issuing person, then review the read-only issuerPeerId resolved from that selection; issuerKeyId is derived automatically from the loaded ML-DSA signing key. If the local organization context, issuer person lookup, or signing key cannot be loaded, the wizard stops here until the issue is resolved.
  3. Recipient — choose the recipientMode and enter the corresponding recipient identifier(s).
  4. Scope and Permissions — choose scopeType, scopeId, and the permissions to include (limited to those defined in the selected TPA Definition).
  5. Validity Period — set notBefore and endDate using the date pickers. The system validates notBefore < endDate and endDate > now.
  6. Review and Generate — the app auto-computes the grantId (32 secure hex chars) and tpaKey (32 random bytes), calculates the canonical hash, and signs the payload. A progress indicator is shown during the signing step.
  7. Preview — review all fields before submitting to the Policy Manager.

After a successful POST /tpa/grants, an Export TPA Key Material dialog appears immediately. This dialog is the only opportunity to retrieve the key material:

TPA key material is only available now. After export, it cannot be retrieved from the server.

  • Click Export to File to save the tpa-export/v1 JSON package to a local file. The package contains all grant fields and the tpaKey (hex-encoded).
  • Click Cancel — key will be lost (a second confirmation is required) to abandon the key.

After export completes or is cancelled, the tpaKey bytes are zeroed from memory. No second export attempt is possible.

Caution: Keep the exported package file in a secure location. Anyone in possession of the file can submit the grant for import.

Grant list

The grant list shows status badges (active / expired / revoked), an expiry countdown when the grant ends within 30 days, and an amber Not yet valid badge when notBefore is in the future.

Grants that reference a superseded grant via replacesGrantId show a truncated lineage link to the original.

Revoking a grant

Open the grant detail panel and click Revoke. Confirm in the dialog. After revocation, any TPA imports that reference this grant will return TPA_REVOKED during the next preflight run and deployment will be blocked until the import is removed or replaced.

TPA Imports

Prerequisite: You must have an active TPA Trust record for the issuing organisation before importing their grant. If no trust exists — or the trust's remote org ID does not exactly match the grant's issuerOrgId — commit-time revalidation will fail and return trust_not_found to the review step for remediation. See TPA Trusts for setup instructions.

TPA Imports record grant packages received from a remote trading partner. The import workflow is a three-step process with back navigation available before commit:

  1. Load Package — click Select Export File and choose the tpa-export/v1 JSON file provided by the issuing partner. Files exceeding 1 MB are rejected before parsing. After successful parse, a read-only summary card shows the schema version, grant ID (truncated), issuer organisation, and expiry. The summary also shows an issuer trust badge: if no matching trust exists yet, a Trust not established badge appears alongside an Establish trust button that opens the partner Identity Card panel inline, so you can create the trust without leaving the import. The badge re-checks the current trust list whenever you return to the tab, so a trust you create elsewhere is reflected here.
  2. Review Findings — click Validate to send the nested grant, including grant.tpaKey, to the Policy Manager for advisory validation so the request matches the running server validator and commit-time payload shape. A successful validate call advances the workflow with the current validation state; if commit-time revalidation later fails, those findings are returned to this review step for remediation. TPA_CANONICAL_HASH_MISMATCH and TPA_INVALID_SIGNATURE use a highlighted error-container background because they indicate possible tampering.
  3. Commit — once validation succeeds, click Continue to Commit, review the confirmation step, tick the explicit confirmation checkbox, and then click Confirm Import. The commit request includes the key alongside the grant fields. The server re-validates at commit time; if blocking findings appear during that final check, the workflow returns you to review with those findings surfaced for remediation.

Common validation findings and their remediation:

Code Meaning Remediation
trust_not_found No active trust exists for the issuer Create a trust relationship under TPA Trusts first
canonical_hash_mismatch Computed hash does not match the grant The package may be corrupted or tampered; request a new export from the issuer
invalid_signature Signature verification failed The package may have been tampered; request a new export
scope_not_allowed Scope type not in the trust's allowed list Update the trust record to include the required scope type
permissions_exceed_trust Grant permissions exceed what the trust allows Update the trust record or request a re-issue with narrower permissions

When replacesGrantId is set on the imported grant, a banner shows the superseded grant ID. On successful commit, the server atomically revokes the old grant.

After commit or cancellation, the in-memory key bytes are zeroed.

Import management

Active imports are listed with status badges: active, expired, revoked, rejected, disabled. Use Disable (requires confirmation) to deactivate an import without deleting the record. Use Delete to remove the record; note that deleting the import record does not affect the grant on the issuing side.

TPA Trusts

A TPA Trust authorises your organisation to accept grants from a specific remote organisation. Each trust defines which scope types and permissions the remote partner may grant, and identifies the ML-DSA-44 public keys whose signatures you will accept.

Creating a trust

Click TPA Trusts and then New Trust. The primary flow imports the partner's Identity Card so you never hand-type an org id or key id:

  1. Paste the card JSON into Paste Identity Card JSON, or click Load from file to select the card file the partner shared. The panel parses the card and shows the Remote Org ID and the card's self-signature status.
  2. Confirm the Trust Label (pre-filled from the partner's display name).
  3. Select the Scope Types and Permissions this trust will accept — at least one of each is required. This is the policy envelope incoming grants are validated against.
  4. Tick the checkbox affirming you verified the card's fingerprint out-of-band (see Trading Partner Onboarding).
  5. Click Create Trust.

The card supplies the remote org ID and the ML-DSA-44 signing key, and ntkDeploy derives the canonical Key ID (sha256:<fingerprint>) automatically.

Advanced — manual entry: If a partner cannot share a card, click Advanced: enter partner manually to open the manual form. There you hand-type the Remote Org ID, set the Label, Scope Types, and Permissions, then in the Trusted Keys section click Add Key and Upload ML-DSA Public Key — the file must be exactly 1312 bytes (or a UTF-8 text file containing the hex-encoded 1312-byte key); invalid sizes are rejected immediately. The Key ID and fingerprint are computed automatically from the uploaded key. Local Org is shown read-only and submitted as localOrgId. Only one trust per local/remote pair is allowed.

If the local organization context cannot be loaded from the Policy Manager, the create flow stays unavailable until the connection is restored. Read-only browsing of existing records is still available.

Updating, revoking, and deleting

Open a trust row to view its detail panel, then click Edit to change its label, scope types, permissions, or trusted keys. If the server reports that a key you are trying to remove is used by active grants (key_in_use), a dialog lists the affected grant IDs; revoke those grants first before retrying the key removal.

Click Revoke Trust to revoke the entire relationship. Confirm in the dialog. After revocation, all imports from this partner will fail preflight validation with TPA_MISSING_TRUST or TPA_INVALID_ISSUER.

A revoked trust still occupies the unique local-org/remote-org slot, so you cannot create a fresh trust for the same partner while it exists. To free the slot, open the revoked trust and click Delete Trust; confirm in the Delete Revoked Trust? dialog. Deletion is only permitted on a revoked trust — attempting to delete an active or suspended trust prompts you to revoke it first.

Key fingerprint display

Public key fingerprints are shown as the first 16 hex characters of the SHA-256 hash of the full 1312-byte public key. Hover over any truncated fingerprint to see the full 64-character value. Raw key bytes are never displayed.

How TPA affects deployment preflight

TPA findings are evaluated alongside ABAC findings during the per-device preflight step. A single blocking TPA finding prevents deployment for all affected devices.

For the full list of TPA finding codes and their remediation guidance, see Deployment Preflight Reference — TPA Preflight Findings.

Typical TPA preflight blockers:

  • TPA_MISSING_TRUST — create a trust relationship for the issuer before importing grants from them.
  • TPA_NOT_YET_VALID — a grant's notBefore is in the future; wait until the validity window opens or ask the issuer to adjust it.
  • TPA_REVOKED — grant or import is revoked; remove or replace it.
  • TPA_CANONICAL_HASH_MISSING — the grant was not signed correctly; the issuer must re-create the grant.

How policies gate deployment

When you run the deployment wizard and reach the Review step, ntkDeploy calls the Policy Manager and:

  1. Checks that the connectivity gate is open.
  2. Submits a batch of device key lookups to resolve each device in the selected groups to a Peer ID (via ownership mappings).
  3. Requests a policy plan — the Policy Manager evaluates every policy for the resolved Peer IDs and attributes.
  4. Reports blocking findings (deployment blocked) or warning findings (deployment allowed with notes).

A blocking finding typically means one of:

  • The Peer ID has no ownership mapping (add one via Device Enrollment or inline in Device Groups).
  • The Peer ID is missing a required attribute (add the attribute in the Attributes tab, then assign it to the person).
  • A TPA grant is missing trust, not yet valid, revoked, or exceeds the trust policy for that partner.
  • The Policy Manager is unreachable (fix the endpoint in Settings).

Policy status badge

The app header shows a badge indicating the current connectivity gate status:

  • Connected (green) — Policy Manager is reachable; ABAC evaluation is available.
  • Degraded (amber) — Policy Manager is partially available; some capabilities may be missing.
  • Disconnected (red) — Policy Manager is unreachable. Deployment is blocked. Check the endpoint in Settings.

Next Steps