FoxIDs Control API

Control API is een REST API met een online Swagger (OpenAPI) interface beschrijving en Swagger UI.

Als je FoxIDs self host, wordt het Swagger (OpenAPI) document getoond in FoxIDs Control op .../api/swagger/v2/swagger.json en de Swagger UI op .../api/swagger.

API-referentie

Swagger beschrijft de exacte routes, parameters, request- en response-schema's en actuele statuscodes.

• Swagger (OpenAPI) JSON
• Swagger UI

Hulpbronnengidsen

In de bronnengidsen wordt uitgelegd hoe u gerelateerde activiteiten veilig kunt combineren. Ze omvatten workflows, voorbeelden, beveiligingsoverwegingen en opmerkelijke bijwerkingen zonder het volledige OpenAPI-contract te dupliceren.

Tenant structuur

• Tenant administratie
• Omgevingen

Configuratie

• Toepassingen en authenticatiemethoden

Gebruikers en toegang

• Gebruikers en authenticator-app-registraties

Operaties

• Logboeken, controle en gebruik

Terminologie en endpoint-structuur

Control API naming:

• Een omgeving heet een track
• Een app registratie heet een downparty
• Een authenticatiemethode heet een upparty

De Control API URL bevat variabelen voor de tenant naam en track naam (omgeving naam) die je wilt beheren: .../{tenant_name}/{track_name}/.... Vervang {tenant_name} met je tenant naam en {track_name} met de technische omgeving naam. Als je een proxy genereert vanuit het Swagger (OpenAPI) document, worden die variabelen als input parameters aangeboden.

Bijvoorbeeld om een OpenID Connect app registratie te lezen in FoxIDs Cloud met de technische naam some_oidc_app, roep (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app aan (vervang de variabelen met je tenant naam en technische omgeving naam).

Authenticatie

Je kunt Control API aanroepen als service daemon met een OAuth 2.0 client (client credentials) of in de context van een gebruiker via een OpenID Connect client.

De stappen hieronder maken een OAuth 2.0 client aan en verlenen admin level access rights via scopes en rollen.

Maak een OAuth 2.0 client in FoxIDs Control Client:

1. Selecteer de master omgeving (in de header).
2. Selecteer de Applications tab.
3. Klik New Application.
4. Klik Backend Application.
   1. Voeg een Name toe, bijvoorbeeld My API Client.
   2. Klik Register.
   3. Kopieer Client ID en Client secret.
   4. Klik Close.
5. Klik je client registratie in de lijst om deze te openen.
6. In de Resource and scopes sectie - geeft de client toegang tot je tenant:
   1. Klik Add Resource and scope en voeg de resource foxids_control_api toe.
   2. Klik Add Scope en voeg het scope foxids:tenant toe.
7. Selecteer Show advanced.
8. In de Issue claims sectie - geeft de client de tenant administrator rol:
   1. Klik Add Claim en voeg de claim role toe.
   2. Klik Add Value en voeg de claim waarde foxids:tenant.admin toe.
9. Klik Update.

Voer daarna een OAuth 2.0 Client Credentials Grant request uit om een access token voor Control API te verkrijgen.

Vervang {tenant_name}, {track_name}, {client_id} en {client_secret}. Wijzig het domein als je self host.

Postman sample Deze Postman collection authenticeert met de OAuth 2.0 client My API Client en retourneert de gebruikers voor de geconfigureerde omgeving (track).

Maak een Postman collection JSON bestand, bijvoorbeeld foxids_control_api.postman_collection.json, met de onderstaande inhoud. Vervang {tenant_name}, {track_name}, {client_id} en {client_secret}. Wijzig de domeinen (foxids.com en control.foxids.com) als je self host.

{
  "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 Deze HTTP sample authenticeert als de OAuth 2.0 client My API Client met de 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
}

Het access_token wordt gebruikt om Control API aan te roepen.

C# code sample Deze C# sample authenticeert als de OAuth 2.0 client My API Client met de 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);

Roep daarna Control API aan met het access token als Authorization Bearer header, zoals gedefinieerd in OAuth 2.0 Bearer Token (RFC 6750).

C# code sample Deze C# sample laat zien hoe je het access token toevoegt aan de HttpClient en de OpenID Connect app registratie some_oidc_app (technische naam) leest.

// 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

Dit toont de Control API configuratie in een tenant master omgeving met de default set scopes die toegang geven tot tenant data.

Je kunt extra scopes toevoegen om Control API toegang per omgeving uit te breiden voor least privilege configuraties.

Toegang tot Control API wordt beperkt door scopes en rollen. Er zijn twee scope families: foxids:master geeft toegang tot master tenant data en foxids:tenant geeft toegang tot tenant data. De Control API resource foxids_control_api is gedefinieerd in elke tenant master omgeving, en de geconfigureerde scopes geven toegang tot de tenant data via Control API.

De toegang van een scope kan worden beperkt door extra elementen toe te voegen, gescheiden door puntkomma's en punten. Punt notatie beperkt tot een specifieke sub rol en wordt gebruikt in zowel scopes als rollen. Callers moeten één of meerdere passende scope(s) en rol(len) presenteren.

Elke toegangsrecht is zowel een scope als een rol. Dit maakt het mogelijk om toegang op client en gebruiker niveau te verlenen of te beperken. Toegangsrechten zijn hiërarchisch, en client en gebruiker hoeven geen overeenkomende scopes en rollen te hebben.

De administrator rol foxids:tenant.admin geeft toegang tot alle data in een tenant en de master tenant data; het is gelijk aan de rollen foxids:tenant en foxids:master.

Een client vraagt een scope aan door resource en scope te scheiden met een puntkomma. Bijvoorbeeld, om het scope foxids:tenant:track:party.create aan te vragen, vraagt de client foxids_control_api:foxids:tenant:track:party.create aan.

Als een request wordt geweigerd vanwege onvoldoende toegang, wordt een trace item gelogd met de mogelijke authoriserende scopes en rollen samen met de scopes en rollen van de gebruiker.

Tenant access rights

Tenant access rights zijn zowel scopes als rollen.

Als het scope dat je nodig hebt niet is gedefinieerd op Control API foxids_control_api, kun je het scope toevoegen.

:track[xxxx] specificeert een omgeving via de technische naam. Bijvoorbeeld een Test omgeving met technische naam hsgm7je5 is :track[hsgm7je5] en een Production omgeving met technische naam - is :track[-].

Master tenant access rights

Master tenant access rights zijn zowel scopes als rollen.

Gerelateerde documentatie

• FoxIDs Control overzicht
• Tenant administratie
• Omgevingen
• Toepassingen en authenticatiemethoden
• Gebruikers en authenticator-app-registraties
• Logboeken, controle en gebruik