Öffentliche API

Das Dashboard baut auf einer REST-API auf, und Ihre eigenen Werkzeuge können dieselbe API nutzen. Was das Dashboard mit Geräten, Gruppen, Zugriffsregeln, Netzwerken, DNS, Registrierungsschlüsseln und Mitgliedern tut, kann auch ein Skript über HTTPS tun. Es kann etwa Zugriffsregeln in der Versionsverwaltung pflegen, Gruppen aus einem Inventar befüllen, die Aktivität in ein Log-System übernehmen oder in einem Test prüfen, was ein Gerät erreichen kann.

Die Basis-URL lautet https://app.sxaccess.com, und jeder Pfad beginnt mit /api. Anfragen und Antworten verwenden JSON.

Jede Anfrage enthält ein Zugriffstoken im Header Authorization, nach dem Wort Token: Authorization: Token sxp_.... Token beginnen immer mit sxp_, sodass Secret-Scanner ein Token erkennen können, das in ein Repository oder ein Log gelangt ist.

Stellen Sie Token für ein Dienstkonto aus, nicht für eine Person. Die Automatisierung funktioniert dann weiter, wenn Personen ausscheiden, und unter Aktivität erscheint das Dienstkonto als Urheber jeder Änderung. Mitglieder, die Eigentümer, Administrator oder Netzwerkadministrator sind, können auch für sich selbst ein Token erstellen: im Kontomenü unter Profile Settings → Tokens. Dieses Token funktioniert nicht mehr, sobald das Mitglied gesperrt oder aus der Organisation entfernt wird. Ein Token handelt mit der Rolle seines Kontos und in der Organisation, in der es ausgestellt wurde; siehe Rollen.

Das Dashboard ruft dieselbe API mit der Anmeldesitzung der Person auf, die es gerade benutzt; Skripte und Werkzeuge verwenden ein Zugriffstoken. Pfade unter /api/auth/ bedienen die Anmeldeseiten und nehmen kein Token entgegen.

Jeder Aufruf wirkt in genau einer Organisation. Ein Zugriffstoken wirkt immer in der Organisation, in der es ausgestellt wurde; ein Werkzeug, das zwei Organisationen verwaltet, braucht also ein Token aus jeder. GET /api/organizations liefert die Organisation, in der ein Aufruf wirkt, als Liste mit einem Eintrag.

Eine Person, die Mitglied mehrerer Organisationen ist und die API mit ihrer Anmeldesitzung aufruft, wählt eine davon mit dem Header X-Organization-Id aus, gesetzt auf die ID der Organisation; ohne diesen Header wirkt der Aufruf in ihrer Standardorganisation. Zugriffstoken brauchen den Header nicht, und er versetzt ein Token auch nicht in eine andere Organisation. Wie Sie Organisationen anlegen und wechseln, beschreibt die Seite Organisationen.

Ein Token darf, was die Rolle seines Kontos in dieser Organisation erlaubt, und nicht mehr. Die Rolle wird bei jeder Anfrage neu gelesen; eine geänderte Rolle gilt also ab dem nächsten Aufruf. Dienstkonten dürfen unabhängig von ihrer Rolle alles in ihrer Organisation lesen; die Rolle bestimmt, was sie ändern dürfen. Die vollständige Matrix steht unter Rollen und Berechtigungen.

Die Pfade sind so geschrieben, wie die API sie nennt. Eine Sammlung beantwortet GET mit einer Liste und POST mit einem neuen Objekt; der eigene Pfad eines Objekts, etwa /api/groups/{groupId}, beantwortet GET, PUT und DELETE. Die Tabelle nennt die Ausnahmen.

• Bezeichner sind opake Zeichenketten wie p64dm3gk7ku6rc5asbde. Lesen Sie sie aus der API; zerlegen Sie sie nicht und erfinden Sie keine.
• Verweise erfolgen über IDs. Eine Zugriffsregel nennt Gruppen-IDs, keine Gruppennamen; schlagen Sie die Gruppen also zuerst nach. Eine ID, die keine Gruppe der Organisation bezeichnet, wird aus der Regel weggelassen statt abgelehnt; prüfen Sie daher, ob jede Abfrage eine Gruppe gefunden hat.
• Anfrage-Bodys werden streng geprüft. Ein Body darf auf jeder Ebene nur die Felder enthalten, die sein Schema auflistet. Jedes andere Feld wird mit 400 und einer Meldung abgelehnt, die das Feld nennt.
• PUT ersetzt. Bauen Sie den Body aus dem auf, was GET geliefert hat: Behalten Sie jedes Feld, das die Anfrage annimmt, ändern Sie die gewünschten und lassen Sie Felder weg, die die Anfrage nicht auflistet, etwa id.

Jeder Fehler hat denselben Body: {"message": "...", "code": 403, "error_code": "..."}. code wiederholt den HTTP-Status, und message ist für Menschen geschrieben. error_code steht nur dort, wo ein Client Fehler unterscheiden muss; verzweigen Sie danach, nie nach dem Text von message.

Die Beispiele laufen in einer POSIX-Shell mit curl und jq. Setzen Sie einmalig das Token und zwei Abkürzungen und prüfen Sie dann, ob das Token funktioniert; das Token stammt aus Ihrer Secret-Verwaltung. Die Prüfung gibt 200 aus, wenn das Token funktioniert, und 401, wenn es fehlt, abgelaufen oder falsch ist.

Die Liste enthält jedes Gerät der Organisation, mit seiner Tunneladresse und der Angabe, ob es gerade verbunden ist.

Aus den Zugriffsregeln abzuleiten, was ein Gerät erreichen kann, ist fehleranfällig. /api/devices/{deviceId}/reachable-devices liefert die Antwort, nachdem jede Zugriffsregel und jede Geräteanforderung ausgewertet wurde: die Geräte, mit denen sich dieses Gerät verbinden darf, und die Geräte, die sich mit ihm verbinden dürfen, einschließlich der Routing-Geräte, die seinen Datenverkehr zu Netzwerkressourcen weiterleiten. Protokolle und Ports gehören nicht zur Antwort; darüber entscheiden die Zugriffsregeln.

Setzen Sie DEVICE auf die id des Geräts aus GET /api/devices. Das zweite Beispiel endet mit einem Exit-Status ungleich null, wenn db-01 in der Antwort fehlt. Deshalb eignet sich dieser Endpunkt für Prüfungen in Tests.

Dieses Beispiel erlaubt der Gruppe Engineering, die Gruppe Production databases über TCP 5432 zu erreichen, in eine Richtung. Es braucht ein Token, dessen Rolle Zugriffsregeln ändern darf: Eigentümer, Administrator oder Netzwerkadministrator. Die Regel verweist über IDs auf Gruppen; der erste Block schlägt deshalb beide Gruppen nach und gibt ihre IDs aus. Prüfen Sie, dass keine davon leer ist: Eine ID, die keine Gruppe bezeichnet, wird aus der Regel weggelassen statt abgewiesen.

"bidirectional": false beschränkt die Regel auf eine Richtung; true erlaubt zusätzlich den Zielen, Verbindungen zu den Quellen zu öffnen. Fügen Sie source_device_requirements mit den IDs von Geräteanforderungen hinzu, um diese von den Quellen zu verlangen. Fragen Sie anschließend ab, was ein Gerät aus Engineering erreichen kann, um zu prüfen, ob die Regel tut, was Sie beabsichtigt haben.

PUT /api/organizations/{organizationId} nimmt die Einstellungen der Organisation als ein Objekt entgegen. Lesen Sie sie mit GET, ändern Sie, was Sie ändern wollen, und senden Sie das vollständige settings-Objekt zurück. Dieses Beispiel setzt die Session length für Geräte, die per Anmeldung registriert wurden (Settings → Security; sie gilt, solange Expire device sessions eingeschaltet ist), auf 12 Stunden. Es braucht das Token eines Eigentümers oder Administrators. Der erste Block liest die Organisation, in der das Token wirkt. Der zweite sendet das vollständige settings-Objekt mit einer Änderung zurück: device_login_expiration ist die Sitzungsdauer in Sekunden, 43200 also 12 Stunden.

Wenn Sie SXAccess mit Terraform verwalten, ruft der Provider dieselbe API auf. Behandeln Sie ihn also wie jeden anderen Client: mit einem eigenen Dienstkonto, einem eigenen Token und der Rolle mit den geringsten Rechten, die abdeckt, was er verwaltet. Wenn Sie Gruppen, Zugriffsregeln, Netzwerke, Routen und DNS als Code verwalten, erhalten Sie ein Review vor jeder Änderung, eine Historie danach und eine schnelle Antwort auf die Frage, was sich geändert hat, wenn etwas nicht mehr funktioniert.