FoxIDs Control API

Control API er en REST API med en online Swagger (OpenAPI) interface beskrivelse og Swagger UI.

Hvis du self hoster FoxIDs, er Swagger (OpenAPI) dokumentet eksponeret i FoxIDs Control på .../api/swagger/v2/swagger.json og Swagger UI på .../api/swagger.

API-reference

Swagger beskriver de præcise routes, parametre, request- og response-skemaer samt aktuelle statuskoder.

• Swagger (OpenAPI) JSON
• Swagger UI

Ressourcevejledninger

Ressourcevejledninger forklarer, hvordan man kombinerer relaterede operationer sikkert. De omfatter arbejdsgange, eksempler, sikkerhedsovervejelser og bemærkelsesværdige bivirkninger uden at duplikere hele OpenAPI-kontrakten.

Tenant struktur

• Tenant administration
• Miljøer

Konfiguration

• Applikationer og godkendelsesmetoder

Brugere og adgang

• Registreringer af brugere og godkendelsesapps

Operationer

• Log, revision og brug

Terminologi og endpoint-struktur

Control API navngivning:

• Et miljø kaldes en track
• En applikationsregistrering kaldes en downparty
• En autentificeringsmetode kaldes en upparty

Control API URL'en indeholder variabler for tenant navn og track navn (miljønavn) du vil arbejde på: .../{tenant_name}/{track_name}/.... Erstat {tenant_name} med dit tenant navn og {track_name} med miljøets tekniske navn. Hvis du genererer en proxy fra Swagger (OpenAPI) dokumentet, leveres variablerne som input parametre.

For eksempel, for at læse en OpenID Connect applikationsregistrering i FoxIDs Cloud med det tekniske navn some_oidc_app, kald (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app (erstat variablerne med dit tenant navn og miljøets tekniske navn).

Autentificering

Du kan kalde Control API enten som en service daemon med en OAuth 2.0 client (client credentials) eller i konteksten af en bruger via en OpenID Connect client.

Trinene nedenfor opretter en OAuth 2.0 client og tildeler den admin niveau access rights via scopes og roller.

Opret en OAuth 2.0 client i FoxIDs Control Client:

1. Vælg master miljøet (i headeren).
2. Vælg fanen Applications.
3. Klik New Application.
4. Klik Backend Application.
   1. Tilføj et Name f.eks. My API Client.
   2. Klik Register.
   3. Kopiér Client ID og Client secret.
   4. Klik Close.
5. Klik din client registrering i listen for at åbne den.
6. I sektionen Resource and scopes - tildeler client adgang til din tenant:
   1. Klik Add Resource and scope og tilføj resourcen foxids_control_api.
   2. Klik Add Scope og tilføj scopet foxids:tenant.
7. Vælg Show advanced.
8. I sektionen Issue claims - tildeler clienten tenant administrator rollen:
   1. Klik Add Claim og tilføj claim role.
   2. Klik Add Value og tilføj claim værdi foxids:tenant.admin.
9. Klik Update.

Udfør derefter en OAuth 2.0 Client Credentials Grant request for at få en access token til Control API.

Erstat {tenant_name}, {track_name}, {client_id} og {client_secret}. Skift domænet hvis du self hoster.

Postman sample Denne Postman collection autentificerer med OAuth 2.0 clienten My API Client og returnerer brugerne for det konfigurerede miljø (track).

Opret en Postman collection JSON fil, f.eks. foxids_control_api.postman_collection.json, med indholdet nedenfor. Erstat {tenant_name}, {track_name}, {client_id} og {client_secret}. Skift domænerne (foxids.com og control.foxids.com) hvis du self hoster.

{
  "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 Denne HTTP sample autentificerer som OAuth 2.0 clienten My API Client med 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
}

access_token bruges til at kalde Control API.

C# code sample Denne C# sample autentificerer som OAuth 2.0 clienten My API Client med 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);

Kald derefter Control API med access token som Authorization Bearer header, som defineret i OAuth 2.0 Bearer Token (RFC 6750) standarden.

C# code sample Denne C# sample viser hvordan access token tilføjes til HttpClient og læser OpenID Connect applikationsregistreringen some_oidc_app (teknisk navn).

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

Dette viser Control API konfigurationen i en tenants master miljø med det default sæt af scopes som giver adgang til tenant data.

Du kan tilføje flere scopes for at udvide Control API adgangsrettigheder pr. miljø for at opnå least privilege konfigurationer.

Adgang til Control API er begrænset af scopes og roller. Der er to scope familier: foxids:master giver adgang til master tenant data og foxids:tenant giver adgang til tenant data. Control API resourcen foxids_control_api er defineret i hver tenants master miljø, og de konfigurerede scopes giver adgang til den tenants data via Control API.

Et scopes adgang kan indsnævres ved at tilføje flere elementer adskilt med semikolon og punktum. Punktum notation begrænser til en specifik sub rolle og bruges både i scopes og roller. Kaldere skal præsentere et eller flere matchende scope(s) og rolle(r).

Hver adgangsrettighed defineres både som et scope og en rolle. Det gør det muligt at tildele eller begrænse adgang på både client og bruger niveau. Adgangsrettigheder er hierarkiske, og client og bruger behøver ikke matchende scopes og roller.

Administrator rollen foxids:tenant.admin giver adgang til alle data i en tenant og master tenant data; den svarer til at have rollerne foxids:tenant og foxids:master.

En client anmoder om et scope ved at specificere resourcen og scopet adskilt af et semikolon. For eksempel, for at anmode om scopet foxids:tenant:track:party.create anmoder clienten om foxids_control_api:foxids:tenant:track:party.create.

Hvis en anmodning afvises på grund af utilstrækkelige adgangsrettigheder, logges et trace item med mulige autoriserende scopes og roller sammen med brugerens aktuelle scopes og roller.

Tenant access rights

Tenant adgangsrettigheder er både scopes og roller.

Hvis scopet du har brug for ikke er defineret på Control API foxids_control_api kan du tilføje scopet.

:track[xxxx] specificerer et miljø ved det tekniske navn. f.eks. et Test miljø med det tekniske navn hsgm7je5 er :track[hsgm7je5] og et Production miljø med det tekniske navn - er :track[-].

Master tenant access rights

Master tenant adgangsrettigheder er både scopes og roller.

Relateret dokumentation

• FoxIDs Control oversigt
• Tenant administration
• Miljøer
• Applikationer og godkendelsesmetoder
• Registreringer af brugere og godkendelsesapps
• Log, revision og brug