FoxIDs Control

FoxIDs viene configurato tramite FoxIDs Control, composto da Control Client e Control API. Control Client e API sono protetti da FoxIDs e Control Client usa Control API.

Control API contiene tutta la funzionalita di configurazione. Per questo motivo e possibile automatizzare la configurazione integrandosi con Control API.

FoxIDs Control Client

Control Client e un'app Blazor WebAssembly (WASM).

Apri il tuo Control Client su FoxIDs.com.

Tenant e ambiente master

Se usi FoxIDs.com, il tuo tenant viene creato durante la registrazione.

Se distribuisci FoxIDs (self-hosted), ottieni accesso al tenant master. Crea innanzitutto un tenant che contenga la tua configurazione di sicurezza. La maggior parte delle installazioni ne richiede solo uno, ma puoi configurare un numero illimitato di tenant.

Un tenant contiene un ambiente master, dal quale viene configurato l'intero tenant. L'ambiente master contiene un repository utenti e, al momento della creazione, un solo utente amministratore.

Normalmente non dovresti modificare la configurazione dell'ambiente master o aggiungere nuovi metodi di autenticazione o registrazioni applicative, ma e possibile. Ad esempio, aggiungendo un metodo di autenticazione puoi ottenere single sign-on (SSO) verso l'ambiente master.

Creare utenti amministratori

E possibile creare piu utenti amministratori nell'ambiente master. Un utente diventa amministratore aggiungendo il ruolo amministratore foxids:tenant.admin, come mostrato sotto.

Crea un utente:

1. Apri l'ambiente master
2. Seleziona la scheda Users
3. Fai clic su Create User
4. Aggiungi le informazioni dell'utente e fai clic su Create.

Concedere accesso a un utente

L'accesso viene concesso con i ruoli. Gli scope sono necessari solo quando un client richiede un token per Control API; Control Client richiede gia lo scope necessario su foxids_control_api, quindi in genere assegni solo ruoli all'utente nell'ambiente master.

Per consentire a una persona di accedere a Control Client e vedere i dati di configurazione:

1. Crea o apri l'utente nell'ambiente master (scheda Users).
2. Aggiungi il ruolo base foxids:tenant:basic.read (necessario per consentire a Control Client di caricare profilo e strumenti di supporto).
3. Decidi cosa puo vedere l'utente:
   • Per limitare la visibilita a un ambiente, aggiungi foxids:tenant:track[vh2csjt4].read (sostituisci vh2csjt4 con il nome tecnico dell'ambiente).
   • Per consentire l'accesso a tutti gli ambienti, aggiungi foxids:tenant.read.
4. Aggiungi i ruoli operativi necessari in ciascun ambiente. Esempi: foxids:tenant:track[vh2csjt4]:user per gestire gli utenti, foxids:tenant:track[vh2csjt4]:party per gestire applicazioni e metodi di autenticazione.

Control Client vs solo API:

• Control Client (UI interattiva) legge dati profilo ed elenco ambienti oltre alla specifica API che vuoi gestire. Per questo richiede foxids:tenant:basic.read piu un ruolo di lettura ambiente (foxids:tenant:track[main].read oppure foxids:tenant.read) insieme ai ruoli di azione.
• I chiamanti solo API possono essere piu limitati. Se un servizio backend chiama solo la user API per l'ambiente vh2csjt4, il ruolo foxids:tenant:track[vh2csjt4]:user e sufficiente, insieme alla richiesta dello scope corrispondente quando si usano client credentials. I ruoli di lettura aggiuntivi non sono necessari perche non devono essere caricati dati UI.

Ambienti

Configura un insieme di ambienti, uno per ciascuno dei tuoi ambienti, ad esempio dev, qa e prod.

Crea uno o piu ambienti, non collocare la configurazione nell'ambiente master.

Ogni ambiente contiene un repository utenti e un metodo di autenticazione login predefinito.

Puoi aggiungere registrazioni applicative e metodi di autenticazione OpenID Connect, OAuth 2.0 e SAML 2.0.

Un ambiente contiene un certificato primario e possibilmente un certificato secondario nella scheda Certificates. Se entrambi sono configurati, e possibile scambiare tra certificato primario e secondario, a seconda del tipo di contenitore del certificato.

Le proprieta dell'ambiente possono essere configurate facendo clic sull'icona impostazioni in alto a destra.

• Sequence lifetime e la durata massima del flusso di login di un utente dall'inizio alla fine.
• FoxIDs protegge dai tentativi di indovinare la password tramite max failing logins, durata del conteggio dei login falliti e observation period.
• I requisiti password vengono configurati in termini di lunghezza, complessita e password risk.
• E possibile ospitare FoxIDs in un iframe da domini consentiti.
• Puoi inviare email con il tuo tenant SendGrid aggiungendo un indirizzo email personalizzato e la chiave SendGrid.

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.

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.

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}/{track_name}/{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}/{track_name}/{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 client.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.