Access policy API
The access policy API exposes the policy engine: the attribute dictionary and operators that conditions use, a validator for condition lists, and a simulator that runs a synthetic request through service selection, authentication, role mapping and enforcement. It backs Access › Test access and the condition editors on Access › Access policies and Access › Enforcement profiles.
To create and change the policy objects themselves (services, role mappings, enforcement policies and profiles, authentication methods), use the Policy administration API.
Base path and permissions
Section titled “Base path and permissions”All routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. See API overview for authentication.
| Method | Path | Permission | Purpose |
|---|---|---|---|
GET |
/policy/dictionary |
policy:read |
Namespaces, attributes, types, values, operators and groups |
GET |
/policy/operators |
policy:read |
Operator catalogue and operators by attribute type |
POST |
/policy/simulate |
policy:read; policy:write when a password is sent |
Run the full policy pipeline for a synthetic request |
POST |
/policy/validate |
policy:read |
Validate a condition list against the tenant without saving |
None of these routes changes configuration. Errors use the standard envelope {"error": "...", "code": "..."} with codes bad_request, not_found, forbidden, rate_limited or internal.
Dictionary
Section titled “Dictionary”GET /policy/dictionary
Section titled “GET /policy/dictionary”Permission: policy:read
Returns every namespace and attribute a condition, an enforcement profile attribute or a %{...} variable can use.
- RADIUS dictionaries with attribute type, direction (
in,outorinout), a multi-valued flag and enum values written as"Name (N)":Radius:IETF,Radius:Aruba,Radius:Cisco,Radius:Hewlett-Packard-Enterprise,Radius:Hewlett-Packard-Enterprise-2,Radius:H3C,Radius:Extreme,Radius:Brocade,Radius:Alcatel-Lucent-Enterprise,Radius:Airespace,Radius:Microsoft,Radius:Juniper,Radius:Fortinet,Radius:Ruckus,Radius:Arista,Radius:MerakiandRadius:Tellabs. Where the RADIUS server spells an attribute differently,freeradius_namegives the name actually sent (for exampleHPE-User-Roleis sent asHP-User-Role). Rules and profiles accept either name. - Fixed namespaces:
Connection,Authentication,Endpoint,Device,Tips,Date,Certificate,GuestUser,LocalUser,TACACS,Host,ApplicationandOnboard. - Tenant-specific values:
Tips:Rolelists the tenant’s roles plus[User Authenticated]and[Machine Authenticated];Device:Device-Grouplists the device group names;Authentication:Sourcelists the directory names. Custom attributes found on devices, network devices and local users are added with"custom": true. Each directory gets anAuthorization:<directory name>namespace with its attribute aliases. - Secret attributes carry
"secret": true(for exampleTunnel-Password). Their values in enforcement profiles are encrypted at rest and masked by the API. - Pseudo attributes carry
"pseudo": trueand adescription. Airgate turns them into real reply attributes. Today:Cisco-IP-Downloadable-ACLinRadius:Cisco, where each ACE line becomesCisco-AVPair += "ip:inacl#N=<ace>". operators,operators_by_type(guidance for editors; the engine accepts any operator on any attribute),groups(device groups and MAC/IP lists), the tenanttimezoneand the supportedvariablesforms.
Attribute types: string, integer, enum, ipaddr, ipv6addr, mac, datetime, date, time (time of day), day, boolean, list, version, octets.
curl -s "$AIRGATE/api/v1/t/$TENANT/policy/dictionary" \ -H "Authorization: Bearer $TOKEN"{ "namespaces": [ {"name": "Radius:IETF", "attributes": [ {"name": "NAS-Port-Type", "type": "enum", "values": ["Ethernet (15)", "Wireless-802.11 (19)"], "direction": "in"}, {"name": "Reply-Message", "type": "string", "multi_valued": true, "direction": "out"} ]}, {"name": "Tips", "attributes": [ {"name": "Role", "type": "list", "values": ["[User Authenticated]", "[Machine Authenticated]", "[Employee]", "[Guest]"]} ]} ], "operators": [{"name": "EQUALS", "arity": "scalar", "negated": false, "description": "any value equals"}], "operators_by_type": {"ipaddr": ["IN_SUBNET", "BELONGS_TO_GROUP"]}, "groups": {"nad_groups": ["Branch Switches"], "static_host_lists": ["Printers"]}, "timezone": "UTC", "variables": ["%{Namespace:Attribute}", "%{Radius:<Vendor>:<Attribute>}", "%{Authorization:<source name>:<alias>}"]}GET /policy/operators
Section titled “GET /policy/operators”Permission: policy:read
Returns the operator catalogue (name, arity, negated, description) and operators_by_type.
{"operators": [{"name": "IN_RANGE", "arity": "range", "negated": false, "description": "low <= value <= high (times of day may wrap midnight)"}], "operators_by_type": {"integer": ["EQUALS", "NOT_EQUALS", "BELONGS_TO"]}}Conditions
Section titled “Conditions”A condition has the form {"type": "<namespace>", "name": "<attribute>", "oper": "<operator>", "value": "<value>"}. A list of conditions is combined with a match_type of AND or OR. An empty list is true.
| Operator | True when (the attribute may have several values) |
|---|---|
EQUALS / NOT_EQUALS |
any value equals / the attribute is present and no value equals |
EQUALS_IGNORE_CASE / NOT_EQUALS_IGNORE_CASE |
the same, ignoring case |
CONTAINS / NOT_CONTAINS |
the configured string is a substring of a value |
BEGINS_WITH / NOT_BEGINS_WITH, ENDS_WITH / NOT_ENDS_WITH |
prefix / suffix |
EXISTS / NOT_EXISTS |
present and not empty / absent (the value is ignored) |
BELONGS_TO / NOT_BELONGS_TO |
a value is in the list / the attribute is present and no value is |
MATCHES_ANY / NOT_MATCHES_ANY |
the attribute’s values and the list intersect / are disjoint |
MATCHES_ALL / NOT_MATCHES_ALL |
every list item is among the attribute’s values / not |
MATCHES_EXACT / NOT_MATCHES_EXACT |
the two sets are equal / differ |
BELONGS_TO_GROUP / NOT_BELONGS_TO_GROUP |
the value is in a device group or a MAC/IP list (see below) |
MATCHES_REGEX / NOT_MATCHES_REGEX |
RE2 regular expression, unanchored |
LESS_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS |
typed comparison |
IN_RANGE / NOT_IN_RANGE |
inclusive range low,high, low..high or low - high; times of day may wrap midnight (22:00,06:00) |
IN_SUBNET / NOT_IN_SUBNET |
IP address inside any of the comma-separated CIDRs or addresses |
Rules that apply to every operator:
- When the attribute is absent, every operator is false except
NOT_EXISTS, including the otherNOT_*operators. - Operator names are case-insensitive.
- A value of exactly
%{X}is replaced by the values of X. When a reference cannot be resolved, the condition is false. - List values are split on
<br>when present, otherwise on,. - Enum values compare by name (case-insensitive) or by code. MAC addresses compare in any notation; IP addresses, numbers, dates and versions compare by type (
10.1is not equal to10.10for a version attribute).
Groups. For BELONGS_TO_GROUP, attributes that describe the network device (Connection:NAD-*, Device:*, NAS-IP-Address, NAS-IPv6-Address, NAS-Identifier) refer to a device group first; every other attribute refers to a MAC/IP list (static host list) first. The value is a group name, a group ID, or a name with a prefix that forces the kind: HostList:, StaticHostList:, SHL: for a list; NadGroup:, DeviceGroup:, NDG: for a device group.
Date namespace. Computed in the tenant time zone when the request does not carry it: Day-of-Week, Time-of-Day (HH:MM:SS), Date-of-Year (YYYY-MM-DD), Day-of-Month, Month, Year, Date-Time (YYYY-MM-DD HH:MM:SS).
Validate conditions
Section titled “Validate conditions”POST /policy/validate
Section titled “POST /policy/validate”Permission: policy:read
Checks a condition list against the tenant’s current policy without saving it: operator, attribute, regular expression, CIDR, range, list and %{...} syntax; that referenced device groups and MAC/IP lists exist; and that Tips:Role names used with value operators exist. Role and group names are case-sensitive except under the *_IGNORE_CASE operators; a case-only mismatch is reported with a hint. This is the same check the policy administration API runs on every write.
| Field | Type | Meaning |
|---|---|---|
match_type |
string | AND or OR |
conditions |
array | Conditions to check, at most 1000 |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/policy/validate" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"match_type": "OR", "conditions": [ {"type": "Connection", "name": "Client-Mac-Address", "oper": "BELONGS_TO_GROUP", "value": "Nope"}, {"type": "Host", "name": "Name", "oper": "MATCHES_REGEX", "value": "("}]}'Response 200:
{"valid": false, "issues": [ {"index": 0, "field": "value", "code": "unknown_group", "message": "unknown NAD group / static host list \"Nope\""}, {"index": 1, "field": "condition", "code": "syntax", "message": "invalid regular expression: ..."}]}index is the condition’s position (-1 for an invalid match_type). code is one of syntax, template, match_type, unknown_group, unknown_nad_group, unknown_role. fail_open: true is present on unknown-object issues under a negated operator.
Simulate a request
Section titled “Simulate a request”POST /policy/simulate
Section titled “POST /policy/simulate”Permission: policy:read. With a password, policy:write.
Runs a synthetic request through service selection, username stripping, identity lookup or password verification, device and guest attribute lookup, role mapping and enforcement. It has no side effects: no service hit counters, device updates, CoA, sign-in records or events.
| Field | Type | Meaning |
|---|---|---|
protocol |
string | RADIUS (default), TACACS, WEBAUTH or APPLICATION. Any other value returns 400. |
service_id |
UUID | Force this service instead of running service selection. 404 if it is not the tenant’s. |
nad_id |
UUID | Network device of the tenant (404 otherwise). |
nad_ip |
string | Network device IP address. When it matches one of the tenant’s devices, the Device:* attributes are filled. An invalid address returns 400. |
username |
string | User name. When absent, taken from Radius:IETF:User-Name or TACACS:UserName. |
password |
string | Verify this password against the service’s directories instead of only looking the user up. |
mac |
string | Client MAC address. Fills Connection:Client-Mac-Address and its variants, and Calling-Station-Id for RADIUS. An invalid value returns 400. |
skip_identity |
boolean | Do not look the user up at all; evaluate only the attributes you supply. |
attributes |
object | {"<namespace>": {"<attribute>": value or [values]}}. Supplied attributes win over derived ones. Date:Date-Time simulates a point in time. |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/policy/simulate" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"protocol": "RADIUS", "nad_ip": "10.0.0.4", "username": "alice@contoso.com", "mac": "02-00-00-00-00-05", "attributes": {"Radius:IETF": {"NAS-Port-Type": "Wireless-802.11"}}}'Response 200:
{ "service": {"id": "6f7c...", "name": "Corp-WiFi", "type": "RADIUS"}, "authentication": {"performed": true, "verified": false, "result": "ok", "username": "alice", "source": "Contoso AD"}, "decision": { "result": "ACCEPT", "reason": "", "service_name": "Corp-WiFi", "monitor_mode": false, "auth_source": "Contoso AD", "roles": ["[Employee]", "[User Authenticated]"], "enforcement_policy": "Corp Enforcement", "profiles": ["Employee VLAN"], "radius_reply": [{"name": "Tunnel-Private-Group-Id", "op": ":=", "value": "20"}], "trace": ["Service \"Corp-WiFi\" (order 10, AND): matched", "...", "Result: ACCEPT"] }, "context": {"Authentication": {"Username": ["alice"]}, "Tips": {"Role": ["[Employee]", "[User Authenticated]"]}}}authentication.resultisok,failedorskipped. When authentication fails,erroris set,decision.resultisREJECTwith reasonauthentication failed: ..., and enforcement does not run.- When no service matches,
serviceisnullanddecision.resultisREJECTwith reasonno service matched(still200). - Secret values (for example
Tunnel-Passwordor a Wi-Fi passphrase) are returned as"********"everywhere in the decision and the context.
How a decision is made
Section titled “How a decision is made”The simulator returns the same decision the RADIUS and TACACS+ services use:
- Identity roles: roles from the user or guest account, from directory lookups, the device status (
Known,Unknown,Disabled), and the built-in roles[User Authenticated]and[Machine Authenticated]. - Role mapping (optional, set on the service):
first-applicableuses the first matching rule’s role,evaluate-alluses every matching rule’s role; when nothing matches, the default role. The result is written toTips:Role. - Enforcement policy:
first-applicableapplies the first matching rule’s profiles,evaluate-allthe union of every matching rule’s profiles; when nothing matches, the default profile. A missing policy, no match without a default profile, or a rule with no profiles is aREJECT. - Device-group filter: a profile limited to device groups applies only when the network device is in one of them.
- Merge:
DROPbeatsREJECTbeatsACCEPT. Single-valued RADIUS attributes are first-wins; multi-valued ones (Cisco-AVPair,Reply-Message,Framed-Route, any*-AVPair) are appended. An Access-Reject carries onlyReply-Message. - Monitor mode (set on the service): the decision is computed and traced, but the result is
ACCEPTwith reasonmonitor mode (enforcement result X: ...)and no reply attributes are sent.
An enforcement profile whose encrypted secret value cannot be decrypted is unusable: any decision that selects it is a REJECT with reason enforcement profile "<name>" is unusable: a sealed secret value cannot be decrypted.