From 488e63979e07542a49478a705ae7b32c52be16e9 Mon Sep 17 00:00:00 2001 From: Brad Fitzpatrick Date: Wed, 27 Apr 2022 15:51:59 -0700 Subject: [PATCH] api.md: document new ACL validate mode Updates tailscale/corp#4932 Change-Id: Ie176ee79595c3b56d3376f1d81a441f9272e6ed4 Signed-off-by: Brad Fitzpatrick --- api.md | 38 +++++++++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/api.md b/api.md index 94f0a7464..f6ae8335d 100644 --- a/api.md +++ b/api.md @@ -24,7 +24,7 @@ Currently based on {some authentication method}. Visit the [admin panel](https:/ - [GET tailnet ACL](#tailnet-acl-get) - [POST tailnet ACL](#tailnet-acl-post): set ACL for a tailnet - [POST tailnet ACL preview](#tailnet-acl-preview-post): preview rule matches on an ACL for a resource - - [POST tailnet ACL validate](#tailnet-acl-validate-post): run validation tests against the tailnet's existing ACL + - [POST tailnet ACL validate](#tailnet-acl-validate-post): run validation tests against a new or existing ACL - [Devices](#tailnet-devices) - [GET tailnet devices](#tailnet-devices-get) - [Keys](#tailnet-keys) @@ -620,7 +620,12 @@ Response: #### `POST /api/v2/tailnet/:tailnet/acl/validate` - run validation tests against the tailnet's active ACL -Runs the provided ACL tests against the tailnet's existing ACL. This endpoint does not modify the ACL in any way. +This endpoint works in one of two modes: + +1. with a request body that's a JSON array, the body is interpreted as ACL tests to run against the domain's current ACLs. +2. with a request body that's a JSON object, the body is interpreted as a hypothetical new JSON (HuJSON) body with new ACLs, including any tests. + +In either case, this endpoint does not modify the ACL in any way. ##### Parameters @@ -630,7 +635,7 @@ The POST body should be a JSON formatted array of ACL Tests. See https://tailscale.com/kb/1018/acls for more information on the format of ACL tests. -##### Example +##### Example with tests ``` POST /api/v2/tailnet/example.com/acl/validate curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \ @@ -641,11 +646,28 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \ ]' ``` -Response: -If all the tests pass, the response will be empty, with an http status code of 200. +##### Example with an ACL body +``` +POST /api/v2/tailnet/example.com/acl/validate +curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \ + -u "tskey-yourapikey123:" \ + --data-binary ' + { + "ACLs": [ + { "Action": "accept", "src": ["100.105.106.107"], "dst": ["1.2.3.4:*"] }, + ], + "Tests", [ + {"src": "100.105.106.107", "allow": ["1.2.3.4:80"]} + ], + }' +``` + +Response: + +The HTTP status code will be 200 if the request was well formed and there were no server errors, even in the case of failing tests or an invalid ACL. Look at the response body to determine whether there was a problem within your ACL or tests. + +If there's a problem, the response body will be a JSON object with a non-empty `message` property and optionally additional details in `data`: -Failed test error response: -A 400 http status code and the errors in the response body. ``` { "message":"test(s) failed", @@ -658,6 +680,8 @@ A 400 http status code and the errors in the response body. } ``` +An empty body or a JSON object with no `message` is returned on success. + ### Devices