FoxIDs Control API

Control API är en REST API med en online Swagger (OpenAPI) interface beskrivning och Swagger UI.

Om du self hostar FoxIDs, exponeras Swagger (OpenAPI) dokumentet i FoxIDs Control på .../api/swagger/v2/swagger.json och Swagger UI på .../api/swagger.

API-referens

Swagger beskriver exakta routes, parametrar, request- och response-scheman samt aktuella statuskoder.

• Swagger (OpenAPI) JSON
• Swagger UI

Resursguider

Resursguider förklarar hur man kombinerar relaterade operationer på ett säkert sätt. De inkluderar arbetsflöden, exempel, säkerhetsöverväganden och anmärkningsvärda bieffekter utan att duplicera hela OpenAPI-kontraktet.

Tenant struktur

• Tenant administration
• Miljöer

Konfiguration

• Applikationer och autentiseringsmetoder

Användare och åtkomst

• Registrering av användare och autentiseringsappar

Operationer

• Loggar, granskning och användning

Terminologi och endpoint-struktur

Control API namngivning:

• En miljö kallas track
• En applikationsregistrering kallas downparty
• En autentiseringsmetod kallas upparty

Control API URLen innehåller variabler för tenant namn och track namn (miljö namn) du vill arbeta på: .../{tenant_name}/{track_name}/.... Ersätt {tenant_name} med ditt tenant namn och {track_name} med miljöns tekniska namn. Om du genererar en proxy från Swagger (OpenAPI) dokumentet, levereras variablerna som input parametrar.

Till exempel, för att läsa en OpenID Connect applikationsregistrering i FoxIDs Cloud med tekniskt namn some_oidc_app, anropa (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app (ersätt variablerna med ditt tenant namn och tekniskt miljö namn).

Autentisering

Du kan anropa Control API antingen som en service daemon med en OAuth 2.0 client (client credentials) eller i kontexten av en användare via en OpenID Connect client.

Stegen nedan skapar en OAuth 2.0 client och ger den admin nivå access rights via scopes och roller.

Skapa en OAuth 2.0 client i FoxIDs Control Client:

1. Välj master miljön (i headern).
2. Välj Applications fliken.
3. Klicka New Application.
4. Klicka Backend Application.
   1. Lägg till ett Name t.ex. My API Client.
   2. Klicka Register.
   3. Kopiera Client ID och Client secret.
   4. Klicka Close.
5. Klicka din client registrering i listan för att öppna den.
6. I sektionen Resource and scopes - ger clienten tillgång till din tenant:
   1. Klicka Add Resource and scope och lägg till resursen foxids_control_api.
   2. Klicka Add Scope och lägg till scopet foxids:tenant.
7. Välj Show advanced.
8. I sektionen Issue claims - ger clienten tenant administratör rollen:
   1. Klicka Add Claim och lägg till claim role.
   2. Klicka Add Value och lägg till claim värde foxids:tenant.admin.
9. Klicka Update.

Gör sedan en OAuth 2.0 Client Credentials Grant request för att få ett access token till Control API.

Ersätt {tenant_name}, {track_name}, {client_id} och {client_secret}. Byt domän om du self hostar.

Postman sample Denna Postman collection autentiserar med OAuth 2.0 clienten My API Client och returnerar användarna för den konfigurerade miljön (track).

Skapa en Postman collection JSON fil, t.ex. foxids_control_api.postman_collection.json, med innehållet nedan. Ersätt {tenant_name}, {track_name}, {client_id} och {client_secret}. Byt domäner (foxids.com och control.foxids.com) om du self hostar.

{
  "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 Denna HTTP sample autentiserar 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 används för att anropa Control API.

C# code sample Denna C# sample autentiserar 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);

Anropa sedan Control API med access token som Authorization Bearer header, enligt OAuth 2.0 Bearer Token (RFC 6750) standarden.

C# code sample Denna C# sample visar hur du lägger till access token i HttpClient och läser OpenID Connect applikationsregistreringen some_oidc_app (tekniskt namn).

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

Detta visar Control API konfigurationen i en tenants master miljö med default uppsättning scopes som ger åtkomst till tenant data.

Du kan lägga till fler scopes för att utöka Control API åtkomst per miljö för att uppnå least privilege konfigurationer.

Åtkomst till Control API är begränsad av scopes och roller. Det finns två scope familjer: foxids:master ger åtkomst till master tenant data och foxids:tenant ger åtkomst till tenant data. Control API resursen foxids_control_api är definierad i varje tenants master miljö, och de konfigurerade scopes ger åtkomst till tenant data via Control API.

En scopes åtkomst kan begränsas genom att lägga till fler element separerade med semikolon och punkter. Punkt notering begränsar till en specifik sub roll och används både i scopes och roller. Callers måste presentera en eller flera matchande scope(s) och roll(er).

Varje åtkomsträtt är definierad både som ett scope och en roll. Detta gör det möjligt att ge eller begränsa åtkomst på både client och användare nivå. Åtkomsträttigheter är hierarkiska, och client och användare behöver inte matchande scopes och roller.

Administratör rollen foxids:tenant.admin ger åtkomst till all data i en tenant och master tenant data; den är likvärdig med rollerna foxids:tenant och foxids:master.

En client begär ett scope genom att ange resource och scope separerat med ett semikolon. Till exempel, för att begära scopet foxids:tenant:track:party.create begär clienten foxids_control_api:foxids:tenant:track:party.create.

Om en request nekas på grund av otillräckliga åtkomsträttigheter loggas ett trace item med möjliga authoriserande scopes och roller tillsammans med användarens faktiska scopes och roller.

Tenant access rights

Tenant access rights är både scopes och roller.

Om scopet du behöver inte är definierat på Control API foxids_control_api kan du lägga till scopet.

:track[xxxx] specificerar en miljö med tekniskt namn. t.ex. en Test miljö med tekniskt namn hsgm7je5 är :track[hsgm7je5] och en Production miljö med tekniskt namn - är :track[-].

Master tenant access rights

Master tenant access rights är både scopes och roller.

Relaterad dokumentation

• FoxIDs Control översikt
• Tenant administration
• Miljöer
• Applikationer och autentiseringsmetoder
• Registrering av användare och autentiseringsappar
• Loggar, granskning och användning