Carregar muitos utilizadores

Utilize o FoxIDs Seed Tool para carregar utilizadores de um CSV num ambiente FoxIDs como utilizadores internos. Cada utilizador pode ser carregado com:

  • Nenhuma palavra-passe, para iniciar sessão sem palavra-passe com código de utilização única por e-mail ou SMS.
  • Nenhuma palavra-passe e a obrigação de escolher uma no primeiro início de sessão, confirmado por e-mail ou SMS.
  • Uma palavra-passe conhecida em texto simples, cujo hash o Seed Tool calcula antes do carregamento por predefinição.
  • Um hash de palavra-passe FoxIDs pré-calculado e o respetivo salt separado.
  • Um hash de palavra-passe Auth0 bcrypt, permitindo manter a palavra-passe existente.

A Control API aceita até 1 000 utilizadores por pedido, dos quais no máximo 100 podem conter palavras-passe em texto simples. Os hashes pré-calculados contam para o limite de 1 000 utilizadores. O Seed Tool usa lotes até 1 000 utilizadores com o cálculo de hashes no cliente predefinido. Carrega vários lotes para ficheiros maiores. Também pode usar diretamente as operações de utilizadores da Control API.

Exemplo de tempo de carregamento para 50.000 utilizadores

Scenario Users Batch size Approx. total time
Without passwords 50,000 1,000 ~2 minutes
With passwords 50,000 100 ~2 hours
Password hashes pre-calculated on client 50,000 1,000 ~5 minutes

Os tempos são aproximados e dependem da máquina cliente, da rede e da infraestrutura.

Carregar utilizadores com palavras-passe demora mais porque tem de ser calculado um hash da palavra-passe para cada utilizador, e esta operação é intencionalmente demorada por motivos de segurança. O tempo de carregamento pode ser melhorado calculando os hashes das palavras-passe no cliente antes de carregar os utilizadores.

Carregar com a seed tool

O Seed Tool em tools/FoxIDs.SeedTool lê um CSV e carrega os utilizadores em massa no ambiente FoxIDs configurado através da Control API. Defina o caminho em SeedSettings.UsersSvcPath e selecione U para carregar. A ferramenta também permite eliminar utilizadores em massa.

Por predefinição, o Seed Tool pré-calcula hashes de palavras-passe para palavras-passe em texto simples antes do carregamento. Os hashes FoxIDs ou bcrypt fornecidos são carregados sem alterações quando Password está vazio ou omitido.

Ficheiro CSV

Guarde o CSV em UTF-8, com campos separados por ;. O texto pode estar entre aspas. O analisador divide pelos pontos e vírgulas, pelo que os campos não podem conter pontos e vírgulas nem quebras de linha, mesmo entre aspas.

Pode encontrar ficheiros CSV de exemplo aqui. (Por exemplo, veja caracteres UTF-8 em claims no ficheiro password-claims-3-test-users.csv, que demonstra suporte multi-língua / de caracteres alargados.)

A primeira linha do ficheiro CSV contém os headers, que são case sensitive. Pode optar por usar todos os headers ou um subconjunto dos headers e alterar a ordem dos headers. Os headers:

  • Email
  • Phone
  • Username
  • ConfirmAccount
  • EmailVerified
  • PhoneVerified
  • Password
  • PasswordHashAlgorithm
  • PasswordHash
  • PasswordHashSalt
  • ChangePassword
  • PasswordLastChanged
  • SetPasswordEmail
  • SetPasswordSms
  • DisableAccount
  • Claims
  • RequireMultiFactor

O número de headers e de elementos em cada linha tem de corresponder.

Este exemplo carrega um utilizador sem palavra-passe. Omita Password e todas as colunas de hash e mantenha SetPasswordEmail e SetPasswordSms em false. Ative o início de sessão sem palavra-passe com o fornecedor de e-mail ou SMS correspondente. Preserve o estado de verificação conhecido de cada utilizador.

Email;EmailVerified;SetPasswordEmail;SetPasswordSms
passwordless@example.com;true;false;false

Este exemplo CSV usa os cabeçalhos Email e SetPasswordEmail para carregar utilizadores que devem escolher uma palavra-passe com confirmação por e-mail no primeiro início de sessão. O email é depois marcado como verificado.

Email;SetPasswordEmail
u1@somedomain.test;true
u2@somedomain.test;true
u3@somedomain.test;true

Este exemplo CSV inclui um nome de utilizador e marca o e-mail e telefone fornecidos como verificados. As palavras-passe são definidas com um código de confirmação por e-mail ou SMS.

Email;Phone;Username;EmailVerified;PhoneVerified;SetPasswordEmail;SetPasswordSms
u1@somedomain.test;;u1;true;true;true;false
;+4422222222;u2;true;true;false;true
u3@somedomain.test;+4433333333;u3;true;true;true;false

Este exemplo CSV carrega utilizadores com palavras-passe em texto simples e claims. O último utilizador é carregado como desativado.

Email;Phone;Username;ConfirmAccount;EmailVerified;PhoneVerified;Password;ChangePassword;SetPasswordEmail;SetPasswordSms;DisableAccount;Claims;RequireMultiFactor
u1@somedomain.test;+4411111111;u1;false;true;true;"My1Password!";false;false;false;false;"[{""Claim"": ""role"", ""Values"": [""admin""]}]";false
u2@somedomain.test;+4422222222;u2;false;true;true;"My2Password!";true;false;false;false;"[{""Claim"": ""role"", ""Values"": [""admin""]}, {""Claim"": ""customer_id"", ""Values"": [""1234""]}]";true
u3@somedomain.test;+4433333333;u3;false;true;true;"My3Password!";false;false;false;true;"[{""Claim"": ""role"", ""Values"": [""admin"", ""user""]}]";false

Se fornecer hashes pré-calculados, use as colunas PasswordHashAlgorithm e PasswordHash e deixe Password vazio (ou remova-o). Inclua PasswordHashSalt para P2HS512:10; omita-o para bcrypt, cuja cadeia completa inclui o salt. Consulte os formatos de importação de palavras-passe suportados. Pode preservar a data de alteração original com PasswordLastChanged (segundos Unix). Quando uma palavra-passe ou hash é fornecido sem PasswordLastChanged, o carregamento regista a hora atual.

Deve adicionar palavras-passe e claims com a notação ;"";. Se uma palavra-passe contiver o símbolo ", este é escaped, por exemplo a palavra-passe My"Password, que se torna ;"My""Password";

Os claims são adicionados com uma estrutura JSON sem quebras de linha e os símbolos " são escaped.

[
  { "Claim": "role", "Values": ["admin", "user"] },
  { "Claim": "customer_id", "Values": ["1234"] }
]

Importar hashes de palavras-passe Auth0 bcrypt

Converta os dados Auth0 revistos e os hashes correspondentes no formato CSV do Seed Tool. Coloque cada valor Auth0 passwordHash completo em PasswordHash e defina PasswordHashAlgorithm como bcrypt. Omita Password e PasswordHashSalt; o bcrypt inclui o salt na cadeia do hash.

Por exemplo, esta conta de teste sintética usa o formato Auth0 $2b$10$:

Email;EmailVerified;PasswordHashAlgorithm;PasswordHash;SetPasswordEmail;SetPasswordSms;ChangePassword;DisableAccount
auth0.alice@example.com;true;bcrypt;$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC;false;false;false;false

O repositório inclui tools/FoxIDs.SeedTool/user_upload_csv_files/auth0-bcrypt-3-test-users.csv com hashes sintéticos de custos 10 e 12, campos de hash com e sem aspas e uma conta desativada. Estes hashes de teste usam a palavra-passe QAZ!234wsx. Substitua os dados de exemplo pelos utilizadores revistos e respetivos hashes antes da migração.

Defina UsersSvcPath como o CSV convertido e depois execute o Seed Tool e selecione U. Mantenha os indicadores de definição e alteração em false se os utilizadores devem conservar as palavras-passe e ative o acesso com palavra-passe no método Login. Pode experimentar a importação num ambiente de teste e iniciar sessão com a palavra-passe original de um utilizador importado.

Consulte Migrar do Auth0 para o FoxIDs para exportação, associação de hashes a utilizadores, formatos suportados e associação de contas.

Transferir e configurar a seed tool

Primeiro transfira o ficheiro FoxIDs.SeedTool-x.x.x-win-x64.zip para Windows ou FoxIDs.SeedTool-x.x.x-linux-x64.zip para Linux a partir da release do FoxIDs e extraia a seed tool.

A seed tool é configurada no ficheiro appsettings.json.

O acesso para carregar utilizadores é concedido no seu ambiente master.

Crie um cliente OAuth 2.0 da seed tool no FoxIDs Control Client:

Isto vai conceder à seed tool acesso total ao seu tenant; para privilégios mínimos veja Direitos de acesso da Control API.

  1. Inicie sessão no seu tenant (em self-hosted, o tenant principal)
  2. Selecione o ambiente master (no seletor de ambiente no topo ao centro)
  3. Selecione o separador Applications
  4. Clique em New Application
  5. Clique em Backend Application
    1. Selecione Show advanced
    2. Adicione um Name, por exemplo Seed tool
    3. Altere o Client ID para foxids_seed
    4. Clique em Register
    5. Guarde a Authority.
    6. Guarde o Client secret.
    7. Clique em Close
  6. Clique na aplicação na lista para a abrir
  7. Na secção Resource and scopes
    1. Remova o visto de Default resource 'foxids_seed' for the application itself
    2. Clique em Add Resource and scope e adicione o recurso foxids_control_api
    3. Em seguida, clique em Add Scope e adicione o scope foxids:tenant
  8. Selecione Show advanced
  9. Na secção Issue claims
    1. Clique em Add Claim e adicione o claim role
    2. Em seguida, clique em Add Value e adicione o valor de claim foxids:tenant
  10. Clique em Update

FoxIDs Control Client - master seed tool client

Adicione ao ficheiro de configuração da seed tool o seu endpoint FoxIDs Control API, tenant e environment, bem como a Authority, o Client secret e o caminho do ficheiro CSV.

"SeedSettings": {
    "FoxIDsControlEndpoint": "https://control.foxids.com", // self-hosted "https://control.yyyyxxxx.com" or local development https://localhost:44331
    "Tenant": "xxxxxx",
    "Environment": "xxxxxx",
    "Authority": "https://id.foxids.com/zzzzz/master/foxids_seed/", // custom domain, self-hosted or local development "https://https://localhost:44331/zzzzz/master/foxids_seed/"
    "ClientId": "foxids_master_seed",
    "ClientSecret": "xxxxxx",
    "Scope": "foxids_control_api:foxids:tenant",
    "UsersSvcPath": "c:\\... xxx ...\\users.csv"
}

Executar a seed tool e carregar os utilizadores

  1. Inicie um Command Prompt
  2. Execute a seed tool com SeedTool.exe
  3. Clique em U para começar a carregar utilizadores

O carregamento pode demorar algum tempo dependendo do número de utilizadores.

O Seed Tool apresenta contagens de sucessos e falhas e os utilizadores importados ficam disponíveis no FoxIDs Control. Pode experimentar carregar um pequeno CSV num ambiente de teste e examinar os utilizadores resultantes. O carregamento em massa pode substituir utilizadores e credenciais existentes; verifique colisões de identificadores antes do carregamento e reconcilie resultados parciais antes de tentar novamente.