Skip to main content

Domain Policy

Where read-context policy and write-context policy affect how data is handled and transformed, domain policy affects who are permitted to do what within Antimatter.

The general flow for controlling user permissions is

  1. Define capabilities (see Capabilities) that serve as a set of roles and attributes that normalize different sources of principals into a common form
  2. Add those capabilities to principals in the Identity Provider config (see Identity Providers)
  3. Define domain policy rules that define what those capabilities allow principals to do

Domain policy rules always reference:

  • The path that summarizes the operation (this is usually the same as API URL of the operation, or is a prefix of that URL)
  • The operation, one of View, Edit or Use
  • The result of the rule, either Allow or Deny
  • The priority of the rule, which determines if it evaluated before or after other rules (the first matching rule applies)

In addition, a domain policy can reference:

  • The capabilities of the subject (e.g. to determine between an admin and a guest)
  • A fact with arguments that in turn reference either literals or capabilities of the requesting subject.

Path​

The path in a rule is a glob expression that matches against an API operation. To see a list of all possible paths that you can reference in rules, use the "list resources" operation:

import antimatter as am
amr = am.Session.from_api_key(domain_id="dm-xxxxxxxx", api_key="xxxxxxxxx")

amr.list_resources()

Which returns

[
    {'resource': '/peer-domain',
     'operations': ['edit', 'view'],
     'placeholder_values': {},
     'description': 'Create or view a domain that is a peer of the current domain.'},
    {'resource': '/control/write-context',
     'operations': ['view'],
     'placeholder_values': {},
     'description': 'List the domain write contexts.'},
    {'resource': '/control/write-context/{contextName}',
     'operations': ['view', 'edit', 'use'],
     'placeholder_values': {'contextName': []},
     'description': 'Interact with a specific write context.'},
    {'resource': '/control/read-context',
     'operations': ['view'],
     'placeholder_values': {},
     'description': 'List the domain read contexts.'},
    {'resource': '/control/read-context/{contextName}',
     'operations': ['view', 'edit', 'use'],
     'placeholder_values': {'contextName': []},
     'description': 'Interact with a specific read context.'},
    {'resource': '/control/identities',
     'operations': ['view'],
     'placeholder_values': {},
     'description': "Get a summary of the domain's Identity Providers."},
    {'resource': '/control/identities/{identityProviderName}',
     'operations': ['view', 'edit'],
     'placeholder_values': {'identityProviderName': ['apikey']},
     'description': 'Create, configure or view an identity provider.'},
    {'resource': '/capsules',
     'operations': ['view'],
     'placeholder_values': {},
     'description': 'View the capsule list'},
    {'resource': '/control/facts',
     'operations': ['view'],
     'placeholder_values': {},
     'description': 'Get a list of the registered fact types in this domain.'},
    {'resource': '/control/peers',
     'operations': ['view', 'edit'],
     'placeholder_values': {},
     'description': 'Returns a list of this domains peers.'},
    {'resource': '/hooks',
     'operations': ['view'],
     'placeholder_values': {},
     'description': 'Get a list of available hooks in this domain.'},
    {'resource': '/hooks/data-tagging/{hookName}',
     'operations': ['use'],
     'placeholder_values': {'hookName': ['accurate-pii',
                                         'data-structure-classifier',
                                         'fast-pii',
                                         'regex-classifier']},
     'description': 'Invoke the supplied data tagging hook.'},
    {'resource': '/control/settings',
     'operations': ['view', 'edit'],
     'placeholder_values': {},
     'description': 'View or update the domain settings.'},
    {'resource': '/control/capabilities',
     'operations': ['view', 'edit'],
     'placeholder_values': {},
     'description': 'Get the domain capabilities.'},
    {'resource': '/encryption/flush',
     'operations': ['use'],
     'placeholder_values': {},
     'description': 'Flush all keys in memory.'},
    {'resource': '/control/policy',
     'operations': ['view', 'edit'],
     'placeholder_values': {},
     'description': 'View or create domain policy rules. These govern which resources in the domain can be interacted with.'}
]

For paths that have a resource identifier in them (e.g. write contexts), the list_resources endpoint will tell you all the names of the resources that can appear in that part of the URL, in case you wish to define policy rules that apply to only one of the resources. For example, if you want to allow someone to Use just a single read context, not all read contexts, you would use /control/read-context/my_read_context as the path, and use as the operation.

As an example, if you would like to create a rule that says that users with the "policy-manager" capability are able to edit and view domain policy, this would look like this (including creating the capability, but omitting assigning the capability to any principals):

import antimatter as am
amr = am.Session.from_api_key(domain_id="dm-xxxxxxxx", api_key="xxxxxxxxx")

amr.put_capability("policy-editor", summary="Policy Editors", description="Can edit/view domain policy")
amr.create_policy_rule(
    path="/control/policy",
    operation=am.Operation.Edit,
    result=am.Result.Allow,
    priority=100,
    capability_rules=am.CapabilityRulesBuilder()
        .with_rule("policy-editor", am.CapabilityOperator.Exists)
)
amr.create_policy_rule(
    path="/control/policy",
    operation=am.Operation.View,
    result=am.Result.Allow,
    priority=110,
    capability_rules=am.CapabilityRulesBuilder()
    .with_rule("policy-editor", am.CapabilityOperator.Exists)
)

Note that the path supports glob matching, so you can, for example, create a rule that matches against /control/** to refer to all API endpoints within the "control" group.

warning

There is currently no functionality in Antimatter to prevent you from defining or deleting rules that result in you "locking yourself out" of your domain. We are aware that this is not ideal and will be introducing some protection against this in a future release. If you have accidentally locked yourself out of a domain, please contact support@antimatter.io, and we can help you restore the default domain policies.

To avoid this, we recommend mostly writing "Allow" rules, and not deleting the default "admin" capability or the rules that grant it permissions.

Capability and Fact matching​

A rule can reference the existence or nonexistence of a capability for the subject making the request. For capabilities with a value, you can also match if the value is present in a list of values captured in the rule.

Fact matching allows a rule to match based on the existence or nonexistence of a fact. Facts are tuples with one or more arguments. When defining a fact rule inside a domain policy rule, you can either specify a literal for an argument, specify that it can have Any value, or specify that it must have a value that matches the value of a capability that the subject has.