FoxIDs Control

O FoxIDs é configurado através do FoxIDs Control, que consiste no Control Client e no Control API. O Control Client e o Control API são protegidos pelo FoxIDs, e o Control Client utiliza o Control API.

Control API contém todas as funcionalidades de configuração. Por conseguinte, é possível automatizar a configuração através da integração com o Control API.

FoxIDs Control Client

O Control Client é uma aplicação Blazor WebAssembly (WASM).

Abra o seu Control Client em FoxIDs.com.

Tenant e ambiente master

Se usar FoxIDs.com, o seu tenant é criado durante o registo.

Se implementar o FoxIDs em self-hosting, obtém acesso ao tenant master. Crie primeiro um tenant para conter a sua configuração de segurança. A maioria das instalações só precisa de um, mas pode configurar um número ilimitado de tenants.

Um tenant contém um ambiente master, a partir do qual todo o tenant é configurado. O ambiente master contém um repositório de utilizadores e, na criação, apenas um utilizador administrador.

Normalmente não deve alterar a configuração do ambiente master nem adicionar novos métodos de autenticação ou registos de aplicações, mas isso é possível. Pode, por exemplo, ao adicionar um método de autenticação, obter single sign-on (SSO) para o ambiente master.

Criar utilizadores administradores

É possível criar mais utilizadores administradores no ambiente master. Um utilizador torna-se administrador ao adicionar o papel de administrador foxids:tenant.admin, como mostrado abaixo.

Crie um utilizador:

1. Abra o ambiente master
2. Selecione o separador Users
3. Clique em Create User
4. Adicione a informação do utilizador e clique em Create.

Conceder acesso ao utilizador

O acesso é concedido com papéis. Os scopes só são necessários quando um cliente pede um token para a Control API; o Control Client já pede o scope necessário em foxids_control_api, por isso normalmente apenas atribui papéis ao utilizador no ambiente master.

Para permitir que uma pessoa inicie sessão no Control Client e veja dados de configuração:

1. Crie ou abra o utilizador no ambiente master (separador Users).
2. Adicione o papel base foxids:tenant:basic.read (necessário para o Control Client carregar o perfil e ferramentas auxiliares).
3. Decida o que o utilizador pode ver:
   • Para limitar a visibilidade a um ambiente, adicione foxids:tenant:track[vh2csjt4].read (substitua vh2csjt4 pelo nome técnico do ambiente).
   • Para permitir todos os ambientes, adicione foxids:tenant.read.
4. Adicione os papéis operacionais de que o utilizador necessita em cada ambiente. Exemplos: foxids:tenant:track[vh2csjt4]:user para gerir utilizadores, foxids:tenant:track[vh2csjt4]:party para gerir aplicações e métodos de autenticação.

Control Client vs apenas API:

• O Control Client (UI interativa) lê dados de perfil e listas de ambientes, além da API específica que pretende gerir. Por isso precisa de foxids:tenant:basic.read mais um papel de leitura de ambiente (foxids:tenant:track[main].read ou foxids:tenant.read) juntamente com os seus papéis de ação.
• Chamadores apenas API podem ser mais restritos. Se um serviço backend apenas chamar a user API para o ambiente vh2csjt4, o papel foxids:tenant:track[vh2csjt4]:user é suficiente, juntamente com o pedido do scope correspondente quando usar client credentials. Os papéis extra de leitura não são necessários porque não há dados de UI para carregar.

Ambientes

Um ambiente é um Identity Provider independente com o seu próprio repositório de utilizadores, certificado, métodos de autenticação, registos de aplicações e definições. Utilize ambientes separados para isolar fases como desenvolvimento, teste e produção.

Consulte Ambientes para obter informações sobre a separação, o conteúdo, a criação e a configuração de ambientes.

FoxIDs Control API

A Control API é uma REST API com descrição online da interface Swagger (OpenAPI) e Swagger UI.

Se alojar o FoxIDs em self-hosting, o documento Swagger (OpenAPI) fica exposto no FoxIDs Control em .../api/swagger/v2/swagger.json e a Swagger UI em .../api/swagger.

Nomenclatura da Control API:

• Um ambiente chama-se track
• Um registo de aplicação chama-se downparty
• Um método de autenticação chama-se upparty

O URL da Control API contém variáveis para o nome do tenant e do track, isto é, o nome do ambiente onde pretende operar: .../{tenant_name}/{track_name}/.... Substitua {tenant_name} pelo nome do tenant e {track_name} pelo nome técnico do ambiente. Se gerar um proxy a partir do documento Swagger (OpenAPI), essas variáveis são fornecidas como parâmetros de entrada.

Por exemplo, para ler um registo de aplicação OpenID Connect no FoxIDs Cloud com o nome técnico some_oidc_app, faça a chamada HTTP GET https://control.foxids.com/api/{tenant_name}/{track_name}/!oidcdownparty?name=some_oidc_app, substituindo as variáveis pelo nome do seu tenant e o nome técnico do ambiente.

Pode chamar a Control API como serviço/daemon usando um cliente OAuth 2.0 com client credentials ou no contexto de um utilizador através de um cliente OpenID Connect.

Os passos abaixo criam um cliente OAuth 2.0 e concedem-lhe direitos de acesso de nível administrativo através de scopes e papéis.

Crie um cliente OAuth 2.0 no FoxIDs Control Client:

1. Selecione o ambiente master no cabeçalho.
2. Selecione o separador Applications.
3. Clique em New Application.
4. Clique em Backend Application.
   1. Adicione um Name, por exemplo My API Client.
   2. Clique em Register.
   3. Copie o Client ID e o Client secret.
   4. Clique em Close.
5. Clique no registo do cliente na lista para o abrir.
6. Na secção Resource and scopes, que concede ao cliente acesso ao seu tenant:
   1. Clique em Add Resource and scope e adicione o recurso foxids_control_api.
   2. Clique em Add Scope e adicione o scope foxids:tenant.
7. Selecione Show advanced.
8. Na secção Issue claims, que concede ao cliente o papel de administrador do tenant:
   1. Clique em Add Claim e adicione o claim role.
   2. Clique em Add Value e adicione o valor de claim foxids:tenant.admin.
9. Clique em Update.

Depois execute um pedido OAuth 2.0 Client Credentials Grant para obter um access token para a Control API.

Substitua {tenant_name}, {track_name}, {client_id} e {client_secret}. Altere o domínio se estiver em self-hosting.

Exemplo Postman Esta coleção Postman autentica com o cliente OAuth 2.0 My API Client e devolve os utilizadores do ambiente configurado, isto é, o track.

Crie um ficheiro JSON de coleção Postman, por exemplo foxids_control_api.postman_collection.json, com o conteúdo abaixo. Substitua {tenant_name}, {track_name}, {client_id} e {client_secret}. Altere os domínios (foxids.com e control.foxids.com) se estiver em self-hosting.

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

Exemplo de pedido HTTP Este exemplo HTTP autentica como o cliente OAuth 2.0 My API Client com o 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

Resposta JSON do token:

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
}

O access_token é usado para chamar a Control API.

Exemplo de código C# Este exemplo C# autentica como o cliente OAuth 2.0 My API Client com o 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);

Depois chame a Control API com o access token num header Authorization Bearer, conforme definido pelo standard OAuth 2.0 Bearer Token (RFC 6750).

Exemplo de código C# Este exemplo C# mostra como adicionar o access token ao HttpClient e ler o registo de aplicação OpenID Connect some_oidc_app, isto é, o nome técnico.

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

Direitos de acesso à API

Isto mostra a configuração da Control API no ambiente master de um tenant com o conjunto predefinido de scopes que concede acesso aos dados do tenant.

Pode adicionar mais scopes para alargar os direitos de acesso à Control API por ambiente e obter configurações least-privilege.

O acesso à Control API é limitado por scopes e papéis. Existem duas famílias de scopes: foxids:master concede acesso a dados do master tenant e foxids:tenant concede acesso a dados do tenant. O recurso da Control API foxids_control_api é definido no ambiente master de cada tenant, e os scopes configurados concedem acesso aos dados desse tenant através da Control API.

O acesso de um scope pode ser restringido adicionando mais elementos separados por dois pontos e pontos. A notação com ponto limita a um sub-papel específico e é usada tanto em scopes como em papéis. Os chamadores têm de apresentar um ou mais scopes e papéis correspondentes.

Cada direito de acesso é definido tanto como scope como como papel. Isto permite conceder ou limitar acesso tanto ao nível do cliente como ao nível do utilizador. Os direitos de acesso são hierárquicos e o cliente e o utilizador não precisam de ter scopes e papéis correspondentes.

O papel de administrador foxids:tenant.admin concede acesso a todos os dados de um tenant e aos dados do master tenant; equivale a ter os papéis foxids:tenant e foxids:master.

Um cliente pede um scope ao especificar o recurso e o scope separados por dois pontos. Por exemplo, para pedir o scope foxids:tenant:track:party.create, o cliente pede foxids_control_api:foxids:tenant:track:party.create.

Se um pedido for negado devido a direitos de acesso insuficientes, é registado um trace item com os possíveis scopes e papéis autorizadores juntamente com os scopes e papéis reais do utilizador.

Direitos de acesso do tenant

Os direitos de acesso do tenant são tanto scopes como papéis.

Se o scope de que precisa não estiver definido na Control API foxids_control_api, pode adicioná-lo.

:track[xxxx] especifica um ambiente pelo nome técnico. Por exemplo, um ambiente Test com o nome técnico hsgm7je5 é :track[hsgm7je5] e um ambiente Production com o nome técnico - é :track[-].

Direitos de acesso do master tenant

Os direitos de acesso do master tenant são tanto scopes como papéis.

Documentação relacionada

• Começar a utilizar o FoxIDs Control
• Configuração do ambiente
• Recursos de desenvolvimento do FoxIDs
• Registo, auditoria e utilização
• Carregamento em massa de utilizadores