Appearance

Authorization and Visibility ​

Control what appears in the Applications tab and which executables are allowed to launch.

What You'll Learn

  • Authorize applications using allow policies (allowlist model)
  • Keep apps visible or hide them while still enabling file association targets
  • Understand how priority affects outcomes when multiple policies match

Authorization (Allowlist) ​

A launch is permitted only if at least one enabled application policy with action: "allow" matches the discovered executable (a shortcut target on Windows, an application bundle or command-line tool on macOS). An empty apps list authorizes nothing, on every platform; what a machine runs on when no policy is delivered at all differs per platform and is described in Merging & Precedence → Policy sources and delivery.

Security Rule — Deny Always Wins

If any matching application policy has action: "deny", the launch is blocked, even if one or more matching policies have action: "allow".

Use deny sparingly and deliberately (for example, to enforce global blocks on high-risk executables). Once a deny matches, the app is neither visible nor launchable. A deny applies at every site — visibilityConstraints.siteRefs scopes allow and modify rules only.

modify never authorizes

A third action, action: "modify", applies modifications and profiles to a launch that a separate action: "allow" policy has already permitted. A modify policy on its own does not authorize anything, and a modify policy with a higher priority than the allow does not replace it as the deciding rule. Use it to attach behavior (for example an MCP overlay's flags) to an app whose authorization is defined elsewhere. The allow / deny / modify vocabulary is identical on Windows and macOS; a policy authored for one platform decodes on the other.

  • If no allow policy matches, the application is not launchable and will not appear in the Applications tab.
  • Matching is performed against the discovered application and the resolved executable; matchers can include shortcut name, target path, arguments (Windows), bundle and team identifiers (macOS), and high-assurance identity (publisher certificate, file hash, version, code directory hash). One matcher vocabulary is accepted on both platforms; a type a platform cannot evaluate never matches there. See Matchers & Patterns.
  • Only id is required on a rule: enabled defaults to true, priority to 500, action to allow, displayName to the id.

Tip: Use matchAny to express OR across alternatives; use matchAll for AND logic.

Minimal allow example:

json
{
  "id": "allow-chrome",
  "displayName": "Allow Chrome",
  "enabled": true,
  "priority": 200,
  "matchAll": [
    { "type": "targetPath", "pattern": ".*\\\\chrome\\.exe$", "patternType": "regex" }
  ],
  "action": "allow"
}

Additional example (OR across browsers using matchAny + glob):

json
{
  "id": "allow-chromium-browsers",
  "displayName": "Allow Chrome or Edge",
  "enabled": true,
  "priority": 200,
  "matchAny": [
    { "type": "targetPath", "pattern": "**\\\\chrome.exe", "patternType": "glob" },
    { "type": "targetPath", "pattern": "**\\\\msedge.exe", "patternType": "glob" }
  ],
  "action": "allow"
}

Matcher Evaluation Semantics ​

  • Logical AND (matchAll): All matchers must evaluate to true.
  • Logical OR (matchAny): At least one matcher must evaluate to true.
  • Lists are flat: a matcher list contains matchers only. Nested groups are not supported on any reader; a group object inside a list decodes as a matcher that never matches.
  • Rule: a rule carries matchAll or matchAny, not both; or it names one executable directly with the targetPath shorthand. A rule with none of the three matches nothing.
  • Exclusions (matchNone): a rule applies when its positive side matches and no entry in matchNone matches. Any single entry vetoes the rule. Requires "schemaVersion": 2; a document that carries it without declaring that version is refused. See: Matchers & Patterns — Exclusions
  • An exclusion scopes one rule; it does not block an application. An excluded app is still authorized by any other matching rule — deny-override is what blocks a launch, and it records which rule blocked it.
  • Where matchNone does not fit (an exclusion about part of one field's value), regex constructs such as an anchored negative lookahead remain available; prefer readable positive matches.
  • When multiple allow policies match, the deciding allow is the highest priority, ties to the smallest id; modifications layer in contributor order. See: Merging & Precedence
  • For detailed guidance and examples (boolean logic semantics and matchAll/matchAny), see: Matchers & Patterns (boolean logic semantics)
  • Publisher certificate matching: specify the certificate field via the optional field on publisherCertificate (thumbprint, subjectCN, issuerCN, subjectDN, issuerDN). See: Matchers & Patterns (publisherCertificate)

Additional Matcher Examples ​

Example (OR across items):

json
{
  "id": "allow-putty-suite",
  "displayName": "Allow PuTTY Suite",
  "enabled": true,
  "priority": 200,
  "matchAny": [
    { "type": "targetPath", "pattern": ".*\\\\putty\\.exe$", "patternType": "regex" },
    { "type": "targetPath", "pattern": ".*\\\\psftp\\.exe$", "patternType": "regex" },
    { "type": "targetPath", "pattern": ".*\\\\pageant\\.exe$", "patternType": "regex" },
    { "type": "targetPath", "pattern": ".*\\\\puttygen\\.exe$", "patternType": "regex" }
  ],
  "action": "allow"
}

Contextual Authorization (ABAC) ​

Proposed — not enforced on either platform today

apps[].authorization (ABAC requirements and approval gating), apps[].identityRequirements, configuration.identity, configuration.security.hostAttestation and the approval workflows under configuration.launch.runtime.approval describe the intended model. No shipped reader — the Windows client, the macOS daemon, or the macOS launcher — evaluates them. They are accepted and ignored, so a launch they would have blocked is not blocked. Authorization today is the matcher-based allowlist above.

Augment allow policies with attribute- and context-based constraints. Attributes come from configuration.identity.claimsMapping and are referenced by normalized keys. Context may include geo and host posture (derived from configuration.security.hostAttestation).

Example

json
{
  "apps": [
    {
      "id": "itar-engineering-suite",
      "displayName": "ITAR Engineering Suite",
      "enabled": true,
      "priority": 300,
      "matchAll": [
        { "type": "targetPath", "pattern": "**\\\\itarsuite.exe", "patternType": "glob" }
      ],
      "action": "allow",
      "authorization": {
        "requirements": {
          "userAttributes": [
            { "attribute": "usPersonStatus", "allowedValues": ["verified"] }
          ],
          "contextConstraints": {
            "allowedGeos": ["US"],
            "requireCompliantHost": true
          }
        }
      }
    }
  ]
}

Notes

  • userAttributes.attribute must reference a key defined under configuration.identity.claimsMapping (for example, "usPersonStatus": "ext.usPersonVerified").
  • requireCompliantHost relies on host posture signaled by configuration.security.hostAttestation (mode: "audit" or mode: "enforce"). When posture is non-compliant and enforce semantics apply, the launch is denied.
  • ABAC complements the allowlist matcher model; an allow policy must still match the executable or its shortcut.

Evaluation order

    1. A matching enabled policy with action: "allow" must succeed.
    1. apps[].authorization.requirements are evaluated (userAttributes and contextConstraints). Any failure denies launch (fail-closed under enforce modes).
    1. If apps[].authorization.approval.mode is configured (for example, "required"), an approval workflow must succeed before appLaunch is allowed. Approval workflows are defined under configuration.launch.runtime.approval and referenced by authorization.approval.workflowRef.
    1. If both allow and deny policies match, deny takes precedence. See: Deny vs Allow precedence
  • Workspace/profile scoping remains unchanged; ABAC is additive to existing scope filters.

Approval-Gated Applications ​

Use apps[].authorization.approval when you want an application to be discoverable and visible, but not automatically approved for use. Instead, a launch into the Secure Sandbox runtime triggers an approval workflow and generates audit events.

Example (approval required before launch):

json
{
  "apps": [
    {
      "id": "sensitive-engineering-tools",
      "displayName": "Sensitive Engineering Tools",
      "enabled": true,
      "priority": 400,
      "matchAll": [
        { "type": "targetPath", "pattern": "C:\\\\Tools\\\\Sensitive\\\\**.exe", "patternType": "glob" }
      ],
      "action": "allow",
      "authorization": {
        "requirements": {
          "userAttributes": [
            { "attribute": "usPersonStatus", "allowedValues": ["verified"] }
          ]
        },
        "approval": {
          "mode": "required",
          "workflowRef": "manager-approval-app-launch",
          "reuse": {
            "policy": "perUserPerApp",
            "ttlSeconds": 86400
          }
        }
      }
    }
  ]
}

Semantics

  • The app is still governed by the allowlist model and ABAC checks.
  • When a user selects the app in Applications and attempts to launch, the runtime evaluates authorization.approval:
    • If mode: "required" and no valid approval token exists under the configured reuse rules, the client triggers the configured workflow (for example, manager approval) and blocks launch until a decision is recorded.
    • On approval, a appLaunch authorization event is emitted and the app launches in the Secure Sandbox runtime.
    • On rejection or timeout, launch remains denied.
  • Use authorization.approval.operations[] for future in-app operations that should also be gated by workflows (for example, appOperation.crm.exportSensitiveData).

See Also ​

Visibility ​

Visibility controls UI presence only, and it is the deciding allow rule's visibility that applies (the matching allow with the highest priority, ties to the smallest id). A lower-priority allow marked hidden does not hide an app that a higher-priority allow shows.

  • visibility: "visible" (default) — the app appears in the Applications tab.
  • visibility: "hidden" — the app is not shown in the Applications but may still be used via file associations (e.g., Open With, default handlers) when referenced by file association rules.
  • An unknown visibility value refuses the document, like an unknown action.

visibility is applied by the Windows client and the macOS launcher; the macOS daemon accepts and ignores it.

Target-Based Visibility (Sites) ​

In addition to the visibility field, allow and modify rules can be scoped to specific user-selected target sites (infrastructure or region) via visibilityConstraints.siteRefs. When Sites are enabled and the user selects a site, only rules whose siteRefs include that site (or have no site constraint) contribute; an app with no eligible allow at the selected site is not visible or launchable there. A deny rule is never scoped by siteRefs — it denies at every site.

See: Sites

Hidden example (used only by file associations):

json
{
  "id": "ms-word",
  "displayName": "Microsoft Word",
  "enabled": true,
  "priority": 200,
  "visibility": "hidden",
  "matchAll": [
    { "type": "targetPath", "pattern": ".*WINWORD\\.EXE$", "patternType": "regex" }
  ],
  "action": "allow"
}

Related (Windows)

If an app includes configurationTemplates (e.g., apps[].configurationTemplates: ["template-id"]), user configurations derived from those templates will appear in the app’s context menu. Authorization still applies: the app must be discoverable and allowed by at least one enabled action: "allow" policy. Template validation enforces enterprise constraints on user inputs. See: Configuration Templates

Policy Priority ​

When multiple enabled allow policies match the same executable, the one with the highest priority is the deciding rule; if priorities tie, the smallest policy id (ordinal, case-insensitive) decides. priority defaults to 500 when omitted.

  • Authorization: any matching allow policy authorizes the launch (unless a deny also matches).
  • Visibility: the deciding allow's visibility is the one shown in Applications.
  • Modifications: every matching allow and modify rule contributes, layered so the deciding rule is applied last. See Merging & Precedence.

Hidden Applications and File Associations ​

Policies with visibility: "hidden" are still eligible as handlers via fileAssociations:

  • Hidden apps can appear in Open With lists if the association entry sets showInOpenWith: true.
  • Default handlers will be selected even if the app is hidden, provided security gating passes (the referenced app policy must be enabled and match).

Example (hidden apps referenced by centralized file associations):

json
{
  "fileTypes": [
    {
      "id": "word-docs",
      "displayName": "Word Documents",
      "match": { "extensions": ["doc", "docx"] }
    }
  ],
  "apps": [
    {
      "id": "ms-word",
      "displayName": "Microsoft Word",
      "enabled": true,
      "priority": 200,
      "visibility": "hidden",
      "matchAll": [
        { "type": "targetPath", "pattern": ".*WINWORD\\.EXE$", "patternType": "regex" }
      ],
      "action": "allow",
      "capabilities": [
        {
          "fileTypeRef": "word-docs",
          "verbs": { "open": { "arguments": "\"%1\"" } }
        }
      ]
    }
  ],
  "fileAssociations": [
    {
      "id": "word-docs-routing",
      "displayName": "Word docs",
      "enabled": true,
      "priority": 300,
      "fileTypeRef": "word-docs",
      "actions": [
        { "verb": "open", "displayName": "Open", "appRef": "ms-word", "default": true, "showInOpenWith": true }
      ]
    }
  ]
}

Discovery Scope Reminder ​

Authorization and visibility apply only to applications the Launcher discovers.

  • Windows: executables reachable via shortcuts in the Start Menu (All Users and Current User; recursive) and the Desktop (Current User; top-level only). Executables without shortcuts in scope are not discoverable or launchable — create a shortcut, then author a policy that matches it (for example, via targetPath).
  • macOS: application bundles known to LaunchServices and Homebrew, plus command-line tools named by a rule's targetPath matcher. The daemon additionally refuses a fixed set of platform-unsupported apps regardless of policy; see Limitations & Scope.

Scope

For end-to-end guidance on what is and is not governed by Launcher policy, see: Limitations & Scope.

Next Steps ​

Turbo.net © 2025