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 eksponert i FoxIDs Control på .../api/swagger/v2/swagger.json og Swagger UI på .../api/swagger.

API-referanse

Swagger beskriver de nøyaktige rutene, parameterne, request- og response-skjemaene samt gjeldende statuskoder.

• Swagger (OpenAPI) JSON
• Swagger UI

Ressursguider

Ressursguider forklarer hvordan du kan kombinere relaterte operasjoner på en sikker måte. De inkluderer arbeidsflyter, eksempler, sikkerhetshensyn og bemerkelsesverdige bivirkninger uten å duplisere hele OpenAPI-kontrakten.

Tenant struktur

• Tenant administrasjon
• Miljøer

Konfigurasjon

• Applikasjoner og autentiseringsmetoder

Brukere og tilgang

• Registreringer av brukere og autentiseringsapper

Drift

• Logger, revisjon og bruk

Terminologi og endpoint-struktur

Control API navngivning:

• Et miljø kalles en track
• En applikasjonsregistrering kalles en downparty
• En autentiseringsmetode kalles en upparty

Control API URLen inneholder variabler for tenant navn og track navn (miljønavn) du vil operere på: .../{tenant_name}/{track_name}/.... Erstatt {tenant_name} med tenant navnet ditt og {track_name} med teknisk miljønavn. Hvis du genererer en proxy fra Swagger (OpenAPI) dokumentet, leveres disse variablene som input parametre.

For eksempel, for å lese en OpenID Connect applikasjonsregistrering i FoxIDs Cloud med teknisk navn some_oidc_app, kall (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app (erstatt variablene med tenant navn og teknisk miljønavn).

Autentisering

Du kan kalle Control API enten som en service daemon med en OAuth 2.0 client (client credentials) eller i konteksten av en bruker via en OpenID Connect client.

Trinnene nedenfor oppretter en OAuth 2.0 client og gir den admin nivå access rights via scopes og roller.

Opprett en OAuth 2.0 client i FoxIDs Control Client:

1. Velg master miljøet (i headeren).
2. Velg Applications fanen.
3. Klikk New Application.
4. Klikk Backend Application.
   1. Legg til Name f.eks. My API Client.
   2. Klikk Register.
   3. Kopier Client ID og Client secret.
   4. Klikk Close.
5. Klikk din client registrering i listen for å åpne den.
6. I seksjonen Resource and scopes - gir clienten tilgang til tenant:
   1. Klikk Add Resource and scope og legg til ressurss foxids_control_api.
   2. Klikk Add Scope og legg til scopet foxids:tenant.
7. Velg Show advanced.
8. I seksjonen Issue claims - gir clienten tenant administrator rollen:
   1. Klikk Add Claim og legg til claim role.
   2. Klikk Add Value og legg til claim verdi foxids:tenant.admin.
9. Klikk Update.

Gjør deretter en OAuth 2.0 Client Credentials Grant request for å få et access token til Control API.

Erstatt {tenant_name}, {track_name}, {client_id} og {client_secret}. Bytt domene hvis du self hoster.

Postman sample Denne Postman collection autentiserer med OAuth 2.0 clienten My API Client og returnerer brukerne for konfigurert miljø (track).

Opprett en Postman collection JSON fil, f.eks. foxids_control_api.postman_collection.json, med innholdet nedenfor. Erstatt {tenant_name}, {track_name}, {client_id} og {client_secret}. Bytt domener (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 autentiserer 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 brukes til å kalle Control API.

C# code sample Denne C# sample autentiserer 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);

Kall deretter Control API med access token som Authorization Bearer header, som definert i OAuth 2.0 Bearer Token (RFC 6750) standarden.

C# code sample Denne C# sample viser hvordan du legger til access token i HttpClient og leser OpenID Connect applikasjonsregistreringen 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 konfigurasjonen i en tenants master miljø med standard sett av scopes som gir tilgang til tenant data.

Du kan legge til flere scopes for å utvide Control API tilgangsrettigheter per miljø for å oppnå least privilege konfigurasjoner.

Tilgang til Control API er begrenset av scopes og roller. Det er to scope familier: foxids:master gir tilgang til master tenant data og foxids:tenant gir tilgang til tenant data. Control API ressursen foxids_control_api er definert i hver tenants master miljø, og de konfigurerte scopes gir tilgang til tenant data via Control API.

En scopes tilgang kan snevres inn ved å legge til flere elementer separert med semikolon og punktum. Punktum notasjon begrenser til en spesifikk sub rolle og brukes både i scopes og roller. Kallere må presentere ett eller flere matchende scope(s) og rolle(r).

Hver tilgangsrettighet er definert både som et scope og en rolle. Dette lar deg gi eller begrense tilgang på både client og bruker nivå. Tilgangsrettigheter er hierarkiske, og client og bruker trenger ikke matchende scopes og roller.

Administrator rollen foxids:tenant.admin gir tilgang til alle data i en tenant og master tenant data; den tilsvarer rollene foxids:tenant og foxids:master.

En client ber om et scope ved å spesifisere resource og scope separert med et semikolon. For eksempel, for å be om scopet foxids:tenant:track:party.create ber clienten om foxids_control_api:foxids:tenant:track:party.create.

Hvis en request avvises på grunn av utilstrekkelige tilgangsrettigheter, logges et trace item med mulige autoriserende scopes og roller sammen med brukerens faktiske scopes og roller.

Tenant access rights

Tenant tilgangsrettigheter er både scopes og roller.

Hvis scopet du trenger ikke er definert på Control API foxids_control_api kan du legge til scopet.

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

Master tenant access rights

Master tenant tilgangsrettigheter er både scopes og roller.

Relatert dokumentasjon

• FoxIDs Control oversikt
• Tenant administrasjon
• Miljøer
• Applikasjoner og autentiseringsmetoder
• Registreringer av brukere og autentiseringsapper
• Logger, revisjon og bruk