FoxIDs Control

O FoxIDs é configurado através do FoxIDs Control, que consiste em Control Client e Control API. O Control Client e a API são protegidos pelo FoxIDs, e o Control Client usa a Control API.

A Control API contém toda a funcionalidade de configuração. Por isso, é possível automatizar a configuração através de integração com a 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

Configure um conjunto de ambientes, um para cada um dos seus ambientes, por exemplo dev, qa e prod.

Crie um ou mais ambientes, não coloque configuração no ambiente master.

Cada ambiente contém um repositório de utilizadores e um método de autenticação login por predefinição.

Pode adicionar registos de aplicações e métodos de autenticação OpenID Connect, OAuth 2.0 e SAML 2.0.

Um ambiente contém um certificado primário e possivelmente um certificado secundário no separador Certificates. É possível trocar entre o certificado primário e o secundário se ambos estiverem configurados, dependendo do tipo de contentor do certificado.

As propriedades do ambiente podem ser configuradas clicando no ícone de definições no canto superior direito.

• Sequence lifetime é o tempo máximo de vida do fluxo de login de um utilizador do início ao fim.
• O FoxIDs protege contra tentativas de adivinhar passwords através de max failing logins, tempo de vida da contagem de falhas de login e observation period.
• Os requisitos de password são configurados em relação a comprimento, complexidade e password risk.
• É possível alojar o FoxIDs num iframe a partir de domínios permitidos.
• Pode enviar emails com o seu próprio tenant SendGrid ao adicionar um endereço de email personalizado e a chave SendGrid.

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.