Migrar do Auth0 para o FoxIDs

Transfira os inícios de sessão do Auth0 para o FoxIDs com a abordagem adequada a cada ligação. Importe utilizadores da base de dados com hashes de palavras-passe bcrypt ou permita que escolham uma nova palavra-passe. Importe os utilizadores sem palavra-passe e ative códigos de utilização única. Para inícios de sessão sociais e empresariais, configure métodos de autenticação FoxIDs que confiem nos fornecedores de identidade externos.

Este guia técnico abrange a configuração de aplicações, importação de utilizadores e associação de contas para ligações Auth0 de base de dados, sem palavra-passe por e-mail/SMS, sociais e empresariais.

Para utilizadores da base de dados e sem palavra-passe, converta a exportação Auth0 revista num ficheiro CSV e utilize o FoxIDs Seed Tool para carregar os utilizadores em massa no FoxIDs. Os exemplos CSV abaixo mostram os campos para cada abordagem de migração.

Escolha um método para cada grupo antes de preparar a importação:

Os utilizadores importados com e sem palavra-passe autenticam-se localmente no FoxIDs. Os utilizadores sociais e empresariais autenticam-se no fornecedor de identidade ligado.

Preparar o destino e a aplicação

Um ambiente de teste dedicado permite experimentar a migração com um pequeno grupo antes da passagem para produção. Os passos de configuração são:

1. Se pretender um domínio personalizado, configure-o e verifique-o no tenant antes de configurar aplicações e fornecedores de identidade externos. Utilize os URL FoxIDs resultantes durante toda a migração. Alterar o domínio mais tarde exige atualizar as configurações externas, incluindo os URL de autoridade ou metadados das aplicações e os URL de retorno e de fim de sessão dos fornecedores.
2. Cada ambiente tem um método de autenticação Login predefinido chamado login. Personalize a imagem de marca e interface de início de sessão para obter o aspeto desejado e ajuste as opções de início de sessão aos utilizadores importados.
3. Crie os métodos de autenticação que ligam os utilizadores sociais e empresariais aos seus fornecedores externos, seguindo a secção de migração correspondente abaixo.
4. Configure a aplicação, os URL de redirecionamento permitidos, o comportamento de fim de sessão e as API que aceitam os seus tokens de acesso.

O FoxIDs Cloud disponibiliza envio de e-mail e SMS para definir palavras-passe, iniciar sessão sem palavra-passe e usar autenticação multifator (MFA), consoante o plano FoxIDs Cloud escolhido.

Configure as definições MFA necessárias e a inscrição dos utilizadores; as importações descritas não transferem inscrições MFA do Auth0. Para contas com palavra-passe, reveja os requisitos de comprimento, complexidade e validade: importar um hash ignora a validação da política durante a importação, mas a política escolhida aplica-se no início de sessão.

A configuração de aplicações é um trabalho separado da importação de utilizadores. Reveja emissor, audiência, âmbitos, claims e validação de tokens, além de pressupostos do SDK Auth0, Actions, pertença a organizações e atribuições de funções. Reimplemente o comportamento exigido pela aplicação. O guia geral de migração abrange o inventário mais alargado das aplicações e os passos de implementação.

Exportar um grupo definido de utilizadores Auth0

Siga as instruções de exportação em massa de utilizadores Auth0. Selecione explicitamente a ligação de origem com connection_id; uma exportação API sem este campo inclui todas as ligações. Mantenha distinguíveis os utilizadores da base de dados, sem palavra-passe e federados durante a conversão.

Utilize uma exportação compatível com JSON (NDJSON) como origem da conversão. As exportações CSV do Auth0 aplicam escapes adicionais e não são entradas prontas para o FoxIDs Seed Tool. Uma pequena exportação permite experimentar a conversão para o formato CSV do Seed Tool.

Inclua user_id, blocked e os identificadores e estados de verificação usados por cada ligação: email e email_verified, ou phone_number e phone_verified para utilizadores SMS. Para contas sociais, empresariais e associadas, conserve fornecedor, ligação e ID de utilizador de identities para a associação de contas. Exporte apenas os dados necessários após a migração e conserve o tenant e a ligação de origem junto da exportação. Consulte o esquema de perfil de utilizador Auth0 ao selecionar campos.

Obter hashes para manter as palavras-passe

Solicite a exportação dos hashes de palavras-passe ao Auth0 Support. É separada da exportação dos dados de utilizadores. O guia de exportação de hashes do Auth0 descreve os registos NDJSON e o campo passwordHash. O exemplo $2b$10$... identifica a variante bcrypt 2b e o custo 10.

Associe cada hash ao utilizador correto através do tenant de origem, ligação à base de dados e ID de utilizador.

Mapear dados de utilizadores e preservar contas das aplicações

O FoxIDs cria o seu próprio ID persistente para os utilizadores locais importados. Importar um user_id Auth0 como claim personalizado não o torna no ID de utilizador FoxIDs nem preserva automaticamente o claim sub da aplicação. Para inícios de sessão sociais e empresariais, verifique a identidade recebida diretamente do fornecedor e o sujeito emitido pelo FoxIDs para a aplicação.

Para manter o ID de utilizador Auth0 como sub da aplicação, importe-o como claim personalizado, por exemplo legacy_auth0_user_id. No método de autenticação Login, configure uma transformação de claims Map com ação Replace claim, claim de entrada legacy_auth0_user_id e claim de saída sub. A aplicação recebe então o ID Auth0 como sub, enquanto o ID persistente FoxIDs permanece inalterado.

Mantenha uma associação entre a identidade de origem, a nova identidade FoxIDs e a conta existente da aplicação. Por exemplo, a identidade Auth0 antiga e a nova identidade FoxIDs devem apontar para o mesmo registo de cliente durante a transição, sem criar dois registos. Verifique o sujeito efetivamente emitido para cada aplicação e atualize a associação de contas quando necessário. Não associe contas apenas porque os endereços de e-mail coincidem.

Para importar utilizadores locais, utilize o seguinte mapeamento:

Migrar inícios de sessão sociais e empresariais

Crie um método de autenticação FoxIDs para cada ligação social ou empresarial, estabelecendo confiança diretamente com o fornecedor externo. Os utilizadores mantêm as suas contas e credenciais nesse fornecedor.

1. Identifique o fornecedor e a configuração de cada ligação Auth0. Utilize o guia de integração do fornecedor adequado, como Google, Facebook ou Microsoft Entra ID, e selecione o método suportado OpenID Connect, SAML 2.0 ou WS-Federation.
2. Registe ou configure o FoxIDs no fornecedor. Troque as definições de cliente ou os metadados de federação e configure os URL de retorno e fim de sessão indicados no guia. Conserve a configuração Auth0 durante a transição.
3. Permita o novo método de autenticação na aplicação FoxIDs. Configure Home Realm Discovery para que os utilizadores possam escolher o fornecedor ou ser encaminhados pelas regras configuradas.
4. Reconcilie a identidade do fornecedor com a conta existente da aplicação. Os identificadores devolvidos num início de sessão de teste podem ser comparados com a conta de origem; um ID de utilizador Auth0 não é necessariamente o identificador devolvido diretamente ao FoxIDs. Se precisar de guardar claims ou atribuições de acesso por utilizador no FoxIDs, configure e aprovisione utilizadores externos.
5. Recrie as restrições anteriormente aplicadas pelo Auth0, incluindo utilizadores bloqueados e acesso a organizações.

O fluxo esperado é aplicação → FoxIDs → fornecedor de identidade externo → FoxIDs → aplicação. O FoxIDs emite os tokens da aplicação após o fornecedor autenticar o utilizador.

Pode experimentar cada ligação iniciando a sessão na aplicação, selecionando o fornecedor e concluindo o respetivo fluxo. Isto permite observar MFA, conta e permissões da aplicação e comportamento de fim de sessão.

Migrar utilizadores sem palavra-passe

Importe utilizadores das ligações Auth0 sem palavra-passe por e-mail ou SMS como utilizadores internos FoxIDs sem palavra-passe. Configure o início de sessão sem palavra-passe para continuarem com códigos de utilização única. Quem recebia um link mágico Auth0 passa a introduzir um código na página de início de sessão já aberta. Assim não é necessário seguir links de início de sessão em e-mails ou SMS.

1. Ative e-mail ou telefone como identificador de início de sessão no método FoxIDs Login e ative Passwordless with email (one-time password) ou Passwordless with SMS (one-time password) conforme adequado.
2. Para um método dedicado a utilizadores sem palavra-passe, selecione Disable password authentication e desative a definição/reposição de palavra-passe por e-mail e SMS. O fluxo mantém-se centrado nos códigos de utilização única.
3. Importe os utilizadores omitindo Password e todos os campos de hash. Mantenha SetPasswordEmail, SetPasswordSms e ChangePassword em false para não exigir que escolham uma palavra-passe. Preserve os estados de verificação e desativação e os claims necessários.

Para experimentar o acesso sem palavra-passe, pode iniciar sessão com o e-mail ou telefone de um utilizador de teste importado e introduzir o código recebido. Um código válido permite a um utilizador ativo continuar pela MFA necessária até à aplicação; códigos inválidos ou expirados e contas desativadas não concedem acesso.

Por exemplo, este CSV do Seed Tool importa um utilizador fictício sem palavra-passe por e-mail:

Email;EmailVerified;SetPasswordEmail;SetPasswordSms;ChangePassword;DisableAccount
alice@example.com;true;false;false;false;false

Para utilizadores SMS, substitua Email e EmailVerified por Phone e PhoneVerified, com o número e estado de verificação revistos. Aplica-se o mesmo procedimento de carregamento. O utilizador continua sem palavra-passe após um início de sessão sem palavra-passe bem-sucedido.

Importar utilizadores com hashes de palavras-passe bcrypt

O FoxIDs aceita cadeias bcrypt completas com prefixos $2a$, $2b$ ou $2y$ e custos de 4 a 16. Para utilizadores cujos hashes estão fora do formato suportado, utilize a definição de palavra-passe por e-mail.

Ative o início de sessão por e-mail e a autenticação com palavra-passe no método FoxIDs Login para estes utilizadores.

Copie cada valor Auth0 passwordHash associado para a coluna CSV PasswordHash e defina PasswordHashAlgorithm como bcrypt. Preserve toda a cadeia, incluindo variante, custo e salt incorporado. Já está codificada para bcrypt. Consulte os formatos de hash de palavras-passe e o contrato de importação de palavras-passe da Control API.

Para o Seed Tool, utilize as colunas seguintes. Esta é uma conta de teste sintética; substitua-a pela exportação revista:

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

Omita Password e PasswordHashSalt. Mantenha SetPasswordEmail, SetPasswordSms e ChangePassword em false se o utilizador deve continuar com a palavra-passe existente. Preserve os estados de desativação e verificação, claims e requisitos MFA do mapeamento revisto. Inclua PasswordLastChanged se conhecer a data de alteração original, em segundos Unix; caso contrário, o FoxIDs regista a hora de importação para verificar a antiguidade da palavra-passe.

O mesmo procedimento de carregamento aplica-se a todas as importações de utilizadores locais. O aprovisionamento em massa pode substituir uma conta existente e as suas credenciais, independentemente do formato escolhido.

Com um utilizador de teste importado, pode experimentar iniciar sessão com a palavra-passe original e depois com uma incorreta. A original autentica o utilizador segundo a política configurada e a MFA; uma palavra-passe incorreta ou conta desativada não concede acesso. Também pode experimentar a alteração e recuperação da palavra-passe na interface Login configurada.

O hash importado mantém-se bcrypt após o início de sessão. Uma palavra-passe definida ou alterada no FoxIDs é guardada no formato PBKDF2 predefinido. O histórico continua a impedir a reutilização conforme a política escolhida, incluindo quando um hash bcrypt antigo é conservado após uma reposição.

Importar utilizadores para definir a palavra-passe

Utilize este método para contas que escolherão uma nova palavra-passe em vez de importar um hash. Ative início de sessão por e-mail, autenticação com palavra-passe e definição por e-mail no método FoxIDs Login. Para utilizadores que devem continuar sem palavra-passe, siga Migrar utilizadores sem palavra-passe.

A importação prepara as contas. A definição da palavra-passe ocorre quando cada utilizador inicia sessão, não durante a importação.

Converta os registos revistos num ficheiro UTF-8 para o FoxIDs Seed Tool. Os cabeçalhos distinguem maiúsculas de minúsculas e o separador é um ponto e vírgula. O exemplo contém utilizadores fictícios com e-mails anteriormente verificados; a segunda conta continua desativada:

Email;EmailVerified;SetPasswordEmail;DisableAccount;RequireMultiFactor;Claims
alice@example.com;true;true;false;true;"[{""Claim"":""legacy_auth0_user_id"",""Values"":[""auth0|demo-001""]}]"
blocked@example.com;true;true;true;true;"[{""Claim"":""legacy_auth0_user_id"",""Values"":[""auth0|demo-002""]}]"

SetPasswordEmail=true seleciona a definição da palavra-passe com confirmação por e-mail. Omita Password e todas as colunas de hash. Não é necessária uma palavra-passe temporária partilhada nem ChangePassword neste fluxo. RequireMultiFactor=true é a política escolhida no exemplo e requer a configuração dos métodos MFA correspondentes.

Disponibilize o claim de exemplo legacy_auth0_user_id apenas às aplicações que dele necessitem através do tratamento de claims configurado.

Carregar utilizadores e examinar o resultado

Utilize este procedimento para utilizadores com hashes bcrypt, sem palavra-passe e que escolherão uma palavra-passe no primeiro início de sessão, com os campos adequados ao método escolhido.

O Seed Tool divide os campos por pontos e vírgulas; campos entre aspas não podem conter pontos e vírgulas nem quebras de linha. Utilize as operações de utilizadores da Control API se os valores exigirem uma representação de importação mais completa.

1. Transfira e configure o Seed Tool para o ambiente pretendido. Defina SeedSettings.UsersSvcPath como o ficheiro CSV convertido.
2. Execute o Seed Tool e selecione U para carregar os utilizadores em massa.
3. Registe os novos ID de utilizador no mapeamento de migração.

Pode experimentar o carregamento com um CSV de poucos utilizadores num ambiente de teste. O Seed Tool apresenta as contagens de sucessos e falhas. No FoxIDs Control pode examinar identificadores, estado de desativação, claims e indicadores de definição da palavra-passe dos utilizadores importados.

O Seed Tool usa aprovisionamento em massa, que pode substituir utilizadores existentes em vez de os combinar com segurança. Verifique colisões antes do carregamento. Não volte a executar o ficheiro completo depois de os utilizadores definirem palavras-passe ou obterem acesso: a substituição pode remover credenciais e estado e criar novos ID. Reconcilie uma importação parcial antes de tentar novamente; trate alterações posteriores com atualizações específicas e revistas dos utilizadores.

Definição da palavra-passe no primeiro início de sessão

Para um utilizador importado ativo com SetPasswordEmail=true, o fluxo esperado é:

1. O utilizador abre a aplicação e inicia sessão através do FoxIDs Login.
2. O FoxIDs identifica o utilizador pelo endereço de e-mail e envia um código de confirmação.
3. O utilizador submete o código e uma nova palavra-passe que cumpre a política do FoxIDs.
4. O FoxIDs verifica o e-mail, guarda a palavra-passe e limpa os indicadores de definição. O início de sessão prossegue pelas etapas MFA necessárias antes de regressar à aplicação.

Importar um utilizador não envia o e-mail de definição. Os inícios de sessão seguintes usam a nova palavra-passe FoxIDs, não a anterior do Auth0. Se um utilizador não conseguir receber o código, utilize um processo de recuperação aprovado que verifique a identidade.

Pode explorar o fluxo com um utilizador de teste seguindo os passos acima. Estes cenários mostram os resultados esperados:

Implementar e manter uma via de reversão

A migração pode ser implementada por aplicação ou grupo de utilizadores. Os utilizadores podem continuar pelo URL habitual com o fluxo configurado: palavra-passe existente, definição de palavra-passe, código de utilização única ou fornecedor externo existente.

Antes de cada importação em produção, reconcilie os utilizadores criados, alterados, bloqueados ou eliminados desde a exportação. Defina um breve período sem alterações ou outro processo de reconciliação controlado. Não substitua utilizadores já migrados para aplicar estas alterações.

Monitorize a entrega de e-mail e SMS, falhas na definição de palavras-passe, falhas de início de sessão e problemas de associação de contas. Nos imports de hashes, tenha em conta alterações de palavras-passe no Auth0 após a exportação, para os utilizadores não chegarem com uma palavra-passe diferente do hash importado. A reversão depende da disponibilidade da configuração Auth0 anterior. Pode experimentar restaurá-la para uma aplicação de teste e observar o regresso ao fluxo Auth0.

Uma palavra-passe definida no FoxIDs não é sincronizada de volta para o Auth0. A reversão usa, por isso, as credenciais ainda guardadas no Auth0. Defina como os utilizadores criados apenas no FoxIDs obterão acesso pelo Auth0 se for necessário reverter. Para acessos sem palavra-passe e federados, conserve as definições de entrega e ligações a fornecedores Auth0 necessárias para restaurar o fluxo anterior. Retire a integração antiga e elimine os ficheiros exportados conservados apenas após a aceitação do acesso às contas e do suporte operacional.

Documentação relacionada

• Visão geral da migração
• Carregar muitos utilizadores
• Operações de utilizadores da Control API
• Início de sessão e Home Realm Discovery
• Fornecedor de e-mail
• Aplicativos