Atributos de grupo de usuários

Os atributos são informações que ajudam a identificar usuários específicos, como nome, endereço de e-mail e número de telefone. Um novo grupo de usuários tem um conjunto padrão de atributos. Você também pode adicionar atributos personalizados à definição do grupo de usuários no AWS Management Console. Este tópico descreve esses atributos detalhadamente e oferece dicas sobre como configurar seu grupo de usuários.

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

Atributos padrão

O Amazon Cognito atribui a todos os usuários o seguinte conjunto de atributos padrão com base na 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 obrigatório, durante o processo de criação do grupo de usuários, marque a caixa de seleção Required (Obrigatório) ao lado do atributo.

nota

Quando você marcar um atributo padrão como Required (Obrigatório), o usuário não poderá se inscrever, a menos que forneça um valor para o atributo. Para criar usuários e não fornecer valores aos atributos obrigatórios, os administradores podem usar a API AdminCreateUser. Após a criação de um grupo de usuários, não é possível alternar um atributo entre obrigatório e não obrigatório.

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

nota

Alguns documentos e padrões se referem a atributos como membros.

Veja algumas outras observações sobre alguns desses campos.

e-mail

Os usuários e administradores podem verificar valores de endereço de e-mail.

Um administrador com permissões adequadas da Conta da AWS pode alterar o endereço de e-mail do usuário, além de marcá-lo como verificado. Marque um endereço de e-mail como verificado com a API AdminUpdateUserAttributes ou o comando admin-update-user-attributes da AWS Command Line Interface (AWS CLI). Com esse comando, o administrador pode alterar o atributo email_verified para true. Você também pode editar um usuário na guia Users (Usuários) do AWS Management Console para marcar um endereço de e-mail como verificado.

phone

O usuário deverá fornecer um número de telefone se a autenticação multifator (MFA) de SMS estiver ativa. Para mais informações, consulte Adicionar MFA a um grupo de usuários.

Os usuários e administradores podem verificar valores de número de telefone.

Um administrador com permissões adequadas na Conta da AWS pode alterar o número de telefone do usuário, além de marcá-lo como verificado. Marque um endereço de e-mail como verificado com a API AdminUpdateUserAttributes ou o comando admin-update-user-attributes da AWS CLI. Com esse comando, o administrador pode alterar o atributo phone_number_verified para true. Você também pode editar um usuário na guia Users (Usuários) do AWS Management Console para marcar um número de telefone como verificado.

Importante

Os números de telefone devem seguir estas regras de formatação: devem começar com um sinal de mais (+), seguido imediatamente do código do país. Um número de telefone pode conter apenas o sinal + e os dígitos. Remova 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

Você pode selecionar preferred_username conforme necessário ou como um alias, mas não ambos. Se preferred_username for um alias, você poderá usar a API UpdateUserAttributes para adicionar o valor de atributo assim que confirmar o usuário.

Exibir atributos obrigatórios

Siga o procedimento abaixo a fim de exibir atributos obrigatórios para um determinado grupo de usuários.

nota

Não é possível alterar atributos obrigatórios após a criação de um grupo de usuários.

Original console

Para exibir atributos obrigatórios

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Selecione Manage User Pools.

3. Na página Your User Pools (Seus grupos de usuários), escolha um grupo de usuários.

4. No menu de navegação à esquerda, escolha Attributes (Atributos).

5. Em Which standard attributes are required? (Quais atributos padrão são obrigatórios?), veja os atributos obrigatórios de seu grupo de usuários.

New console

Para exibir atributos obrigatórios

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Escolha User Pools (Grupos de usuários).

3. Escolha um grupo de usuários existente da lista.

4. Escolha a guia Sign-up experience (Experiência de cadastro).

5. Na seção Required attributes (Atributos obrigatórios), veja os atributos obrigatórios de seu grupo de usuários.

Nome de usuário e nome de usuário preferido

O valor de username é um atributo separado; não equivale ao atributo name. Cada usuário tem um atributo username. O Amazon Cognito gera automaticamente um nome de usuário para usuários federados. Você deve fornecer um atributo username para criar um usuário nativo no diretório do Amazon Cognito. Após a criação de um usuário, não é possível alterar o valor do atributo username.

Os desenvolvedores podem usar o atributo preferred_username para atribuir aos usuários um nome de usuário que eles podem alterar. Para mais informações, consulte Aliases.

Se sua aplicação não exigir um nome de usuário, não será 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 pode ser útil se você desejar que os usuários se inscrevam e façam login com um endereço de e-mail e senha. Para mais informações, consulte Aliases.

username deve ser exclusivo em um grupo de usuários. username pode ser reutilizado, mas somente depois que você o excluir e ele não estiver mais em uso.

Aliases

Se você quiser, seus usuários podem usar aliases para inserir outros atributos quando fizerem login. 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 mudar. Se você marcar um atributo como alias, os usuários poderão fazer login usando esse atributo em vez de o nome de usuário. Você pode marcar os atributos de endereço de e-mail, número de telefone e nome de usuário preferido como aliases. Por exemplo, se você selecionar um endereço de e-mail e número de telefone como aliases para um grupo de usuários, os usuários desse grupo poderão fazer login usando o respectivo nome de usuário, endereço de e-mail ou número de telefone com a senha.

nota

Ao configurar seu grupo de usuários para indistinção de maiúsculas e minúsculas, o usuário poderá usar letras minúsculas ou maiúsculas para se cadastrar ou fazer login com o alias. Para obter mais informações, consulte CreateUserPool na Referência da API de grupos de usuários do Amazon Cognito.

Se você selecionar o endereço de e-mail como um alias, o Amazon Cognito não aceitará um nome de usuário que corresponda a um formato de endereço de e-mail válido. Da mesma forma, se você selecionar o número de telefone como alias, o Amazon Cognito não aceitará um nome de usuário para esse grupos de usuários que corresponda a um formato de número de telefone válido.

nota

Os valores de alias devem ser exclusivos em um grupo de usuários. Se configurar um alias para um endereço de e-mail ou número de telefone, o valor que você fornecer poderá apresentar o estado verificado em apenas uma conta. Durante o cadastro, se o usuário fornecer um endereço de e-mail ou número de telefone como um valor de alias e outro usuário já tiver usado esse valor, 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 inserir o código válido, o Amazon Cognito retornará um erro AliasExistsException. Esse erro indica ao usuário que já existe uma conta com esse endereço de e-mail (ou número de telefone). Nesse ponto, o usuário pode abandonar a tentativa de criar a nova conta e, em vez disso, tentar redefinir a senha para a conta antiga. Se o usuário continuar criando a nova conta, sua aplicação deverá chamar a API ConfirmSignUp com a opção forceAliasCreation. ConfirmSignUp com forceAliasCreation move o alias da conta anterior para a conta recém-criada e marca o atributo não verificado na conta anterior.

Os números de telefone e os endereços de e-mail só se tornarão aliases ativos para um usuário depois que você os verificar. Portanto, é recomendável escolher a verificação automática dos endereços de e-mail e números de telefone se você os usar como aliases.

Ative o atributo preferred_username para que seu usuário possa alterar o nome de usuário que ele usa para fazer login enquanto o valor de atributo username não mudar. Se desejar configurar essa experiência de usuário, envie o novo valor de username como preferred_username e escolha preferred_username como alias. Assim, os usuários poderão fazer login com o novo valor que eles inseriram. Se você selecionar preferred_username como alias, o usuário só poderá fornecer o valor quando confirmar uma conta. Ele não poderá fornecer o valor durante o registro.

Como usar aliases para simplificar o cadastro e o acesso do usuário

Ao criar um grupo de usuários, você pode escolher se deseja que o usuário se cadastre com um endereço de e-mail ou número de telefone como nome de usuário.

nota

Após a criação de um grupo de usuários, não é possível alterar essa configuração.

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

Quando o usuário se cadastra com um nome de usuário, é possível escolher se ele pode fazer login com um ou mais dos seguintes aliases:

• Um endereço de e-mail verificado

• Um número de telefone verificado

• Nome de usuário preferido

Depois que o usuário se cadastra, ele não pode alterar esses aliases.

Inclua as etapas a seguir quando criar o grupo de usuários para que os usuários possam fazer login com um alias.

Original console

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

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Selecione Manage User Pools.

3. No canto superior direito da página, selecione Create a user pool (Criar um grupo de usuários).

4. No canto superior esquerdo da página, escolha Attributes (Atributos).

5. Na guia Attributes (Atributos), em How do you want your end users to sign-in? (Como você deseja que seus usuários finais façam login?), selecione Username (Nome de usuário). Em seguida, escolha uma das seguintes opções:

   • Also allow sign in with verified email address (Também permitir acesso com endereço de e-mail verificado): permite que os usuários façam o acesso com o endereço de e-mail.

   • Also allow sign in with verified phone number (Também permitir acesso com número de telefone verificado): permite que os usuários façam o acesso com o número de telefone.

   • Also allow sign in with preferred username (Também permitir acesso com nome de usuário preferido): permite que os usuários façam login com um nome de usuário preferido. O usuário pode alterar esse nome de usuário.

6. Selecione Next step (Próxima etapa) para salvar e, em seguida, conclua todas as etapas no assistente.

New console

Para configurar um grupo de usuários para que seja possível fazer login com um nome de usuário preferido

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Escolha User Pools (Grupos de usuários).

3. No canto superior direito da página, escolha Create a user pool (Criar um grupo de usuários) para iniciar o assistente de criação de grupo de usuários.

4. Em Configure sign-in experience (Configurar experiência de acesso), escolha a identidade Provider types (Tipos de provedores) que você deseja associar ao grupo de usuários.

5. Em Cognito user pool sign-in options (Opções de acesso do grupo de usuários do Cognito), escolha qualquer combinação de User name (Nome de usuário), Email (E-mail) e Phone number (Número de telefone).

6. Em User name requirements (Requisitos do nome de usuário), escolha Allow users to sign in with a preferred user name (Permitir que os usuários façam login com um nome de usuário preferido) para permitir a definição de um nome de usuário alternativo para login.

7. Selecione Next (Próximo) e, em seguida, conclua todas as etapas no assistente.

Opção 2: o usuário se cadastra e faz login com um endereço de e-mail ou número de telefone em vez de o nome de usuário

Quando o usuário se cadastra com um endereço de e-mail ou número de telefone como o respectivo nome de usuário, é possível escolher se ele pode se cadastrar apenas com endereços de e-mail, apenas números de telefone ou qualquer um dos dois.

O endereço de 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 cadastra com um endereço de e-mail ou número de telefone, ele não pode criar uma nova conta com o mesmo endereço de e-mail ou número de telefone. O usuário só poderá reutilizar a conta existente e redefinir a respectiva senha, se necessário. No entanto, ele pode alterar o endereço de e-mail ou o número de telefone para um novo endereço de e-mail ou número de telefone. Se o endereço de e-mail ou o número de telefone ainda não estiver em uso, ele se tornará o novo nome de usuário.

nota

Se um usuário se cadastrar com um endereço de e-mail como nome de usuário, ele poderá alterar o nome de usuário para outro endereço de e-mail, mas não poderá alterá-lo para um número de telefone. Se os usuários se cadastrarem com um número de telefone, eles poderão alterar o nome de usuário para outro número de telefone, mas não poderão alterá-lo para um endereço de e-mail.

Siga as etapas abaixo durante o processo de criação do grupo de usuários para configurar o cadastro e o login com um endereço de e-mail ou número de telefone.

Original console

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

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Selecione Manage User Pools.

3. No canto superior direito da página, selecione Create a user pool (Criar um grupo de usuários).

4. No canto superior esquerdo da página, escolha Attributes (Atributos).

5. Na guia Attributes (Atributos), em How do you want your end users to sign-in? (Como você deseja que seus usuários finais se façam login?), selecione Email address or phone number (Endereço de e-mail ou número de telefone). Em seguida, escolha uma das seguintes opções:

   • Allow email addresses (Permitir endereços de e-mail): permite que o usuário se cadastre com um e-mail como nome de usuário.

   • Allow phone numbers (Permitir números de telefone): 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) [Permitir endereços de e-mail e números de telefone (o usuário pode escolher um)]: permite que o usuário escolha entre um endereço de e-mail ou um número de telefone para usar como nome de usuário durante o cadastro.

6. Selecione Next step (Próxima etapa) para salvar e, em seguida, conclua todas as etapas no assistente.

New console

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

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Escolha User Pools (Grupos de usuários).

3. No canto superior direito da página, escolha Create a user pool (Criar um grupo de usuários) para iniciar o assistente de criação de grupo de usuários.

4. Em Cognito user pool sign-in options (Opções de acesso do grupo de usuários do Cognito), escolha qualquer combinação de User name (Nome de usuário), Email (E-mail) e Phone number (Número de telefone) que represente os atributos de alias que o usuário pode usar para fazer login.

5. Em User name requirements (Requisitos de nome de usuário), escolha uma ou ambas as opções a seguir:

   Allow users to sign in with a preferred user name (Permitir que os usuários façam login com um nome de usuário preferido)

   Permite que o usuário faça login com um nome de usuário preferido. O usuário pode alterar esse nome de usuário.

   Make user name case sensitive (Diferenciar maiúsculas e minúsculas no nome de usuário)

   Define o nome de usuário para distinguir maiúsculas e minúsculas, onde ExampleUser e exampleuser são nomes de usuário exclusivos.

6. Selecione Next (Próximo) e, em seguida, conclua todas as etapas no assistente.

nota

Não é necessário marcar o endereço de e-mail ou número de telefone como atributos obrigató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 endereço de e-mail, o grupo de usuários preencherá 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 a string username não estiver no formato de endereço de e-mail ou número de telefone, a API SignUp retornará uma exceção.

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

   • Se a string username contiver um endereço de e-mail ou número de telefone já em uso, a API SignUp retornará uma exceção.

Em vez de o nome de usuário, é possível usar um endereço de e-mail ou número de telefone como alias em todas as APIs, exceto a API ListUsers. Quando você chama ListUsers, é possível pesquisar pelo atributo email ou phone_number. Se você pesquisar por username, será necessário fornecer o nome de usuário real, não o alias.

Atributos personalizados

Você pode adicionar até 50 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.

Todo atributo personalizado tem as seguintes características:

• Você pode defini-lo como uma string ou um número. O Amazon Cognito grava valores de atributo personalizados no token de ID somente como strings.

• Não é possível exigir que os usuários forneçam um valor para o atributo.

• Você não poderá removê-lo ou alterá-lo depois de adicioná-lo ao grupo de usuários.

• A extensão de caracteres do nome do atributo está dentro do limite que o Amazon Cognito aceita. Para mais informações, consulte Cotas no Amazon Cognito.

• Ele pode ser mutável ou imutável. É possível gravar um valor em um atributo imutável ao criar um usuário. Você pode alterar o valor de um atributo mutável se o cliente de aplicação tiver permissão de gravação para o atributo. Consulte Permissões e escopos do atributo para obter mais informações.

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 diferenciados dos atributos padrão.

Siga o procedimento abaixo para criar um novo atributo personalizado.

Original console

Para adicionar um atributo personalizado por meio do console

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Selecione Manage User Pools.

3. Na página Your User Pools (Seus Grupos de Usuários), escolha o grupo de usuários que deseja configurar.

4. Na barra de navegação à esquerda, escolha Attributes (Atributos).

5. Em Do you want to add custom attributes? (Deseja adicionar atributos personalizados?), escolha Add custom attribute (Adicionar atributo personalizado).

6. Forneça os seguintes detalhes sobre o novo atributo:

   • Insira um Name (Nome).

   • Selecione um Type (Tipo), que pode ser String ou Number (Número).

   • Insira um tamanho de string Min. (Mínimo) ou um valor numérico.

   • Insira um tamanho de string Max. (Máximo) ou um valor numérico.

   • Selecione Mutable (Mutável) se quiser conceder permissão aos usuários para alterar o valor de um atributo personalizado depois que eles definirem o valor inicial.

7. Selecione Save changes.

New console

Para adicionar um atributo personalizado usando o console

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Escolha User Pools (Grupos de usuários).

3. Escolha um grupo de usuários existente da lista.

4. Selecione a guia Sign-up experience (Experiência de cadastro) e na seção Custom attributes (Atributos personalizados), escolha Add custom attributes (Adicionar atributos personalizados).

5. Na página Add custom attributes (Adicionar atributos personalizados), forneça os seguintes detalhes sobre o novo atributo:

   • Insira um Name (Nome).

   • Selecione um Type (Tipo), que pode ser String ou Number (Número).

   • Insira um tamanho de string Min. (Mínimo) ou um valor numérico.

   • Insira um tamanho de string Max. (Máximo) ou um valor numérico.

   • Selecione Mutable (Mutável) se quiser conceder permissão aos usuários para alterar o valor de um atributo personalizado depois que eles definirem o valor inicial.

6. Selecione Save changes.

Permissões e escopos do atributo

Para cada aplicação cliente, é possível configurar permissões de leitura e gravação para cada atributo de usuário. Dessa forma, você pode controlar o acesso de leitura que qualquer aplicação tiver e modificar cada atributo armazenado para seus usuários. Por exemplo, você pode ter um atributo personalizado que indique se um usuário é ou não um cliente pagante. Suas aplicações podem ver esse atributo, mas não o alterar diretamente. Em vez disso, você atualizará o atributo usando uma ferramenta administrativa ou um processo em segundo plano. Você pode definir permissões para atributos de usuário no console do Amazon Cognito, na API do Amazon Cognito ou na AWS CLI. 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. Ao criar um cliente de aplicação no console do Amazon Cognito, você concede à aplicação permissões de leitura e gravação para todos os atributos padrão e personalizados por padrão. Para limitar a aplicação apenas à quantidade de informações necessárias, escolha um subconjunto de escopos que a aplicação precisa.

Original console

Para atualizar as permissões de atributo por meio do console

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Selecione Manage User Pools.

3. Na página Your User Pools (Seus Grupos de Usuários), escolha o grupo de usuários que deseja configurar.

4. Na barra de navegação à esquerda, escolha App clients (Clientes da aplicação).

5. Selecione Show details (Mostrar detalhes) para o cliente de aplicação que você deseja atualizar.

6. Na parte inferior da página, escolha Set attribute read and write permissions (Definir permissões de leitura e gravação de atributos) e, em seguida, configure suas permissões de leitura e gravação.

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

New console

Para atualizar as permissões de atributo por meio do console

1. Acesse o Amazon Cognito no AWS Management Console. Se o console solicitar, insira suas credenciais da AWS.

2. Escolha User Pools (Grupos de usuários).

3. Escolha um grupo de usuários existente da lista.

4. Selecione a guia App integration (Integração de aplicação) e na seção App clients (Clientes da aplicação), escolha um cliente da aplicação na lista.

5. Na seção Attribute read and write permissions (Permissões de gravação e leitura de atributos), escolha Edit (Editar).

6. Na página Edit attribute read and write permissions (Editar permissões de leitura e gravação de atributos), configure suas permissões de leitura e gravação e, em seguida, escolha Save changes (Salvar alterações).

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

Para cada aplicação, os atributos podem ser marcados como legíveis ou graváveis. Isso se aplica aos atributos padrão e aos atributos personalizados. Uma aplicação pode ler um atributo marcado como legível e gravar um atributo marcado como gravável. Se uma aplicação tentar atualizar um atributo não gravável, ela receberá uma exceção NotAuthorizedException. A aplicação que chamar GetUser receberá apenas os atributos que ela pode ler. O token de ID do usuário de uma aplicação contém apenas declarações que correspondem aos atributos legíveis. Os atributos obrigatórios em um grupo de usuários sempre são graváveis. Se usar a AWS CLI ou a API do administrador para definir um atributo gravável e não fornecer atributos obrigatórios, você receberá uma exceção InvalidParameterException.

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