FoxIDs Control API

Control API e una REST API con descrizione dell'interfaccia online Swagger (OpenAPI) e Swagger UI.

Se ospiti FoxIDs in self-hosting, il documento Swagger (OpenAPI) e disponibile in FoxIDs Control su .../api/swagger/v2/swagger.json e Swagger UI su .../api/swagger.

Riferimento API

Swagger descrive route, parametri, schemi di request e response e codici di stato correnti esatti.

• Swagger (OpenAPI) JSON
• Swagger UI

Guide alle risorse

Le guide alle risorse spiegano come combinare in modo sicuro le operazioni correlate. Includono flussi di lavoro, esempi, considerazioni sulla sicurezza ed effetti collaterali notevoli senza duplicare il contratto OpenAPI completo.

struttura Tenant

• Tenant amministrazione
• Ambienti

Configurazione

• Applicazioni e metodi di autenticazione

Utenti e accesso

• Utenti e registrazioni all'app di autenticazione

Operazioni

• Log, controllo e utilizzo

Terminologia e struttura degli endpoint

Nomenclatura Control API:

• Un ambiente viene chiamato track
• Una registrazione applicativa viene chiamata downparty
• Un metodo di autenticazione viene chiamato upparty

L'URL di Control API contiene variabili per il nome tenant e il nome track, cioe il nome ambiente, su cui vuoi operare: .../{tenant_name}/{track_name}/.... Sostituisci {tenant_name} con il nome del tenant e {track_name} con il nome tecnico dell'ambiente. Se generi un proxy dal documento Swagger (OpenAPI), queste variabili vengono fornite come parametri di input.

Ad esempio, per leggere una registrazione applicativa OpenID Connect su FoxIDs Cloud con nome tecnico some_oidc_app, chiama con HTTP GET https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app, sostituendo le variabili con il nome tenant e il nome tecnico dell'ambiente.

Autenticazione

Puoi chiamare Control API sia come servizio o daemon usando un client OAuth 2.0 con client credentials, sia nel contesto di un utente tramite un client OpenID Connect.

I passaggi seguenti creano un client OAuth 2.0 e gli concedono diritti di accesso di livello amministrativo tramite scope e ruoli.

Crea un client OAuth 2.0 in FoxIDs Control Client:

1. Seleziona l'ambiente master nell'intestazione.
2. Seleziona la scheda Applications.
3. Fai clic su New Application.
4. Fai clic su Backend Application.
   1. Aggiungi un Name, ad esempio My API Client.
   2. Fai clic su Register.
   3. Copia Client ID e Client secret.
   4. Fai clic su Close.
5. Fai clic sulla registrazione client nell'elenco per aprirla.
6. Nella sezione Resource and scopes, che concede al client accesso al tuo tenant:
   1. Fai clic su Add Resource and scope e aggiungi la resource foxids_control_api.
   2. Fai clic su Add Scope e aggiungi lo scope foxids:tenant.
7. Seleziona Show advanced.
8. Nella sezione Issue claims, che concede al client il ruolo amministratore tenant:
   1. Fai clic su Add Claim e aggiungi il claim role.
   2. Fai clic su Add Value e aggiungi il valore claim foxids:tenant.admin.
9. Fai clic su Update.

Quindi esegui una richiesta OAuth 2.0 Client Credentials Grant per ottenere un access token per Control API.

Sostituisci {tenant_name}, {track_name}, {client_id} e {client_secret}. Cambia il dominio se esegui self-hosting.

Sample Postman Questa Postman collection autentica con il client OAuth 2.0 My API Client e restituisce gli utenti per l'ambiente configurato, cioe il track.

Crea un file JSON per una Postman collection, ad esempio foxids_control_api.postman_collection.json, con il contenuto seguente. Sostituisci {tenant_name}, {track_name}, {client_id} e {client_secret}. Cambia i domini (foxids.com e control.foxids.com) se esegui self-hosting.

{
  "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"
          ]
        }
      }
    }
  ]
}

Sample richiesta HTTP Questo sample HTTP autentica come client OAuth 2.0 My API Client con il 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

Risposta token JSON:

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
}

L'access_token viene usato per chiamare Control API.

Sample codice C# Questo sample C# autentica come client OAuth 2.0 My API Client con il 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);

Quindi chiama Control API con l'access token come header Authorization Bearer, come definito dallo standard OAuth 2.0 Bearer Token (RFC 6750).

Sample codice C# Questo sample C# mostra come aggiungere l'access token a HttpClient e leggere la registrazione applicativa OpenID Connect some_oidc_app, cioe il nome tecnico.

// 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");

Diritti di accesso API

Questo mostra la configurazione di Control API nell'ambiente master di un tenant con l'insieme predefinito di scope che concede accesso ai dati del tenant.

Puoi aggiungere piu scope per estendere i diritti di accesso a Control API per ambiente e ottenere configurazioni least-privilege.

L'accesso a Control API e limitato da scope e ruoli. Esistono due famiglie di scope: foxids:master concede accesso ai dati del master tenant e foxids:tenant concede accesso ai dati del tenant. La resource di Control API foxids_control_api e definita nell'ambiente master di ciascun tenant, e gli scope configurati concedono accesso ai dati di quel tenant tramite Control API.

L'accesso di uno scope puo essere ristretto aggiungendo piu elementi separati con punti e due punti. La notazione con punto limita a un sotto-ruolo specifico e viene usata sia negli scope sia nei ruoli. I chiamanti devono presentare uno o piu scope e ruoli corrispondenti.

Ogni diritto di accesso e definito sia come scope sia come ruolo. Questo permette di concedere o limitare l'accesso sia a livello client sia a livello utente. I diritti di accesso sono gerarchici e client e utente non devono avere necessariamente scope e ruoli identici.

Il ruolo amministratore foxids:tenant.admin concede accesso a tutti i dati di un tenant e ai dati del master tenant; equivale ad avere i ruoli foxids:tenant e foxids:master.

Un client richiede uno scope specificando resource e scope separati da due punti. Ad esempio, per richiedere lo scope foxids:tenant:track:party.create, il client richiede foxids_control_api:foxids:tenant:track:party.create.

Se una richiesta viene negata per diritti di accesso insufficienti, viene registrato un trace item con i possibili scope e ruoli autorizzanti insieme agli scope e ruoli effettivi dell'utente.

Diritti di accesso tenant

I diritti di accesso tenant sono sia scope sia ruoli.

Se lo scope che ti serve non e definito in Control API foxids_control_api, puoi aggiungerlo.

:track[xxxx] specifica un ambiente tramite il nome tecnico. Ad esempio, un ambiente Test con nome tecnico hsgm7je5 e :track[hsgm7je5] e un ambiente Production con nome tecnico - e :track[-].

Diritti di accesso master tenant

I diritti di accesso del master tenant sono sia scope sia ruoli.

Documentazione correlata

• FoxIDs Control panoramica
• Tenant amministrazione
• Ambienti
• Applicazioni e metodi di autenticazione
• Utenti e registrazioni all'app di autenticazione
• Log, controllo e utilizzo