FoxIDs Control API

Control API ist eine REST API mit einer online Swagger (OpenAPI) Interface Beschreibung und Swagger UI.

Wenn Sie FoxIDs self hosten, wird das Swagger (OpenAPI) Dokument in FoxIDs Control unter .../api/swagger/v2/swagger.json und Swagger UI unter .../api/swagger bereitgestellt.

API-Referenz

Swagger beschreibt die exakten Routes, Parameter, Request- und Response-Schemas sowie die aktuellen Statuscodes.

• Swagger (OpenAPI) JSON
• Swagger UI

Ressourcenhandbücher

Ressourcenleitfäden erklären, wie verwandte Vorgänge sicher kombiniert werden können. Sie umfassen Arbeitsabläufe, Beispiele, Sicherheitsüberlegungen und bemerkenswerte Nebenwirkungen, ohne den vollständigen OpenAPI-Vertrag zu duplizieren.

Tenant-Struktur

• Tenant Verwaltung
• Umgebungen

Konfiguration

• Anwendungen und Authentifizierungsmethoden

Benutzer und Zugriff

• Benutzer und Authentifizierungs-App-Registrierungen

Operationen

• Protokolle, Audit und Nutzung

Terminologie und Endpoint-Struktur

Control API Benennung:

• Eine Umgebung heißt track
• Eine Anwendungsregistrierung heißt downparty
• Eine Authentifizierungsmethode heißt upparty

Die Control API URL enthält Variablen für den Tenant Namen und den Track Namen (Umgebungsname), den Sie bearbeiten möchten: .../{tenant_name}/{track_name}/.... Ersetzen Sie {tenant_name} durch Ihren Tenant Namen und {track_name} durch den technischen Umgebungsnamen. Wenn Sie einen Proxy aus dem Swagger (OpenAPI) Dokument generieren, werden diese Variablen als Eingabeparameter bereitgestellt.

Zum Beispiel, um eine OpenID Connect Anwendungsregistrierung in FoxIDs Cloud mit dem technischen Namen some_oidc_app zu lesen, rufen Sie (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app auf (ersetzen Sie die Variablen mit Ihrem Tenant Namen und technischen Umgebungsnamen).

Authentifizierung

Sie können Control API entweder als Service Daemon mit einem OAuth 2.0 Client (Client Credentials) oder im Kontext eines Benutzers über einen OpenID Connect Client aufrufen.

Die folgenden Schritte erstellen einen OAuth 2.0 Client und gewähren ihm Admin Level Access Rights über Scopes und Rollen.

OAuth 2.0 Client im FoxIDs Control Client erstellen:

1. master Umgebung auswählen (im Header).
2. Tab Applications auswählen.
3. New Application klicken.
4. Backend Application klicken.
   1. Name hinzufügen z. B. My API Client.
   2. Register klicken.
   3. Client ID und Client secret kopieren.
   4. Close klicken.
5. Ihre Client Registrierung in der Liste anklicken, um sie zu öffnen.
6. Im Abschnitt Resource and scopes - gewährt dem Client Zugriff auf Ihren Tenant:
   1. Add Resource and scope klicken und die Resource foxids_control_api hinzufügen.
   2. Add Scope klicken und das Scope foxids:tenant hinzufügen.
7. Show advanced auswählen.
8. Im Abschnitt Issue claims - gewährt dem Client die Tenant Administrator Rolle:
   1. Add Claim klicken und Claim role hinzufügen.
   2. Add Value klicken und Claim Wert foxids:tenant.admin hinzufügen.
9. Update klicken.

Führen Sie anschließend eine OAuth 2.0 Client Credentials Grant Anfrage durch, um ein Access Token für Control API zu erhalten.

Ersetzen Sie {tenant_name}, {track_name}, {client_id} und {client_secret}. Ändern Sie die Domain, wenn Sie self hosten.

Postman sample Diese Postman Collection authentifiziert sich mit dem OAuth 2.0 Client My API Client und gibt die Benutzer für die konfigurierte Umgebung (track) zurück.

Erstellen Sie eine Postman Collection JSON Datei, z. B. foxids_control_api.postman_collection.json, mit dem folgenden Inhalt. Ersetzen Sie {tenant_name}, {track_name}, {client_id} und {client_secret}. Ändern Sie die Domains (foxids.com und control.foxids.com), wenn Sie self hosten.

{
  "info": {
    "name": "FoxIDs API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "GET users",
      "request": {
        "auth": {
          "type": "oauth2",
          "oauth2": [
            {
              "key": "accessTokenUrl",
              "value": "https://foxids.com/{tenant_name}/master/{client_id}/(*)/oauth/token",
              "type": "string"
            },
            {
              "key": "clientSecret",
              "value": "{client_secret}",
              "type": "string"
            },
            {
              "key": "clientId",
              "value": "{client_id}",
              "type": "string"
            },
            {
              "key": "tokenName",
              "value": "api_access_token",
              "type": "string"
            },
            {
              "key": "client_authentication",
              "value": "body",
              "type": "string"
            },
            {
              "key": "scope",
              "value": "foxids_control_api:foxids:tenant",
              "type": "string"
            },
            {
              "key": "grant_type",
              "value": "client_credentials",
              "type": "string"
            },
            {
              "key": "addTokenTo",
              "value": "header",
              "type": "string"
            }
          ]
        },
        "method": "GET",
        "header": [],
        "url": {
          "protocol": "https",
          "host": [
            "control.foxids.com"
          ],
          "port": "443",
          "path": [
            "api",
            "{tenant_name}",
            "{track_name}",
            "!users"
          ]
        }
      }
    }
  ]
}

HTTP request sample Dieses HTTP Sample authentifiziert sich als OAuth 2.0 Client My API Client mit dem Client Credentials Grant.

POST https://foxids.com/{tenant_name}/master/{client_id}(*)/oauth/token HTTP/1.1
Host: foxids.com
Content-Type: application/x-www-form-urlencoded

client_id={client_id}
&client_secret={client_secret}
&grant_type=client_credentials
&scope=foxids_control_api%3Afoxids%3Atenant

Token JSON response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
    "access_token":"eyJhGfjlc...nNjH3iIWvMdCM",
    "token_type":"Bearer",
    "expires_in":3600
}

Das access_token wird verwendet, um Control API aufzurufen.

C# code sample Dieses C# Sample authentifiziert sich als OAuth 2.0 Client My API Client mit dem Client Credentials Grant.

// NuGet package: ITfoxtec.Identity
using ITfoxtec.Identity.Helpers;

var oidcDiscoveryUrl = "https://foxids.com/{tenant_name}/master/{client_id}(*)/.well-known/openid-configuration";
// Inject IHttpClientFactory httpClientFactory
var oidcDiscovery = new OidcDiscoveryHandler(httpClientFactory, oidcDiscoveryUrl);

// Inject IHttpClientFactory httpClientFactory
var tokenHelper = new TokenHelper(httpClientFactory, oidcDiscovery);

var clientId = "{client_id}";
var clientSecret = "{client_secret}";
var scope = "foxids_control_api:foxids:tenant";
(var accessToken, var expiresIn) = await tokenHelper.GetAccessTokenWithClientCredentialGrantAsync(clientId, clientSecret, scope);

Rufen Sie anschließend Control API mit dem Access Token als Authorization Bearer Header auf, wie in OAuth 2.0 Bearer Token (RFC 6750) definiert.

C# code sample Dieses C# Sample zeigt, wie das Access Token zum HttpClient hinzugefügt wird und die OpenID Connect Anwendungsregistrierung some_oidc_app (technischer Name) gelesen wird.

// NuGet package: ITfoxtec.Identity
using ITfoxtec.Identity;

// Inject IHttpClientFactory httpClientFactory
var httpClient = httpClientFactory.CreateClient();
// Add the access token
httpClient.SetAuthorizationHeaderBearer(accessToken);

// Call Control API using the httpClient
// E.g. read a OpenID Connect application registration
using var response = await httpClient.GetAsync("https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app");

API access rights

Dies zeigt die Control API Konfiguration in einer Tenant Master Umgebung mit dem default Satz an Scopes, die Zugriff auf Tenant Daten gewähren.

Sie können weitere Scopes hinzufügen, um Control API Zugriffsrechte pro Umgebung zu erweitern und Least Privilege Konfigurationen zu erreichen.

Der Zugriff auf Control API ist durch Scopes und Rollen eingeschränkt. Es gibt zwei Scope Familien: foxids:master gewährt Zugriff auf Master Tenant Daten und foxids:tenant gewährt Zugriff auf Tenant Daten. Die Control API Resource foxids_control_api ist in jeder Tenant Master Umgebung definiert, und die konfigurierten Scopes gewähren Zugriff auf die Tenant Daten über Control API.

Der Zugriff eines Scopes kann durch Hinzufügen weiterer Elemente getrennt mit Semikolons und Punkten eingeschränkt werden. Punkt Notation begrenzt auf eine spezifische Sub Rolle und wird sowohl in Scopes als auch Rollen verwendet. Aufrufer müssen einen oder mehrere passende Scopes und Rollen präsentieren.

Jedes Zugriffsrecht ist sowohl als Scope als auch als Rolle definiert. Dadurch können Sie Zugriff auf Client und Benutzer Ebene gewähren oder einschränken. Zugriffsrechte sind hierarchisch, und Client und Benutzer benötigen keine passenden Scopes und Rollen.

Die Administrator Rolle foxids:tenant.admin gewährt Zugriff auf alle Daten in einem Tenant und die Master Tenant Daten; sie entspricht den Rollen foxids:tenant und foxids:master.

Ein Client fordert ein Scope an, indem er Resource und Scope durch ein Semikolon trennt. Zum Beispiel fordert der Client für das Scope foxids:tenant:track:party.create den Wert foxids_control_api:foxids:tenant:track:party.create an.

Wenn eine Anfrage wegen unzureichender Zugriffsrechte abgelehnt wird, wird ein Trace Item mit den möglichen autorisierenden Scopes und Rollen sowie den tatsächlichen Scopes und Rollen des Benutzers protokolliert.

Tenant access rights

Tenant Zugriffsrechte sind sowohl Scopes als auch Rollen.

Wenn das benötigte Scope auf der Control API foxids_control_api nicht definiert ist, können Sie es hinzufügen.

:track[xxxx] gibt eine Umgebung anhand des technischen Namens an. z. B. eine Test Umgebung mit dem technischen Namen hsgm7je5 ist :track[hsgm7je5] und eine Production Umgebung mit dem technischen Namen - ist :track[-].

Master tenant access rights

Master Tenant Zugriffsrechte sind sowohl Scopes als auch Rollen.

Zugehörige Dokumentation

• FoxIDs Control Übersicht
• Tenant Verwaltung
• Umgebungen
• Anwendungen und Authentifizierungsmethoden
• Benutzer und Authentifizierungs-App-Registrierungen
• Protokolle, Audit und Nutzung