FoxIDs Control
FoxIDs jest konfigurowany za pomocą FoxIDs Control, które składa się z Control Client oraz Control API. Control Client i API są zabezpieczone przez FoxIDs, a Control Client korzysta z Control API.
Control API zawiera całą funkcjonalność konfiguracji. Dlatego można automatyzować konfigurację poprzez integrację z Control API.
FoxIDs Control Client
Control Client to aplikacja Blazor WebAssembly (WASM).
Otwórz swój Control Client na FoxIDs.com.
Tenant i środowisko główne
Jeśli korzystasz z FoxIDs.com, Twój tenant jest tworzony podczas rejestracji.
Jeśli wdrażasz FoxIDs (self-hosted), uzyskujesz dostęp do głównego tenanta. Najpierw utwórz tenanta, który będzie zawierał konfigurację bezpieczeństwa. Większość instalacji potrzebuje tylko jednego, ale możesz skonfigurować nieograniczoną liczbę tenantów.
Tenant zawiera środowisko główne, z którego konfiguruje się cały tenant. Środowisko główne zawiera repozytorium użytkowników i w momencie utworzenia ma tylko jednego użytkownika administracyjnego.
Zwykle nie należy zmieniać konfiguracji środowiska głównego ani dodawać nowych metod uwierzytelniania czy rejestracji aplikacji, ale jest to możliwe. Możesz np. dodając metodę uwierzytelniania uzyskać single sign-on (SSO) do środowiska głównego.
Tworzenie użytkowników administracyjnych
Można utworzyć więcej użytkowników administracyjnych w środowisku master. Użytkownik staje się administratorem po dodaniu roli administratora foxids:tenant.admin, jak pokazano poniżej.
Utwórz użytkownika:
- Otwórz środowisko główne
- Wybierz kartę Users
- Kliknij Create User
- Dodaj informacje o użytkowniku i kliknij Create.
Nadawanie dostępu użytkownikowi
Dostęp jest przyznawany za pomocą ról. Zakresy (scopes) są potrzebne tylko wtedy, gdy klient żąda tokenu dla Control API; Control Client już żąda wymaganych zakresów w foxids_control_api, więc zwykle przypisujesz role tylko użytkownikowi w środowisku głównym.
Aby pozwolić osobie zalogować się do Control Client i zobaczyć dane konfiguracyjne:
- Utwórz lub otwórz użytkownika w środowisku
master(karta Users). - Dodaj podstawową rolę
foxids:tenant:basic.read(wymagana, aby Control Client mógł wczytać profil i narzędzia pomocnicze). - Zdecyduj, co użytkownik może widzieć:
- Aby ograniczyć widoczność do jednego środowiska, dodaj
foxids:tenant:track[vh2csjt4].read(zastąpvh2csjt4techniczną nazwą środowiska). - Aby zezwolić na wszystkie środowiska, dodaj
foxids:tenant.read.
- Aby ograniczyć widoczność do jednego środowiska, dodaj
- Dodaj role operacyjne potrzebne użytkownikowi w każdym środowisku. Przykłady:
foxids:tenant:track[vh2csjt4]:userdo zarządzania użytkownikami,foxids:tenant:track[vh2csjt4]:partydo zarządzania aplikacjami i metodami uwierzytelniania.
Control Client vs tylko API:
- Control Client (interaktywne UI) odczytuje dane profilu i listy środowisk, oprócz konkretnego API, którym chcesz zarządzać. Dlatego wymaga
foxids:tenant:basic.readoraz roli odczytu środowiska (foxids:tenant:track[main].readlubfoxids:tenant.read) obok ról akcji. - Wywołujący tylko API mogą mieć węższy zakres. Jeśli usługa backendowa wywołuje tylko API użytkowników dla środowiska
vh2csjt4, rolafoxids:tenant:track[vh2csjt4]:user(oraz żądanie odpowiadającego zakresu przy użyciu client credentials) jest wystarczająca; dodatkowe role odczytu nie są wymagane, ponieważ nie trzeba ładować danych UI.
Środowiska
Skonfiguruj kilka środowisk, po jednym dla każdego środowiska, np. dev, qa i prod.
Utwórz jedno lub więcej środowisk, nie umieszczaj konfiguracji w środowisku głównym.
Każde środowisko zawiera repozytorium użytkowników i domyślną metodę uwierzytelniania login.
Możesz dodać rejestracje aplikacji i metody uwierzytelniania dla OpenID Connect, OAuth 2.0 oraz SAML 2.0.
Środowisko zawiera certyfikat główny i ewentualnie certyfikat dodatkowy w karcie Certificates. Jeśli oba są skonfigurowane, możesz przełączać się między certyfikatem głównym a dodatkowym, w zależności od typu kontenera certyfikatu.
Właściwości środowiska można skonfigurować, klikając ikonę ustawień w prawym górnym rogu.
- Sequence lifetime to maksymalny czas trwania przepływu logowania użytkownika od początku do końca.
- FoxIDs chroni przed zgadywaniem haseł poprzez maksymalną liczbę nieudanych logowań, czas życia licznika nieudanych logowań i okres obserwacji.
- Wymagania dotyczące haseł są konfigurowane pod kątem długości, złożoności i ryzyka hasła.
- FoxIDs można hostować w iframe z dozwolonych domen.
- Możesz wysyłać wiadomości e-mail ze swojego tenanta SendGrid, dodając niestandardowy adres e-mail i klucz SendGrid.
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.
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).
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:
- Wybierz środowisko master (w nagłówku).
- Wybierz kartę Applications.
- Kliknij New Application.
- Kliknij Backend Application.
a. Dodaj Name, np.
My API Client. b. Kliknij Register. c. Skopiuj Client ID i Client secret. d. Kliknij Close. - Kliknij rejestrację klienta na liście, aby ją otworzyć.
- 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 zakresfoxids:tenant. - Wybierz Show advanced.
- W sekcji Issue claims - przyznaje klientowi rolę administratora tenanta:
a. Kliknij Add Claim i dodaj claim
role. b. Kliknij Add Value i dodaj wartość claimfoxids:tenant.admin. - 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}/{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
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}/{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);
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 client.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[-].
| Zakres / rola | Dostęp |
|---|---|
| Dostęp do wszystkiego w tenancie, bez danych głównego tenanta. | |
foxids:tenant |
read, create, update, delete |
foxids:tenant.read |
read |
foxids:tenant.create |
create |
foxids:tenant.update |
update |
foxids:tenant.delete |
delete |
| Dostęp do podstawowych elementów tenanta:
|
|
foxids:tenant:basic |
read, create, update, delete |
foxids:tenant:basic.read |
read |
foxids:tenant:basic.create |
create |
foxids:tenant:basic.update |
update |
foxids:tenant:basic.delete |
delete |
| Dostęp do wszystkiego we wszystkich środowiskach w tenancie, z wyłączeniem środowiska głównego. | |
foxids:tenant:track |
read, create, update, delete |
foxids:tenant:track.read |
read |
foxids:tenant:track.create |
create |
foxids:tenant:track.update |
update |
foxids:tenant:track.delete |
delete |
| Dostęp do wszystkiego w konkretnym środowisku w tenancie. `xxxx` to techniczna nazwa środowiska. | |
foxids:tenant:track[xxxx] |
read, create, update, delete |
foxids:tenant:track[xxxx].read |
read |
foxids:tenant:track[xxxx].create |
create |
foxids:tenant:track[xxxx].update |
update |
foxids:tenant:track[xxxx].delete |
delete |
| Wszystkie logi użycia we wszystkich środowiskach w tenancie, z wyłączeniem środowiska głównego. Nie dotyczy głównego tenanta. | |
foxids:tenant:track:usage |
read |
| Logi użycia w konkretnym środowisku w tenancie. Nie dotyczy głównego tenanta. | |
foxids:tenant:track[xxxx]:usage |
read |
| Wszystkie logi audytu we wszystkich środowiskach w tenancie, z wyłączeniem środowiska głównego. | |
foxids:tenant:track:audit |
read |
| Logi audytu w konkretnym środowisku w tenancie. | |
foxids:tenant:track[xxxx]:audit |
read |
| Wszystkie logi we wszystkich środowiskach w tenancie, z wyłączeniem środowiska głównego. | |
foxids:tenant:track:log |
read, create, update, delete |
foxids:tenant:track:log.read |
read |
foxids:tenant:track:log.create |
create |
foxids:tenant:track:log.update |
update |
foxids:tenant:track:log.delete |
delete |
| Logi w konkretnym środowisku w tenancie. | |
foxids:tenant:track[xxxx]:log |
read, create, update, delete |
foxids:tenant:track[xxxx]:log.read |
read |
foxids:tenant:track[xxxx]:log.create |
create |
foxids:tenant:track[xxxx]:log.update |
update |
foxids:tenant:track[xxxx]:log.delete |
delete |
| Wszyscy użytkownicy we wszystkich środowiskach w tenancie, z wyłączeniem środowiska głównego. | |
foxids:tenant:track:user |
read, create, update, delete |
foxids:tenant:track:user.read |
read |
foxids:tenant:track:user.create |
create |
foxids:tenant:track:user.update |
update |
foxids:tenant:track:user.delete |
delete |
| Wszyscy użytkownicy w konkretnym środowisku w tenancie. | |
foxids:tenant:track[xxxx]:user |
read, create, update, delete |
foxids:tenant:track[xxxx]:user.read |
read |
foxids:tenant:track[xxxx]:user.create |
create |
foxids:tenant:track[xxxx]:user.update |
update |
foxids:tenant:track[xxxx]:user.delete |
delete |
| Wszystkie rejestracje aplikacji i metody uwierzytelniania we wszystkich środowiskach w tenancie, z wyłączeniem środowiska głównego. | |
foxids:tenant:track:party |
read, create, update, delete |
foxids:tenant:track:party.read |
read |
foxids:tenant:track:party.create |
create |
foxids:tenant:track:party.update |
update |
foxids:tenant:track:party.delete |
delete |
| Wszystkie rejestracje aplikacji i metody uwierzytelniania w konkretnym środowisku w tenancie. | |
foxids:tenant:track[xxxx]:party |
read, create, update, delete |
foxids:tenant:track[xxxx]:party.read |
read |
foxids:tenant:track[xxxx]:party.create |
create |
foxids:tenant:track[xxxx]:party.update |
update |
foxids:tenant:track[xxxx]:party.delete |
delete |
Uprawnienia dostępu głównego tenanta
Uprawnienia dostępu głównego tenanta są zarówno zakresami, jak i rolami.
| Zakres / rola | Dostęp |
|---|---|
| Dostęp do danych głównego tenanta Można wyświetlać listę, tworzyć i usuwać tenantów, ale bez wglądu w innych tenantów. |
|
foxids:master |
read, create, update, delete |
foxids:master.read |
read |
foxids:master.create |
create |
foxids:master.update |
update |
foxids:master.delete |
delete |
| Log audytu w głównym tenancie. | |
foxids:master:audit |
read |
| Log użycia w głównym tenancie. | |
foxids:master:usage |
read |