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 people and, since attributes now carry a scope, to the devices those people connect from — rather than from static role membership.

The Policy section actually gates two different things, and it's worth keeping them straight:

  • Deployment preflight (this admin tool writing a configuration artifact to a device's UNC share) checks that the device's owner holds every ABAC attribute the profile requires, via Assignments. This is the preflight behaviour described throughout this guide and in the Deployment Preflight Reference: a missing or expired assignment returns a blocking finding and the deployment is refused.
  • Runtime key delivery (the ntkDrive/ntkMobile conductor deciding which attribute keys to hand a connecting device) is gated by Policy records, described below. A Policy never blocks anything ntkDeploy itself writes — it decides, at the moment a device reconnects to the conductor, whether that device receives the key for a governed attribute at all.

The practical effect for deployment preflight is:

  • A device without a mapped owner (a Peer ID) cannot be deployed to.
  • A person missing one of the ABAC attributes configured on the profile cannot have their devices deployed to — add the attribute in the Attributes tab, then assign it to the person in Assignments.

Managing policies correctly means keeping people records, attribute definitions, assignments, 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 six tabs for core ABAC management, plus five additional TPA tabs that appear only when the Policy Manager reports tradingPartnerAttributes: true:

Tab Purpose
Policies Rules that gate conductor-side delivery of one governed attribute's key to connecting devices — see The Policies tab
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 and a scope that can be assigned to people (subject scope) or matched against a device's environment (environment scope)
Assignments Person-to-attribute assignment records — which person holds which attribute, and until when
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
Device Profiles Admin-asserted device records (fingerprint, platform, managed, trust level) that the conductor matches against environment attributes — see The Device Profiles tab

The Policies tab

A Policy governs delivery of one attribute — its Resource — by the ntkDrive/ntkMobile conductor. Every time a device reconnects to the conductor, the conductor checks every Policy that governs an attribute it's about to hand out; if the device's environment doesn't satisfy the policy, the attribute's key is simply left out of the payload — before it would have been signed, so there is nothing for a modified client to intercept or bypass. An attribute with no governing Policy is ungoverned and is always delivered, exactly as before Policies existed.

Looking for a walkthrough? This section is a reference for the Policies tab. For a start-to-finish setup — minting the attributes, recording device environments, authoring the policy, and the simulate → dry-run → enforce rollout — plus copy-ready worked examples, see Setting Up Policy-Aware dABAC (End to End).

Two things are easy to assume incorrectly, so state them plainly:

  • Policies are org-wide, not per-device or per-person. The Person you pick when creating a policy records who authored or requested the rule — it is not an enforcement scope. Once saved, a Policy governs its Resource attribute for every device that connects to the conductor, regardless of which person owns that device.
  • A Policy is not a deployment-preflight rule. It has no effect on whether ntkDeploy can write a configuration artifact to a UNC share — that's governed by Assignments instead. A Policy only affects whether the conductor hands a governed attribute's key to a device at connection time.

If multiple policies govern the same Resource attribute, they are deny-overrides: every one of them must pass for the attribute to be delivered.

Viewing and filtering policies

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

  • Resource — the 32-character hex ID of an existing attribute this policy governs delivery of. A resource that doesn't match any existing attribute definition is inert: it's never evaluated by the conductor.
  • Peer ID — the Peer ID of the person who authored this policy. This is bookkeeping only — see above; it does not scope which devices the policy applies to.
  • Required Attributes — the policy's requirement sets, rendered as set1 OR set2 OR … with & joining the attributes that must all be held within a set — for example env:platform-desktop & env:managed-true OR env:trust-high means the device's environment must satisfy the first set (both attributes) or the second set (just the one) on its own.
  • 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). Requirement sets are exported in parenthesized clause notation, (a&b) | (c) — different punctuation from the grid's a & b OR c display, but the same OR-of-AND grouping.

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 — use the resource picker to choose the attribute this policy governs. It searches existing attribute definitions by label or ID; picking one fills the read-only Selected Resource Attribute ID field below it with the attribute's 32-character hex ID (the field that's actually validated and saved).
  4. Simulate against fleet — once a valid resource is selected, click this button to preview the policy's effect (see Simulating a policy against your fleet below) before you commit to saving it.
  5. Person — pick the person you want recorded as this policy's author using the person picker; the read-only Selected Peer ID field beneath it shows the resolved Peer ID and offers a copy button. This field is required to save the form, but — as above — it does not scope enforcement.
  6. Requirement Sets — build one or more requirement sets with Add requirement set (OR). Each set is its own attribute picker (labelled Requirement set N — all required (AND)); every attribute added to a set is AND'd together, and access is granted the moment any one set is fully satisfied. Attributes badged environment in the picker are evaluated against the connecting device (platform, managed status, trust level) rather than the assigned person — that's normally what you want in a requirement set, since delivery is decided by the device's environment, not by who owns it. Use Remove requirement set (the circled-minus icon) to drop a set. You must have at least one requirement set with at least one attribute, or saving fails with a validation message.
  7. Click Save. The grid refreshes and the new policy appears.

Tip: A Policy's requirement sets are checked against the connecting device's environment, not the assigned person's own attributes. To actually restrict delivery, build requirement sets out of environment-scoped attributes such as env:platform-desktop or env:trust-high — see Attribute scope and environment labels.

Simulating a policy against your fleet

Before — or after — saving a policy, click Simulate against fleet (enabled once the Resource field holds a valid 32-character hex attribute ID) to ask the Policy Manager's /policies/simulate endpoint what would actually happen, using the same evaluation code the conductor uses at connection time, so the preview cannot drift from real enforcement:

  • If no policy governs the resource yet, the summary reads "No policy restricts this resource — all N enrolled devices would receive it."
  • If no devices are registered in Device Profiles yet, it reads "No enrolled devices found to simulate against."
  • Otherwise it reads "X of Y enrolled devices would receive this attribute; Z withheld," followed by a per-device list showing each device's platform, managed status, and trust level, with a check or block icon indicating whether that device would receive the attribute.

"Enrolled" here means every device with a Device Profiles record — it is independent of the People tab's device-key enrollment status.

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. Deleting the last policy governing a Resource attribute makes it ungoverned again — every device will receive it going forward.

Note — the honest limits of policy enforcement:

  • It's not instant. A new, changed, or deleted policy takes effect the next time an affected device reconnects to the conductor — there is no push-revocation. A device that's already connected keeps whatever it was already given.
  • It doesn't claw anything back. Withholding an attribute's key stops future delivery; it does not remove a key a device already received, and it does not un-sync ciphertext that has already synced to a device. A withheld attribute simply fails to decrypt on that device, the same as any attribute the device was never assigned.
  • Attribute hygiene matters. A file encrypted under two attributes — one restricted by a policy, one not — is decryptable via the unrestricted one regardless of the policy. If you need a restriction to actually stick, make sure the sensitive attribute is required in its own requirement set (its own AND group) rather than one of several attributes any of which alone would unlock the file.
  • Device facts are admin-asserted, not attested. Platform, managed, and trust level (see Device Profiles) are what an administrator recorded, not a hardware attestation — treat them at the same trust level as the device fingerprint allowlist.

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. The server refuses to delete a person who is still referenced by an active Policy (person_has_policy_references) or by an assignment (person_has_assignment_references) — remove or reassign those records first.

The Attributes tab

Attributes are the labels that policies, assignments, and requirement sets all refer to by ID. An attribute has a Label (human-readable), an Attribute ID (the 32-character hex identifier used everywhere else in the app), a Default TTL (the number of seconds the attribute remains valid after assignment), and a Scope — Subject or Environment — that decides whether the attribute can be assigned to a person at all.

Viewing attributes

Columns: Label, Attribute ID (with copy icon), Default TTL (in seconds), ID, Actions. The grid doesn't show a Scope column directly — open a record, or look for the scope badge shown wherever an attribute picker lists it elsewhere in the app, to see whether it's Subject or Environment.

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). Letters, numbers, underscore, hyphen, and colon are all accepted; spaces you type are automatically converted to underscores. The colon is reserved for the env:* device-environment convention described below.
  4. Attribute ID — generated automatically (a random 32-character hex value) and shown read-only with a copy button. You don't type it yourself, and it can't be changed afterwards.
  5. Default TTL seconds — how long the attribute is valid after being granted to a person. For example, 86400 = 24 hours. Must be between 60 and 31,536,000.
  6. Scope — a segmented Subject / Environment control. Subject (the default) means the attribute can be assigned to a person in the Assignments tab. Environment means the attribute is never assignable to a person — it exists purely so the conductor can match it against a connecting device's environment (see below). Scope can only be set while creating the record; it is immutable after creation — editing an existing attribute shows the scope read-only.
  7. Click Save.

Attribute scope and environment labels

Subject-scoped attributes (the default, and everything that existed before Policies shipped) are the ones you assign to people in the Assignments tab.

Environment-scoped attributes are never assigned to anyone — the server rejects any attempt to assign one to a person with environment_scope_unassignable. Instead, the conductor computes which environment attributes a connecting device satisfies from that device's Device Profile, using a fixed label convention. To have an environment attribute actually participate in enforcement, create it with Scope = Environment and a Label that matches one of these exactly (case-insensitive):

Label Matches a device whose Device Profile has…
env:platform-desktop Platform = desktop
env:platform-mobile Platform = mobile
env:platform-server Platform = server
env:managed-true Managed = on
env:managed-false Managed = off
env:trust-low Trust Level = low
env:trust-standard Trust Level = standard
env:trust-high Trust Level = high

A device with no Device Profile record — or one the conductor can't resolve — satisfies none of these, so it fails any requirement set that names one.

Editing and deleting attributes

Use the edit and delete icons in the Actions column. Deleting is refused with attribute_in_use while the attribute has an active assignment. There is currently no equivalent guard for Policies — the server does not check whether the attribute is a Policy's Resource or appears in a requirement set before deleting it, so double-check the Policies tab yourself before deleting an attribute a policy still relies on.

The Assignments tab

The Assignments tab shows which attribute each person currently holds, and until when. This is what ntkDeploy's own deployment preflight checks against a profile's configured ABAC attributes — it is unrelated to the Policies tab's Resource/Requirement-Set governance.

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 people hold which attributes, and when each assignment expires.
  • Create new assignment records to grant a person an attribute. Only Subject-scoped attributes can be assigned — the attribute picker also lists Environment-scoped attributes with their scope badge, but saving is rejected with environment_scope_unassignable if you pick one, since environment attributes are computed from the device's Device Profile, not granted to a person.
  • Delete stale or expired assignments.

The Device Profiles tab

A Device Environment Profile is the admin-facing record of one device's environment, keyed by its 64-character hex fingerprint. It's what the conductor reads (and what Simulate against fleet reads) to decide which environment attributes a connecting device satisfies — see Attribute scope and environment labels. These are admin-asserted facts, not a hardware attestation — the same trust level as the device fingerprint allowlist already used elsewhere.

Viewing device profiles

Columns: Fingerprint (truncated, with copy icon), Platform, Managed, Trust Level, Actions.

Filtering: Search by fingerprint using the Search profiles by fingerprint field. Use the Managed and High Trust chips to narrow the list. Export CSV copies the current page (columns: Fingerprint, Platform, Managed, Trust Level) to the clipboard.

Creating or editing a device profile

  1. Click New in the Device Profiles toolbar.
  2. Fill in:
  3. Fingerprint — the 64-character lowercase hex fingerprint of the device. This can only be set when creating the record; it's immutable afterwards.
  4. Platform — desktop, mobile, or server.
  5. Managed — a toggle for whether the device is centrally managed.
  6. Trust Level — low, standard, or high.
  7. Click Save.

A device without a profile — or whose profile the conductor can't fetch — satisfies no environment attributes. Once your organization's conductor has policy enforcement turned on, that means the device fails closed and receives no governed attributes at all; ungoverned attributes are unaffected.

Bulk operations

The core Policy tabs support two kinds of bulk work: bulk delete/revoke for clearing many records at once, and CSV import for creating many records at once. Everything here is admin-console convenience — it drives the same Policy Manager APIs the single-record forms use, and none of it is access-control enforcement (that stays with the conductor).

Bulk delete and revoke

Select rows with the checkbox column (a header checkbox selects the whole page), then use the bulk action in the selection bar:

Tab Bulk action
Policies, Attributes, Assignments, Device Profiles Delete selected
People, Attribute Templates Delete selected
Devices Revoke selected (active registrations only)

Every bulk action first opens a confirmation dialog showing how many records are affected. After you confirm, the app processes each record and reports a "N of M" summary (for example, "Deleted 7 of 8 assignments"). If any record fails, the successful ones are removed and the failed rows stay selected so you can retry just those. Triggering a bulk action while one is already running is ignored, and if nothing in your selection is actually eligible (for example, a Devices selection containing only already-revoked rows) the app tells you instead of opening an empty dialog.

Deletion still respects the server's referential guards — for example, a person still referenced by a policy or an assignment is refused, exactly as for a single delete.

CSV import

The People, Attributes, and Assignments tabs each have an Import CSV action. Each importer accepts either a .csv file (read as UTF-8, so accented names import correctly) or text pasted into the dialog, shows a live preview of the parsed rows, and after running reports a per-row summary counting created, reused, skipped (with a reason), and failed (with the server error) rows. The header row is matched case-insensitively.

Importer Required columns Behaviour
People Display Name, Org Unique ID Matches an existing person by Org Unique ID and reuses it unchanged; creates a new person (with a generated Peer ID) when there's no match. Rows missing either field are skipped.
Attributes Label Matches an existing attribute by Label (trimmed, case-insensitive) and reuses it without touching its scope or TTL; creates a new subject-scoped attribute with a 3600-second TTL otherwise.
Assignments Org Unique ID, Expiration, and either Attribute ID or Attribute Label Joins Org Unique ID to a person and resolves the attribute by Attribute ID (canonicalised, taking precedence when both columns are present) or Attribute Label (best-effort). Expiration is required. Only assignments are created — never people or attributes. Unknown Org Unique IDs, unknown attributes, an ambiguous label (two attributes share it), or a missing/invalid expiration all skip the row with an explicit reason.

"Reuse" means the importer is safe to re-run: importing the same People or Attributes list twice does not create duplicates. Within a single import, a brand-new key that appears on two rows is created once and reused on the second row.

Combined bulk import

The People tab also has a Bulk Import action (shown only when the Policy Manager connection is available) that provisions people, attributes, and assignments from one list. The columns are Display Name, Org Unique ID, Label, and Expiration.

For the whole file it first upserts every person (by Org Unique ID) and every attribute (by Label) — reusing existing records without modifying them — and only then creates the assignments that join each row's person to its attribute with the given expiration. A row's assignment is attempted only when both its person and attribute resolved successfully; if either was skipped or failed, no orphaned assignment is created for that row. The results table shows a rolled-up status per row (failed if any step failed, otherwise skipped, created, or reused) with an expandable breakdown of the person, attribute, and assignment outcomes.

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

This is ntkDeploy's own deployment preflight — the ABAC gate on writing a configuration artifact to a device. It runs on Assignments and TPA grants, not on the Policy records in the Policies tab; a Policy never blocks a deployment by itself (see The Policies tab).

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. Validates the profile's configured ABAC attributes against the resolved peer's assignments and, where applicable, imported TPA grants.
  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 person is missing a required attribute assignment, or their assignment has expired (add the attribute in the Attributes tab, then assign it to the person in Assignments).
  • 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).

See the Deployment Preflight Reference for the full, current list of failure codes.

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