Models

PolicyEntry

object

Single policy entry. Both subjects and resources are optional — they default to empty when absent. An entry may define references to inherit subjects, resources, and namespaces from other entries (local or imported).

subjectsSubjects

A SubjectEntry defines who is addressed.

Show child attributes

nginx:subjectId1SubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes

typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes

beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes

labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example

{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}

randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example

{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}

Example

{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}

nginx:subjectIdNSubjectEntry

Single (Authorization) Subject entry holding its type.

Show child attributes

typestringrequired

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

expirystring<date-time>

The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes

beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes

labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example

{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}

randomizationIntervalstring5m

Example

{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}

Example

{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}

resourcesResources

(Authorization) Resources containing one ResourceEntry for each type:path key, type being one of the following thing, policy, message.

Show child attributes

[key: string]ResourceEntry

Single (Authorization) Resource entry defining permissions per effect. Allowed effects are grant and revoke.

Show child attributes

grantArray<Permission>READWRITE

revokeArray<Permission>READWRITE

Example

{
  "thing:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "thing:/attributes/some/path": {
    "grant": null,
    "revoke": [
      "READ"
    ]
  },
  "policy:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  },
  "message:/": {
    "grant": [
      "READ",
      "WRITE"
    ],
    "revoke": null
  }
}

namespacesArray<string>

Restricts this policy entry to things whose namespace matches at least one pattern. If omitted or empty, the entry applies to all namespaces.

com.acme matches only that exact namespace
com.acme.* matches namespaces below com.acme, but not com.acme itself

Example

[
  "com.acme",
  "com.acme.*"
]

importableImportableimplicitexplicitneverimplicit

Controls the import behavior of this policy entry i.e. whether this policy entry is implicitly, explicitly or never imported when referenced from another policy.

implicit (default): the policy entry is imported without being listed in the importing policy individually
explicit: the policy entry is only imported if it is listed in the importing policy
never: the policy entry is not imported, regardless of being listed in the importing policy If the field is not specified, default value is implicit.

Example

explicit

allowedAdditionsArray<string>subjectsresourcesnamespaces

Defines which types of additions are allowed when this entry is referenced by other entries via references.

Semantics:

Field absent (omitted) — no restriction; the referencing entry's own subjects, resources, and namespaces are merged in as usual. This is the upgrade-friendly default.
Field present and empty ([]) — no additions allowed; only the referenced entry's content is effective.
Field present with values — only the listed kinds of additions survive on the referencing entry.

This field is enforced as a runtime filter, not as a write-time policy contract: a referencing entry that declares own subjects/resources/namespaces not permitted here can still be persisted, but the disallowed own additions are silently stripped at enforcement time. The same filter applies whether the reference is local (within the same policy) or an import reference.

subjects — allows referencing entries to add additional subjects on top of this entry
resources — allows referencing entries to add additional resources on top of this entry
namespaces — allows referencing entries to add additional namespace patterns on top of this entry

Example

[
  "subjects"
]

referencesArray<object>

An optional list of references to other policy entries. Each reference points to an entry either in the same policy (local reference) or in an imported policy (import reference). When set, subjects, resources, and namespaces from the referenced entries are additively merged into this entry.

Import reference: contains both entry (the label) and import (the policy ID of the imported policy)
Local reference: contains only entry (the label of another entry in the same policy)

Show child attributes

A single reference to a policy entry.

entrystringrequired

The label of the referenced entry.

importstring

The ID of the imported policy this reference points to. If absent, the reference points to a local entry within the same policy.

Example

{
  "subjects": {
    "nginx:subjectId1": {
      "type": "This is some description for this subject, adjust as needed.",
      "expiry": "2020-12-07T11:36:40Z",
      "announcement": {
        "beforeExpiry": "5m",
        "whenDeleted": true
      }
    },
    "nginx:subjectIdN": {
      "type": "This is some description for this subject, adjust as needed.",
      "expiry": "2020-12-07T11:36:40Z",
      "announcement": {
        "beforeExpiry": "5m",
        "whenDeleted": true
      }
    }
  },
  "resources": {
    "thing:/": {
      "grant": [
        "READ",
        "WRITE"
      ],
      "revoke": null
    },
    "thing:/attributes/some/path": {
      "grant": null,
      "revoke": [
        "READ"
      ]
    },
    "policy:/": {
      "grant": [
        "READ",
        "WRITE"
      ],
      "revoke": null
    },
    "message:/": {
      "grant": [
        "READ",
        "WRITE"
      ],
      "revoke": null
    }
  },
  "namespaces": [
    "com.acme",
    "com.acme.*"
  ],
  "importable": "explicit",
  "allowedAdditions": [
    "subjects"
  ],
  "references": [
    {
      "entry": "operator",
      "import": "energy-corp:power-plant-roles"
    },
    {
      "entry": "local-admin"
    }
  ]
}

Docs by Sourcey