A ferramenta SPMigrateUsers para alterar identidades de conta no SharePoint 2010

Artigo original publicado em 03 de junho de 2012, domingo

Às vezes no SharePoint você quer ou precisa alterar uma identidade de conta. O melhor exemplo disso são as declarações de SAML. Em quase todos os meus exemplos, eu uso o email como declaração de identidade dos usuários. Primeiro porque a maioria das pessoas tem um email e segundo porque a maioria entende o que é um email. Só que de vez em quando sou pego no contrapé porque a pessoa pode mudar o email. Quando você muda o email, obviamente todas as permissões são eliminadas. Para ser sincero, não acho que essa é uma situação corriqueira, senão para começar eu não usaria o email. Só que eu posso garantir que eventualmente isso acontece, então o que fazer quando o SharePoint inteiro está protegido por endereços de email?

O segredo para controlar isso está em uma postagem de blog que fiz antes sobre a interface do IMigrateUserCallback:  https://blogs.msdn.com/b/sharepoint_br/archive/2011/03/10/migrando-contas-de-usu-225-rio-das-declara-231-245-es-do-windows-para-as-declara-231-245-es-saml.aspx. Nessa postagem, eu descrevo como migrar identidades usando essa interface e dou um exemplo de como converter uma identidade de declarações do Windows em uma identidade de declarações de SAML. O que decidi fazer foi simplesmente escrever um pequeno aplicativo do Windows que permite inserir as credenciais que você quer alterar e implementa as alterações por você. Essa ferramenta simples serve única e exclusivamente para fazer essas alterações, mas é fácil obter seu código-fonte (que estou incluindo nesta postagem) e modificá-lo para oferecer recursos mais criativos, como ler uma lista de usuários de um arquivo ou banco de dados e fazer comparações você mesmo.

Outra vantagem dessa ferramenta é sua versatilidade em vários cenários. Assim, ela não só permite converter entre um email e outro, como também converter entre um nome de grupo e outro. Essa é outra situação em que alguns colegas da área Operacional me dizem "Olha só, que tal você usar SIDs para os nomes de grupo (ou seja, declarações de Função no SAML) porque renomeando o grupo, o SID continuará sendo o mesmo. Isso pode até ser verdade, mas volto a lembrar dois pontos: primeiro, não acho que isso aconteça com frequência; segundo, quantas pessoas querem começar a digitar nomes de SID de grupo e adicioná-los a grupos do SharePoint (se você responder que quer, recomendo fazer análise); e, terceiro, SIDs não significam nada fora do seu Active Directory local – tão logo você migrar para um serviço baseado em nuvem como Azure, Google, Yahoo, Facebook etc., seu SID será tão inútil quanto [escolha um "desadjetivo" qualquer].

E mais outra vantagem especial dessa ferramenta é que ela não restringe o usuário a fazer alterações em um único tipo de provedor. Quer alterar um grupo do Windows para uma declaração de função SAML? Pois vá em frente. Quer alterar uma declaração de identidade de SAML para um usuário associado de FBA? Fique à vontade. Quer alterar uma função de FBA para um grupo de AD? Sem problema. Você entendeu, né? Tentei todo tipo de combinação de diferentes “usuários” e “grupos” entre diferentes provedores e até agora tudo foi convertido com êxito nas duas direções.

A ferramenta em si parece ser bem simples de usar; a seguir está uma imagem dela:

Quando o aplicativo é iniciado pela primeira vez, ele carrega uma lista de todos os aplicativos Web. Para cada aplicativo Web, ele popula as duas caixas de combinação abaixo dele com uma lista de todos os provedores que estão sendo usados nesse aplicativo Web. Se você tiver vários provedores SAML ou vários provedores FBA, cada um será listado na caixa suspensa. Bastará escolher os provedores de origem e de destino para fazer a migração. Na seção Valor da Declaração (Claim Value), digite o valor que deseja migrar e o que deseja migrar para ele. Digite o valor nos campos de edição Valor de Texto sem Formatação (Plain Text Value) e clique no botão de declaração da identidade (à esquerda) ou no botão de declaração do grupo (à direita). A descrição no texto oferece uma explicação completa, e o texto nos botões muda para que faça mais sentido dependendo do provedor de identidade que está sendo usado.

Por exemplo, vamos supor que você esteja usando somente autenticação SAML e queira migrar o email “steve@contoso.com” para “stevep@contoso.com”. Você escolheria seu aplicativo Web e o provedor de autenticação SAML seria selecionado por padrão em cada caixa suspensa. Na seção Valores Anteriores (Before Values), você digitaria “steve@contoso.com” no campo de edição Valor de Texto sem Formatação (Plain Text Value) e clicaria no botão Declaração de ID (ID Claim); isso colocaria o valor de declaração codificado correto no campo de edição Valor Codificado (Encoded Value). Depois você digitaria “stevep@contoso.com” no campo de edição Valor de Texto sem Formatação da seção Valores Posteriores (After Values). Você clicaria no botão Declaração de ID novamente; ele colocaria o valor correto na caixa de edição Valor Codificado (OBSERVAÇÃO: na imagem anterior, o botão na seção Valores Posteriores informa “Usuário” (User) em vez de “Declaração de ID” porque nesse exemplo ele está migrando das declarações de SAML para as declarações do Windows). Depois que todos os seus valores tiverem sido fornecidos, bastará clicar no botão Migrar (Migrate) para concluir o processo; uma caixa de mensagem aparecerá informando quando a migração estiver concluída.

No processo de testes entre vários aplicativos Web diferentes e vários tipos de autenticação diferentes, deparei-me com alguns problemas que gostaria de comentar aqui para preveni-los. Uma vez eu obtive uma mensagem de erro de Acesso Negado ao tentar migrar os usuários de um determinado aplicativo Web. Até hoje eu não sei a causa do problema, por isso a minha melhor explicação é que aquele aplicativo Web estava com falha, mas não sei bem qual é porque todos os outros quatro ou cinco aplicativos Web que testei em meu farm funcionaram perfeitamente.

Em uma segunda ocasião, era informado que a migração foi concluída com êxito, mas eu não conseguia fazer logon como usuário migrado. Examinei minuciosamente e constatei que a conta da qual eu estava migrando não permitia push pela função IMigrateUserCallback (ou seja, isso é um problema do SharePoint, e não um problema de código com esse aplicativo). Se isso acontecer com você, recomendo usar o código-fonte e o Visual Studio para analisar passo a passo o depurador para garantir que a conta da qual você está migrando está sendo chamada. Infelizmente havia um único usuário associado de FBA que ficou preso no limbo.

Por fim, uma última orientação é não entrar em desespero se você migrar uma conta de um valor para outro, fizer logon como novo usuário e vir o nome da conta antigo etc. no controle de boas-vindas no canto superior direito da página. A função de migração simplesmente muda o nome da conta. Se as outras informações do usuário mudarem também, desde que você atualize os perfis de usuário, as informações corretas deverão ser enviadas por push a todas as coleções de sites na próxima sincronização com o sistema de perfis.

E por hoje é só – aproveite e espero ter ajudado. Como eu disse antes, o código-fonte na íntegra está incluído, por isso fique à vontade para se divertir com ele e modificar conforme necessário para o seu cenário.

Esta é uma postagem de blog traduzida. Consulte o artigo original em The SPMigrateUsers Tool for Changing Account Identities in SharePoint 2010