Migração de usuários

O Authio importa a partir de um arquivo: o export que o seu provedor atual entrega, ou uma lista em CSV ou JSON gerada por você. Toda importação é ensaiada primeiro — nada é gravado até você ler um relatório do que aconteceria — e cada linha passa pelas mesmas validações, cotas de plano e permissões de uma mudança feita no console. Linhas que já existem são puladas, então rodar o mesmo arquivo de novo é seguro.

As senhas chegam como os hashes que o sistema antigo guardava. O Authio confere esse hash no formato original na primeira vez que a pessoa entra e o substitui por um hash nativo, então ninguém precisa redefinir uma senha que a origem permitiu exportar. O Authio nunca chama o seu provedor antigo: o que não está no arquivo precisa ser recriado.

Escolha um caminho

As outras listas principais — realms, papéis, escopos, clients, provedores de identidade, consumers, segredos de API, chaves de assinatura e webhooks — têm a mesma ação Importar de arquivo, com o mesmo fluxo de ensaiar e depois aplicar.

Origens aceitas

Do Keycloak, o Authio lê o realm, os papéis, os client scopes, os clients, os provedores de identidade e os usuários. Ele não importa segredos de clients nem de provedores de identidade, que todo export do Keycloak mascara, nem os clients internos do próprio Keycloak, como account e security-admin-console, nem os escopos padrão. Clients públicos chegam exigindo PKCE.

Migre de um provedor

1. 1

   Exporte do provedor atual

   Gere o arquivo que a tabela acima descreve para a sua origem. Trate-o como uma credencial: ele pode conter hashes de senha e outros segredos.

2. 2

   Leia o export

   Abra Migração, escolha o seu provedor em De onde você está vindo? e depois escolha o arquivo ou cole o conteúdo dele. Ler o export traduz o arquivo para um pacote Authio sem gravar nada e mostra quantas linhas foram entendidas em cada seção.

   Se algo precisar de correção, escolha Baixar como pacote, edite o JSON e envie de novo com Um pacote Authio como origem.

3. 3

   Ensaie a importação

   Ensaiar a importação roda a importação inteira sem gravar nada. O relatório conta o que seria criado, o que já existe e o que não pôde ser usado, por seção e linha a linha, com a linha do arquivo e o motivo de cada problema.

4. 4

   Aplique a importação

   Aplicar a importação roda as mesmas validações de verdade e relata linha a linha o que foi criado. Ele só libera depois de um ensaio exatamente do conteúdo que está na tela, e fica bloqueado enquanto o ensaio tiver recusado parte do arquivo, enquanto o seu papel não puder criar algum tipo de recurso que o arquivo traz, ou quando não houver nada a criar.

As seções são aplicadas em ordem de dependência — realms, papéis, escopos, clients, provedores de identidade, consumers, segredos, chaves de assinatura, webhooks, usuários — qualquer que seja a ordem no arquivo. Cada seção exige a permissão de escrita do próprio recurso. Se uma execução real parar no meio, ensaie de novo antes de aplicar: parte do arquivo pode já ter sido gravada.

Importe um arquivo de usuários

Em Usuários, escolha Importar de arquivo e depois escolha um arquivo ou cole o conteúdo. Com um realm em escopo, e opcionalmente um client, toda linha é criada ali, diga o arquivo o que disser. Com todos os realms em escopo, cada linha informa o próprio realm e, opcionalmente, o client.

As colunas do CSV são casadas pelo nome, não pela posição, então a ordem em que saem do sistema antigo não importa:

email,username,firstname,lastname,emailconfirmed,roles,passwordhash
ana@acme.com,ana,Ana,Souza,true,support;billing,$2a$12$R9h/cIPz0gi.URNNX3kh2OPST9/PgBkqquzi.Ss7KIUgO2t0jWMUW
bruno@acme.com,bruno,Bruno,Lima,false,support,

Escolha Ensaiar, leia o relatório e depois Aplicar. Quando o seu plano inclui o consultor de IA, o ensaio também diz o que a IA vê no arquivo, por exemplo muitas linhas parecidas de um jeito que sugere engano; veja Authio AI.

Pelas suas próprias ferramentas, POST /api/v1/admin/realms/{realm}/clients/{client}/users/import recebe o arquivo em content, isJson para dizer que é JSON, dryRun, que vale true a menos que você envie false, e sendEmail, também true por padrão, em que false não manda e-mail a ninguém que o arquivo criar. Veja a Admin API.

Formatos de hash de senha

Só formatos que se descrevem sozinhos — com o algoritmo, os parâmetros e o sal dentro da própria string — podem ser conferidos:

Antes de virar a chave

• As pessoas importadas recebem e-mail, a menos que você desligue. Cada uma é criada como uma conta feita no console: um link de confirmação quando o endereço não está confirmado, e, se estiver, uma mensagem dizendo que a conta está pronta. Para criá-las sem escrever a ninguém, desligue Enviar e-mail às pessoas criadas na importação ou na migração; o e-mail de confirmação pode ser reenviado depois na página de cada pessoa. Caso contrário, marque emailconfirmed nos endereços que o sistema antigo já tinha verificado, e avise as pessoas da mudança.
• Os webhooks disparam. Cada pessoa criada gera um user_created nos webhooks do client. Garanta que os seus receptores aguentam uma rajada, ou cadastre os endpoints depois da importação.
• As cotas valem. Os usuários contam no seu plano conforme são criados. Quando a cota acaba, a seção de usuários para e o dono da conta é avisado uma vez.
• Arquivos grandes. Um envio aceita até 50.000 linhas; divida exports maiores.
• Contas existentes ficam como estão. Uma linha cujo endereço já tem conta é pulada, não atualizada.
• Segredos. Segredos de clients e de provedores de identidade não vêm do Keycloak; configure-os no Authio antes de as suas aplicações migrarem.
• As sessões não migram. Tokens e sessões do provedor antigo não valem no Authio. Quando uma aplicação passa a apontar para o novo emissor, como https://authio.api.hyperio.tech/realms/acme, as pessoas entram de novo.
• Apague os arquivos. Exports e arquivos de importação podem conter hashes e segredos em texto puro. Remova-os quando a migração terminar.

Próximos passos