FoxIDs Control API

Control API to REST API z opisem interfejsu Swagger (OpenAPI) oraz Swagger UI.

Jeśli hostujesz FoxIDs samodzielnie, dokument Swagger (OpenAPI) jest dostępny w FoxIDs Control pod .../api/swagger/v2/swagger.json, a Swagger UI pod .../api/swagger.

Dokumentacja API

Swagger opisuje dokładne routes, parametry, schematy request i response oraz aktualne kody statusu.

• Swagger (OpenAPI) JSON
• Swagger UI

Przewodniki po zasobach

Przewodniki po zasobach wyjaśniają, jak bezpiecznie łączyć powiązane operacje. Obejmują one przepływy pracy, przykłady, względy bezpieczeństwa i godne uwagi skutki uboczne bez powielania całej umowy OpenAPI.

struktura Tenant

• Tenant administracja
• Środowiska

Konfiguracja

• Aplikacje i metody uwierzytelniania

Użytkownicy i dostęp

• Rejestracje użytkowników i aplikacji uwierzytelniających

Operacje

• Dzienniki, kontrola i użycie

Terminologia i struktura endpointów

Nazewnictwo Control API:

• Środowisko nazywa się track
• Rejestracja aplikacji nazywa się downparty
• Metoda uwierzytelniania nazywa się upparty

Adres URL Control API zawiera zmienne dla nazwy tenanta i nazwy track (nazwa środowiska), na którym chcesz operować: .../{tenant_name}/{track_name}/.... Zastąp {tenant_name} nazwą swojego tenanta i {track_name} techniczną nazwą środowiska. Jeśli generujesz proxy na podstawie dokumentu Swagger (OpenAPI), te zmienne są przekazywane jako parametry wejściowe.

Na przykład, aby odczytać rejestrację aplikacji OpenID Connect w FoxIDs Cloud o technicznej nazwie some_oidc_app, wywołaj (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app (zastąp zmienne nazwą tenanta i techniczną nazwą środowiska).

Uwierzytelnianie

Control API możesz wywołać jako usługę/daemon używając klienta OAuth 2.0 (client credentials) albo w kontekście użytkownika przez klienta OpenID Connect.

Poniższe kroki tworzą klienta OAuth 2.0 i przyznają mu administracyjne uprawnienia dostępu poprzez zakresy i role.

Utwórz klienta OAuth 2.0 w FoxIDs Control Client:

1. Wybierz środowisko master (w nagłówku).
2. Wybierz kartę Applications.
3. Kliknij New Application.
4. Kliknij Backend Application. a. Dodaj Name, np. My API Client. b. Kliknij Register. c. Skopiuj Client ID i Client secret. d. Kliknij Close.
5. Kliknij rejestrację klienta na liście, aby ją otworzyć.
6. W sekcji Resource and scopes - przyznaje klientowi dostęp do Twojego tenanta: a. Kliknij Add Resource and scope i dodaj zasób foxids_control_api. b. Kliknij Add Scope i dodaj zakres foxids:tenant.
7. Wybierz Show advanced.
8. W sekcji Issue claims - przyznaje klientowi rolę administratora tenanta: a. Kliknij Add Claim i dodaj claim role. b. Kliknij Add Value i dodaj wartość claim foxids:tenant.admin.
9. Kliknij Update.

Następnie wykonaj żądanie OAuth 2.0 Client Credentials Grant, aby uzyskać token dostępu dla Control API.

Zastąp {tenant_name}, {track_name}, {client_id} oraz {client_secret}. Zmień domenę, jeśli hostujesz samodzielnie.

Przykład Postman Ta kolekcja Postman uwierzytelnia się klientem OAuth 2.0 My API Client i zwraca użytkowników dla skonfigurowanego środowiska (track).

Utwórz plik kolekcji Postman JSON, np. foxids_control_api.postman_collection.json, z poniższą zawartością. Zastąp {tenant_name}, {track_name}, {client_id} oraz {client_secret}. Zmień domeny (foxids.com i control.foxids.com), jeśli hostujesz samodzielnie.

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

Przykład żądania HTTP Ten przykład HTTP uwierzytelnia się jako klient OAuth 2.0 My API Client z użyciem 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

Odpowiedź JSON tokenu:

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 służy do wywoływania Control API.

Przykład kodu C# Ten przykład C# uwierzytelnia się jako klient OAuth 2.0 My API Client z użyciem 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);

Następnie wywołaj Control API z tokenem dostępu w nagłówku Authorization Bearer, zgodnie ze standardem OAuth 2.0 Bearer Token (RFC 6750).

Przykład kodu C# Ten przykład C# pokazuje, jak dodać token dostępu do HttpClient i odczytać rejestrację aplikacji OpenID Connect some_oidc_app (nazwa techniczna).

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

Uprawnienia dostępu API

Pokazuje konfigurację Control API w środowisku głównym tenanta z domyślnym zestawem zakresów, które zapewniają dostęp do danych tenanta.

Możesz dodać więcej zakresów, aby rozszerzyć uprawnienia dostępu Control API dla poszczególnych środowisk i uzyskać konfiguracje o zasadzie najmniejszych uprawnień.

Dostęp do Control API jest ograniczony przez zakresy i role. Istnieją dwie rodziny zakresów: foxids:master zapewnia dostęp do danych głównego tenanta, a foxids:tenant zapewnia dostęp do danych tenanta. Zasób Control API foxids_control_api jest zdefiniowany w środowisku głównym każdego tenanta, a skonfigurowane zakresy przyznają dostęp do danych tego tenanta przez Control API.

Dostęp zakresu można zawęzić, dodając kolejne elementy oddzielone średnikami i kropkami. Notacja z kropką ogranicza do określonej podroli i jest używana zarówno w zakresach, jak i rolach. Wywołujący muszą przedstawić co najmniej jeden pasujący zakres i rolę.

Każde uprawnienie dostępu jest zdefiniowane zarówno jako zakres, jak i rola. Pozwala to przyznawać lub ograniczać dostęp na poziomie klienta i użytkownika. Uprawnienia dostępu są hierarchiczne, a klient i użytkownik nie muszą mieć zgodnych zakresów i ról.

Rola administratora foxids:tenant.admin zapewnia dostęp do wszystkich danych w tenancie i danych głównego tenanta; jest równoważna rolom foxids:tenant i foxids:master.

Klient żąda zakresu, określając zasób i zakres oddzielone średnikiem. Na przykład, aby zażądać zakresu foxids:tenant:track:party.create, klient żąda foxids_control_api:foxids:tenant:track:party.create.

Jeśli żądanie zostanie odrzucone z powodu niewystarczających uprawnień, w logu śledzenia zapisywana jest informacja o możliwych autoryzujących zakresach i rolach wraz z rzeczywistymi zakresami i rolami użytkownika.

Uprawnienia dostępu do tenanta

Uprawnienia dostępu do tenanta są zarówno zakresami, jak i rolami.

Jeśli potrzebny zakres nie jest zdefiniowany w Control API foxids_control_api, możesz go dodać.

:track[xxxx] wskazuje środowisko według nazwy technicznej, np. środowisko Test o technicznej nazwie hsgm7je5 to :track[hsgm7je5], a środowisko Production o technicznej nazwie - to :track[-].

Uprawnienia dostępu głównego tenanta

Uprawnienia dostępu głównego tenanta są zarówno zakresami, jak i rolami.

Powiązana dokumentacja

• FoxIDs Control przegląd
• Tenant administracja
• Środowiska
• Aplikacje i metody uwierzytelniania
• Rejestracje użytkowników i aplikacji uwierzytelniających
• Dzienniki, kontrola i użycie