FoxIDs Control

FoxIDs wordt geconfigureerd via FoxIDs Control, dat bestaat uit Control Client en Control API. Control Client en API zijn beveiligd door FoxIDs en Control Client gebruikt Control API.

Control API bevat alle configuratie functionaliteit. Daarom is het mogelijk om de configuratie te automatiseren door te integreren met Control API.

FoxIDs Control Client

Control Client is een Blazor WebAssembly (WASM) app.

Open je Control Client op FoxIDs.com.

Tenant en master omgeving

Als je FoxIDs.com gebruikt, wordt je tenant aangemaakt tijdens registratie.

Als je FoxIDs deploy (self hosted), krijg je toegang tot de master tenant. Maak eerst een tenant die je beveiligingsconfiguratie bevat. De meeste installaties hebben er maar één nodig, maar je kunt een onbeperkt aantal tenants configureren.

Configure tenants

Een tenant bevat een master omgeving, van waaruit de hele tenant wordt geconfigureerd. De master omgeving bevat een gebruikersrepository en bij aanmaken slechts één administrator gebruiker.

Normaal gesproken moet je de master omgeving configuratie niet wijzigen of nieuwe authenticatiemethoden of app registraties toevoegen, maar het is mogelijk. Je kunt bijvoorbeeld door een authenticatiemethode toe te voegen single sign on (SSO) krijgen voor de master omgeving.

Administrator gebruiker(s) aanmaken

Het is mogelijk om meer administrator gebruikers in de master omgeving aan te maken. Een gebruiker wordt administrator door de administrator rol foxids:tenant.admin toe te voegen zoals hieronder getoond.

Maak een gebruiker aan:

  1. Open de master omgeving
  2. Selecteer de Users tab
  3. Klik Create User
  4. Voeg gebruikersinformatie toe en klik Create.

Configure administrator user

Toegang aan gebruiker verlenen

Toegang wordt verleend met rollen. Scopes zijn alleen nodig wanneer een client een token voor Control API aanvraagt; Control Client vraagt al het vereiste scope aan op foxids_control_api, dus je wijst doorgaans alleen rollen toe aan de gebruiker in de master omgeving.

Om iemand te laten inloggen in Control Client en configuratie data te zien:

  1. Maak of open de gebruiker in de master omgeving (Users tab).
  2. Voeg de basisrol foxids:tenant:basic.read toe (vereist zodat Control Client profiel en hulpprogramma's kan laden).
  3. Bepaal wat de gebruiker mag zien:
    • Om zichtbaarheid te beperken tot één omgeving, voeg foxids:tenant:track[vh2csjt4].read toe (vervang vh2csjt4 met de technische omgeving naam).
    • Om alle omgevingen toe te staan, voeg foxids:tenant.read toe.
  4. Voeg de operationele rollen toe die de gebruiker in elke omgeving nodig heeft. Voorbeelden: foxids:tenant:track[vh2csjt4]:user om gebruikers te beheren, foxids:tenant:track[vh2csjt4]:party om applicaties en authenticatiemethoden te beheren.

Control Client vs API only:

  • Control Client (interactieve UI) leest profieldata en omgevingslijsten naast de specifieke API die je wilt beheren. Het heeft daarom foxids:tenant:basic.read plus een omgevings read rol (foxids:tenant:track[main].read of foxids:tenant.read) nodig naast je action rollen.
  • API only callers kunnen smaller zijn. Als een backend service alleen de user API voor de omgeving vh2csjt4 aanroept, is de rol foxids:tenant:track[vh2csjt4]:user (en het bijbehorende scope aanvragen bij client credentials) voldoende; de extra read rollen zijn niet nodig omdat geen UI data geladen hoeft te worden.

Omgevingen

Configureer een aantal omgevingen, één voor elk van je omgevingen zoals dev, qa en prod.

Maak één of meer omgevingen aan, plaats geen configuratie in de master omgeving.

Configure environments

Elke omgeving bevat een gebruikersrepository en een standaard login authenticatiemethode.

Je kunt OpenID Connect, OAuth 2.0 en SAML 2.0 app registraties en authenticatiemethoden toevoegen.

Configure application registrations and authentication methods

Een omgeving bevat een primair certificaat en mogelijk een secundair certificaat in de Certificates tab. Het is mogelijk om tussen het primaire en secundaire certificaat te wisselen als beide zijn geconfigureerd, afhankelijk van het certificaat container type.

Configure certificates

De omgevingsinstellingen kunnen worden geconfigureerd door op het settings icoon rechtsboven te klikken.

  • Sequence lifetime is de maximale levensduur van een login flow van start tot eind.
  • FoxIDs beschermt tegen password guessing via max failing logins, failing login count lifetime en observation period.
  • Wachtwoordvereisten worden geconfigureerd voor lengte, complexiteit en password risk.
  • Het is mogelijk om FoxIDs te hosten in een iframe vanaf toegestane domeinen.
  • Je kunt emails verzenden met je eigen SendGrid tenant door een custom email adres en SendGrid sleutel toe te voegen.

Configure environment settings

FoxIDs Control API

Control API is een REST API met een online Swagger (OpenAPI) interface beschrijving en Swagger UI.

Als je FoxIDs self host, wordt het Swagger (OpenAPI) document getoond in FoxIDs Control op .../api/swagger/v2/swagger.json en de Swagger UI op .../api/swagger.

Control API naming:

  • Een omgeving heet een track
  • Een app registratie heet een downparty
  • Een authenticatiemethode heet een upparty

De Control API URL bevat variabelen voor de tenant naam en track naam (omgeving naam) die je wilt beheren: .../{tenant_name}/{track_name}/.... Vervang {tenant_name} met je tenant naam en {track_name} met de technische omgeving naam. Als je een proxy genereert vanuit het Swagger (OpenAPI) document, worden die variabelen als input parameters aangeboden.

Bijvoorbeeld om een OpenID Connect app registratie te lezen in FoxIDs Cloud met de technische naam some_oidc_app, roep (HTTP GET) https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app aan (vervang de variabelen met je tenant naam en technische omgeving naam).

Je kunt Control API aanroepen als service daemon met een OAuth 2.0 client (client credentials) of in de context van een gebruiker via een OpenID Connect client.

De stappen hieronder maken een OAuth 2.0 client aan en verlenen admin level access rights via scopes en rollen.

Maak een OAuth 2.0 client in FoxIDs Control Client:

  1. Selecteer de master omgeving (in de header).
  2. Selecteer de Applications tab.
  3. Klik New Application.
  4. Klik Backend Application.
    1. Voeg een Name toe, bijvoorbeeld My API Client.
    2. Klik Register.
    3. Kopieer Client ID en Client secret.
    4. Klik Close.
  5. Klik je client registratie in de lijst om deze te openen.
  6. In de Resource and scopes sectie - geeft de client toegang tot je tenant:
    1. Klik Add Resource and scope en voeg de resource foxids_control_api toe.
    2. Klik Add Scope en voeg het scope foxids:tenant toe.
  7. Selecteer Show advanced.
  8. In de Issue claims sectie - geeft de client de tenant administrator rol:
    1. Klik Add Claim en voeg de claim role toe.
    2. Klik Add Value en voeg de claim waarde foxids:tenant.admin toe.
  9. Klik Update.

Voer daarna een OAuth 2.0 Client Credentials Grant request uit om een access token voor Control API te verkrijgen.

Vervang {tenant_name}, {track_name}, {client_id} en {client_secret}. Wijzig het domein als je self host.

Postman sample Deze Postman collection authenticeert met de OAuth 2.0 client My API Client en retourneert de gebruikers voor de geconfigureerde omgeving (track).

Maak een Postman collection JSON bestand, bijvoorbeeld foxids_control_api.postman_collection.json, met de onderstaande inhoud. Vervang {tenant_name}, {track_name}, {client_id} en {client_secret}. Wijzig de domeinen (foxids.com en control.foxids.com) als je self host.

{
  "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 Deze HTTP sample authenticeert als de OAuth 2.0 client My API Client met de 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

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
}

Het access_token wordt gebruikt om Control API aan te roepen.

C# code sample Deze C# sample authenticeert als de OAuth 2.0 client My API Client met de 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);

Roep daarna Control API aan met het access token als Authorization Bearer header, zoals gedefinieerd in OAuth 2.0 Bearer Token (RFC 6750).

C# code sample Deze C# sample laat zien hoe je het access token toevoegt aan de HttpClient en de OpenID Connect app registratie some_oidc_app (technische naam) leest.

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

API access rights

Dit toont de Control API configuratie in een tenant master omgeving met de default set scopes die toegang geven tot tenant data.

Configure foxids_control_api

Je kunt extra scopes toevoegen om Control API toegang per omgeving uit te breiden voor least privilege configuraties.

Toegang tot Control API wordt beperkt door scopes en rollen. Er zijn twee scope families: foxids:master geeft toegang tot master tenant data en foxids:tenant geeft toegang tot tenant data. De Control API resource foxids_control_api is gedefinieerd in elke tenant master omgeving, en de geconfigureerde scopes geven toegang tot de tenant data via Control API.

De toegang van een scope kan worden beperkt door extra elementen toe te voegen, gescheiden door puntkomma's en punten. Punt notatie beperkt tot een specifieke sub rol en wordt gebruikt in zowel scopes als rollen. Callers moeten één of meerdere passende scope(s) en rol(len) presenteren.

Elke toegangsrecht is zowel een scope als een rol. Dit maakt het mogelijk om toegang op client en gebruiker niveau te verlenen of te beperken. Toegangsrechten zijn hiërarchisch, en client en gebruiker hoeven geen overeenkomende scopes en rollen te hebben.

De administrator rol foxids:tenant.admin geeft toegang tot alle data in een tenant en de master tenant data; het is gelijk aan de rollen foxids:tenant en foxids:master.

Een client vraagt een scope aan door resource en scope te scheiden met een puntkomma. Bijvoorbeeld, om het scope foxids:tenant:track:party.create aan te vragen, vraagt de client foxids_control_api:foxids:tenant:track:party.create aan.

Als een request wordt geweigerd vanwege onvoldoende toegang, wordt een trace item gelogd met de mogelijke authoriserende scopes en rollen samen met de scopes en rollen van de gebruiker.

Tenant access rights

Tenant access rights zijn zowel scopes als rollen.

Als het scope dat je nodig hebt niet is gedefinieerd op Control API foxids_control_api, kun je het scope toevoegen.

:track[xxxx] specificeert een omgeving via de technische naam. Bijvoorbeeld een Test omgeving met technische naam hsgm7je5 is :track[hsgm7je5] en een Production omgeving met technische naam - is :track[-].

Scope / role Access
Toegang tot alles in de tenant, niet tot master tenant data.
foxids:tenant read, create, update, delete
foxids:tenant.read read
foxids:tenant.create create
foxids:tenant.update update
foxids:tenant.delete delete
Toegang tot basis tenant elementen:
  • Mijn profiel gebruikt in Control Client.
  • Roep de ReadCertificate API aan om een JWT met certificaatinformatie van een X509 certificaat te krijgen.
    •
    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
    Toegang tot alles in alle omgevingen binnen een tenant, niet inclusief de master omgeving.
    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
    Toegang tot alles in een specifieke omgeving binnen een tenant. `xxxx` is de technische omgeving naam.
    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
    Alle usage logs in alle omgevingen binnen een tenant, niet inclusief de master omgeving. Niet van toepassing in de master tenant.
    foxids:tenant:track:usage read
    Usage logs in een specifieke omgeving binnen een tenant. Niet van toepassing in de master tenant.
    foxids:tenant:track[xxxx]:usage read
    Alle audit logs in alle omgevingen binnen een tenant, niet inclusief de master omgeving.
    foxids:tenant:track:audit read
    Audit logs in een specifieke omgeving binnen een tenant.
    foxids:tenant:track[xxxx]:audit read
    Alle logs in alle omgevingen binnen een tenant, niet inclusief de master omgeving.
    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
    Logs in een specifieke omgeving.
    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
    Alle gebruikers in alle omgevingen binnen een tenant, niet inclusief de master omgeving.
    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
    Alle gebruikers in een specifieke omgeving binnen een tenant.
    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
    Alle app registraties en authenticatiemethoden in alle omgevingen binnen een tenant, niet inclusief de master omgeving.
    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
    Alle app registraties en authenticatiemethoden in een specifieke omgeving binnen een tenant.
    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

    Master tenant access rights

    Master tenant access rights zijn zowel scopes als rollen.

    Scope / role Access
    Toegang tot master tenant data
    Kan tenants opsommen, aanmaken en verwijderen maar niet in andere tenants kijken.
    foxids:master read, create, update, delete
    foxids:master.read read
    foxids:master.create create
    foxids:master.update update
    foxids:master.delete delete
    Audit log in de master tenant.
    foxids:master:audit read
    Usage log in de master tenant.
    foxids:master:usage read

    Uw privacy

    We gebruiken cookies om uw ervaring op onze websites te verbeteren. Klik op de knop 'Alle cookies accepteren' om akkoord te gaan met het gebruik van cookies. Om niet-noodzakelijke cookies te weigeren, klikt u op 'Alleen noodzakelijke cookies'.

    Bezoek onze privacyverklaring voor meer informatie