Configurar atributos do grupo de usuários

Você obtém um conjunto de atributos padrão, chamado "atributos padrão", com todos os grupos de usuários. Você também pode adicionar atributos personalizados à definição do grupo de usuários no Console de gerenciamento da AWS. Este tópico descreve esses atributos detalhadamente e oferece dicas sobre como configurar seu grupo de usuários.

Os atributos são informações que ajudam a identificar usuários individuais, como nome, e-mail e número de telefone.

Nem todas as informações sobre seus usuários serão armazenadas nos atributos. Por exemplo, os dados do usuário que são alterados com frequência, como estatísticas de uso ou pontuações de jogos, devem ser mantidos em um repositório de dados separado, como o Amazon Cognito Sync ou o Amazon DynamoDB.

Atributos padrão

A seguir estão os atributos padrão de todos os usuários de um grupo de usuários. Eles são implementados seguindo a especificação do OpenID Connect.

• address

• birthdate

• email

• family_name

• gender

• given_name

• locale

• middle_name

• name

• nickname

• phone_number

• picture

• preferred_username

• profile

• updated_at

• website

• zoneinfo

Estes atributos estão disponíveis como atributos opcionais para todos os usuários. Para tornar um atributo necessário, marque a caixa de seleção ao lado do atributo.

nota

Quando um atributo padrão é marcado como necessário, um usuário não poderá se registrar, a menos que seja fornecido um valor para o atributo. Os administradores podem criar usuários sem fornecer valores de atributos obrigatórios usando a API AdminCreateUser. Um atributo não pode ser alternado entre obrigatório e não obrigatório após a criação de um grupo de usuários.

Os valores de atributo padrão e personalizados podem ser qualquer string de até 2.048 caracteres, por padrão, mas alguns valores de atributo, como updated_at, têm restrições de formatação. Somente email e phone podem ser verificados.

nota

Na especificação, os atributos são chamados de membros.

Aqui estão algumas observações adicionais sobre alguns dos campos acima.

e-mail

Os valores de endereço de e-mail podem ser verificados.

Um administrador com as permissões de conta da AWS adequadas pode alterar o e-mail do usuário, além de marcá-lo como verificado. Para fazer isso, use a API AdminUpdateUserAttributes ou o comando admin-update-user-attributes da CLI para alterar o atributo email_verified para true.

phone

Um número de telefone é necessário se a autenticação multifator (MFA) do SMS for habilitada. Para obter mais informações, consulte Adicionar MFA a um grupo de usuários.

Os valores de número de telefone podem ser verificados.

Um administrador com as permissões de conta da AWS adequadas pode alterar o número de telefone do usuário, além de marcá-lo como verificado. Para fazer isso, use a API AdminUpdateUserAttributes ou o comando admin-update-user-attributes da CLI para alterar o atributo phone_number_verified para true.

Importante

Os números de telefone devem seguir estas regras de formatação: um número de telefone deve começar com um sinal de mais (+), seguido imediatamente pelo código do país. Um número de telefone pode conter apenas o sinal + e os dígitos. Você deve remover quaisquer outros caracteres de um número de telefone, como parênteses, espaços ou traços (-) antes de enviar o valor ao serviço. Por exemplo, um número de telefone dos Estados Unidos deve seguir este formato: [phone].

preferred_username

O preferred_username não pode ser selecionado como necessário e como um alias. Se preferred_username for um alias, um usuário poderá adicionar o valor de atributo assim que for confirmado usando a API UpdateUserAttributes.

 

Para editar atributos padrão

1. Na guia Attributes, escolha os atributos necessários ao registro do usuário. Se um atributo for necessário e um usuário não fornecer esse atributo, o usuário não poderá se registrar.

   Importante

   Não será possível alterar esses requisitos depois que o grupo de usuários for criado.

2. Para criar um alias de e-mail, número de telefone, endereço ou nome de usuário preferencial, escolha Alias. Para obter mais informações sobre alias, consulte Visão geral dos aliases.

3. Crie Atributos personalizados.

 

Nomes de usuário e nomes de usuário preferenciais

O valor de username é um atributo separado; não equivale ao atributo name. Um username sempre é necessário para registrar um usuário; ele não pode ser alterado depois que um usuário é criado.

Os desenvolvedores podem usar o atributo preferred_username para dar aos usuários um nome de usuário que eles podem alterar. Para obter mais informações, consulte Visão geral dos aliases.

Se o seu aplicativo não exigir um nome de usuário, não é necessário solicitar que os usuários o forneçam. O aplicativo pode criar um nome de usuário exclusivo para os usuários no plano de fundo. Isso é útil se, por exemplo, deseja-se que os usuários se registrem e façam login com um endereço de e-mail e senha. Para obter mais informações, consulte Visão geral dos aliases.

username deve ser exclusivo em um grupo de usuários. username pode ser reutilizado, mas somente depois que tiver sido excluído e não estiver mais em uso.

Visão geral dos aliases

É possível permitir que os usuários finais façam login com vários identificadores usando aliases.

Por padrão, os usuários fazem login com nome de usuário e senha. O nome de usuário é um valor fixo que os usuários não podem alterar. Se você marcar um atributo como alias, os usuários poderão fazer login usando esse atributo em vez do nome de usuário. Os atributos de endereço de e-mail, o número de telefone e nome de usuário preferencial podem ser marcados como aliases.

Por exemplo, se um e-mail e um telefone forem selecionados como aliases para um grupo de usuários, os usuários desse grupo poderão fazer login usando seu nome de usuário, endereço de e-mail ou número de telefone juntamente com a senha.

nota

Você poderá optar por entrar ou cadastrar-se usando letras minúsculas ou maiúsculas em um alias quando configurar seu grupo de usuários para indistinção de maiúsculas e minúsculas em nome de usuário. Para obter mais informações, consulte CreateUserPool em Referência de API do Grupos de usuários do Amazon Cognito.

Se o e-mail for selecionado como um alias, um nome de usuário não poderá coincidir com um formato de e-mail válido. Da mesma forma, se o número de telefone for selecionado como alias, um nome de usuário que corresponda a um padrão de número de telefone válido não será aceito pelo serviço para esse grupos de usuários.

nota

Os valores de alias devem ser exclusivos em um grupo de usuários. Se um alias for configurado para um endereço de e-mail ou número de telefone, o valor fornecido poderá apresentar o estado verificado em apenas uma conta. Durante o cadastro, se um endereço de e-mail ou um número de telefone for fornecido como alias de uma conta diferente que já tenha sido usada, o registro será bem-sucedido. No entanto, quando um usuário tentar confirmar a conta com esse e-mail (ou número de telefone) e informar o código válido, um erro AliasExistsException será lançado. O erro informa ao usuário que já existe uma conta com esse e-mail (ou número de telefone). Nesse ponto, o usuário pode abandonar a criação da nova conta e tentar redefinir a senha para a conta antiga. Se o usuário continuar criando a nova conta, o aplicativo chamará a opção ConfirmSignUp API com o forceAliasCreation. Isso moverá o alias da conta anterior para a conta recém-criada e marcará o atributo não verificado na conta anterior.

Os números de telefone e os endereços de e-mail só se tornam aliases ativos para um usuário depois que os números de telefone e os endereços de e-mail forem verificados. Portanto, recomendamos que você escolha a verificação automática dos endereços de e-mail e números de telefone caso use-os como aliases. O atributo preferred_username oferece aos usuários a experiência de alterar seu nome de usuário quando, na verdade, o valor real do nome de usuário para um usuário não pode ser alterado.

Se desejar ativar essa experiência de usuário, envie o novo valor do username como preferred_username e selecione preferred_username como um alias. Assim, os usuários poderão fazer login com o novo valor fornecido.

Se preferred_username for selecionado como alias, o valor só poderá ser fornecido quando uma conta for confirmada. O valor não pode ser fornecido durante o registro.

Uso de aliases para simplificar o cadastro e o login do usuário

Na guia Attributes do console, é possível escolher se deseja permitir que o usuário se cadastre com um endereço de e-mail ou número de telefone como seu nome de usuário.

nota

A configuração não pode ser alterada depois que o grupo de usuários é criado.

Opção 1: o usuário se cadastra com o Nome de usuário e faz login com o Nome de usuário ou o Alias

Neste caso, o usuário se cadastra com um nome de usuário. Além disso, é possível, opcionalmente, permitir que os usuários façam login com um ou mais dos seguintes aliases:

• um endereço de e-mail verificado

• um número de telefone verificado

• um nome de usuário preferencial

Estes aliases podem ser alterados após o cadastro do usuário.

Use as etapas a seguir para configurar o grupo de usuários no console para permitir login com um alias.

Para configurar um grupo de usuários para login com um alias

1. Na guia Attributes (Atributos), em How do you want your end users to sign-up and sign-in? (Como você deseja que seus usuários finais se inscrevam e façam login?), selecione Username (Nome de usuário).

2. Escolha uma das seguintes opções:

   • Also allow sign in with verified email address: isso permite que os usuários façam login com o seu endereço de e-mail.

   • Also allow sign in with verified phone number: isso permite que os usuários façam login com o seu número de telefone.

   • Also allow sign in with preferred username: isso permite que os usuários façam login com um nome de usuário preferencial. Este nome de usuário não pode ser alterado pelo usuário.

Opção 2: o usuário se cadastra e faz login com um E-mail ou Número de telefone em vez do Nome de usuário

Neste caso, o usuário se cadastra com um endereço de e-mail ou um número de telefone como nome de usuário. É possível escolher se deseja permitir que o cadastro seja feito apenas com endereços de e-mail, apenas com números de telefone ou ambos.

O e-mail ou o número de telefone deve ser exclusivo e não deve estar em uso por outro usuário. Ele não precisa ser verificado. Depois que o usuário se cadastrou usando um e-mail ou um número de telefone, o usuário não pode criar uma nova conta com o mesmo e-mail ou número de telefone; só é possível reutilizar a conta existente (e redefinir a senha, se necessário). No entanto, o usuário pode alterar o e-mail ou o número de telefone para um novo e-mail ou número de telefone; se ainda não estiver em uso, ele se torna o novo nome de usuário.

nota

Se os usuários se cadastrarem com um endereço de e-mail como nome de usuário, será possível alterar o nome de usuário para outro endereço de e-mail; não será possível alterar para um número de telefone. Se os usuários se cadastrarem com um número de telefone, será possível alterar o nome de usuário para outro número de telefone; não será possível alterar para um endereço de e-mail.

Use as etapas a seguir para configurar o grupo de usuários no console para permitir o cadastro e login com um e-mail ou número de telefone.

Para configurar um grupo de usuários para o cadastro e login com um e-mail ou número de telefone

1. Na guia Attributes (Atributos), em How do you want your end users to sign-up and sign-in? (Como você deseja que seus usuários finais se inscrevam e façam login?), selecione Email address or phone number (Endereço de e-mail ou número de telefone).

2. Escolha uma das seguintes opções:

   • Allow email addresses: isso permite que o usuário se cadastre com um e-mail como nome de usuário.

   • Allow phone numbers: isso permite que o usuário se cadastre com um número de telefone como nome de usuário.

   • Allow both email addresses and phone number (users can choose one): isso permite que o usuário use um endereço de e-mail ou um número de telefone como nome de usuário durante o cadastro.

nota

Não é necessário marcar e-mail ou número de telefone como atributos necessários para o grupo de usuários.

Para implementar a opção 2 no aplicativo

1. Chame a API CreateUserPool para criar o grupo de usuários. Defina o parâmetro UserNameAttributes como phone_number, email ou phone_number | email.

2. Chame a API SignUp e envie um endereço de e-mail ou número de telefone para o parâmetro username da API. Esta API faz o seguinte:

   • Se a string username estiver no formato válido de e-mail, o grupo de usuários ocupa automaticamente o atributo email do usuário com o valor username.

   • Se a string username estiver no formato válido de número de telefone, o grupo de usuários ocupa automaticamente o atributo phone_number do usuário com o valor username.

   • Se o formato da string username não estiver no formato de um e-mail ou número de telefone, a API SignUp lança uma exceção.

   • A API SignUp gera um UUID persistente para o usuário e o utiliza como o atributo imutável nome de usuário internamente. Este UUID possui o mesmo valor reivindicado pelo sub no token de identidade do usuário.

   • Se a string username contém um endereço de e-mail ou número de telefone que já está em uso, a API SignUp lança uma exceção.

É possível usar um endereço de e-mail ou número de telefone como um alias em vez do nome de usuário em todas as APIs, exceto na API ListUsers. Ao chamar a ListUsers, pesquise pelos atributos email ou phone_number; se pesquisar por username, é necessário fornecer o nome de usuário real, e não um alias.

Atributos personalizados

Você pode adicionar até 25 atributos personalizados ao grupo de usuários. Você pode especificar um comprimento mínimo e/ou máximo para os atributos personalizados. No entanto, o comprimento máximo para qualquer atributo personalizado não pode ultrapassar 2.048 caracteres.

Cada atributo personalizado:

• Pode ser definido como uma string ou um número.

• Não pode ser obrigatório.

• Não pode ser removido ou alterado depois de adicionado ao grupo de usuários.

• Pode ter um nome com um comprimento de caracteres que está dentro do limite aceito pelo Amazon Cognito. Para obter mais informações, consulte Cotas no Amazon Cognito.

nota

No código e nas configurações de regra de Controle de acesso com base em função, os atributos personalizados requerem o prefixo custom: para que sejam distinguidos dos atributos padrão.

Para adicionar um atributo personalizado usando o console

1. Na barra de navegação à esquerda, selecione Atributos.

2. Para cada novo atributo:

   1. Escolha Adicionar outro atributo em Deseja adicionar atributos personalizados?.

   2. Escolha as propriedades de cada atributo personalizado, como Tipo (string ou número), Nome, Comprimento mín e Comprimento máx.

   3. Para que o usuário possa alterar o valor de um atributo personalizado após ele ter sido fornecido pelo usuário, selecione Mutable (Mutável).

Permissões de atributo e escopos

Você pode definir permissões de leitura e gravação por aplicativo para cada atributo de usuário. Isso permite a você controlar quais aplicativos poderão ver e/ou modificar cada um dos atributos armazenados para seus usuários. Por exemplo, você pode ter um atributo personalizado que indique se um usuário é um cliente pagante ou não. Seus aplicativos poderão ver esse atributo, mas não poderão modificá-lo diretamente. Em vez disso, você atualizará o atributo usando uma ferramenta administrativa ou um processo em segundo plano. As permissões de atributos de usuário podem ser definidas no console do Amazon Cognito, na API ou na ILC. Por padrão, todos os novos atributos personalizados só estarão disponíveis depois que você definir permissões de leitura e gravação para eles.

Para definir ou alterar as permissões de atributo usando o console

1. Na barra de navegação à esquerda, selecione App clients (Clientes de aplicativo).

2. Escolha Mostrar detalhespara o cliente de aplicativo que você deseja atualizar.

3. Escolha Set the attribute read and write permissions for each attribute (Definir as permissões de leitura e gravação para cada atributo).

4. Escolha Save app client changes (Salvar alterações do cliente do aplicativo).

Repita essas etapas para cada cliente de aplicativo usando o atributo personalizado.

Os atributos podem ser marcados como legíveis ou graváveis para cada aplicativo. Isso se aplica aos atributos padrão e personalizados. Um aplicativo pode ler um atributo marcado como legível e pode gravar um atributo marcado como gravável. Se um aplicativo tentar atualizar um atributo não gravável, o aplicativo receberá uma exceção NotAuthorizedException. Um aplicativo que chama GetUser receberá apenas os atributos que podem ser lidos por esse aplicativo. A pós-autenticação emitida por token de ID contém somente solicitações correspondentes aos atributos legíveis. Os atributos obrigatórios em um grupo de usuários são sempre graváveis. Se você, usando a ILC ou a API de administração, definir um atributo gravável e não fornecer atributos obrigatórios, uma exceção InvalidParameterException será lançada.

Você pode alterar os escopos e as permissões de atributo após ter criado o grupo de usuários.