사용자 풀 속성 구성 - Amazon Cognito

문서의 영문과 번역 사이에 충돌이 있는 경우에는 영문 버전을 따릅니다. 번역 버전은 기계 번역을 사용하여 제공합니다.

사용자 풀 속성 구성

모든 사용자 풀에는 "표준 속성"이라는 여러 기본 속성이 주어집니다. AWS Management 콘솔에서 사용자 풀 정의에 사용자 지정 속성을 추가할 수도 있습니다. 이 단원에서는 이러한 속성을 자세히 설명하며 사용자 풀을 설정하는 방법에 대한 팁을 제공합니다.

속성은 이름, 이메일, 전화 번호 등 개별 사용자를 식별하는 데 도움이 되는 정보입니다.

사용자에 대한 일부 정보는 속성에 저장되지 않습니다. 예를 들어, 사용 통계나 게임 점수와 같이 자주 변경되는 사용자 데이터는 Amazon Cognito Sync 또는 Amazon DynamoDB와 같은 별도의 데이터 스토어에 저장해야 합니다.

표준 속성

다음은 사용자 풀에 있는 모든 사용자의 표준 속성입니다. 이러한 속성은 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

이러한 속성은 모든 사용자의 선택적 속성으로 사용할 수 있습니다. 속성을 필수로 설정하려면 속성 옆에 있는 확인란을 선택합니다.

참고

표준 속성이 필수로 표시되면 해당 속성의 값을 제공해야 사용자가 등록할 수 있습니다. 관리자는 필수 속성의 값을 제공하지 않고 AdminCreateUser API를 사용하여 사용자를 생성할 수 있습니다. 사용자 풀이 생성된 후에는 필수 속성을 필수가 아닌 속성으로, 필수가 아닌 속성을 필수 속성으로 전환할 수 없습니다.

표준 및 사용자 지정 속성 값은 기본적으로 최대 2,048자의 문자열일 수 있지만 updated_at과 같은 일부 속성 값에는 형식 제한이 있습니다. emailphone만 확인할 수 있습니다.

참고

사양에서는 속성을 멤버라고 합니다.

다음은 위의 일부 필드와 관련된 몇 가지 추가 정보입니다.

email

이메일 주소 값은 확인할 수 있습니다.

적절한 AWS 계정 권한을 가진 관리자가 사용자의 이메일을 변경하고 확인됨으로 표시할 수 있습니다. AdminUpdateUserAttributes API 또는 admin-update-user-attributes CLI 명령을 통해 email_verified 속성을 true로 변경하여 이를 수행할 수 있습니다.

phone

SMS MFA(멀티 팩터 인증)가 활성화되면 전화 번호가 필수 사항이 됩니다. 자세한 내용은 사용자 풀에 멀티 팩터 인증(MFA) 추가 단원을 참조하십시오.

전화 번호 값은 확인할 수 있습니다.

적절한 AWS 계정 권한을 가진 관리자가 사용자의 전화 번호를 변경하고 확인됨으로 표시할 수 있습니다. AdminUpdateUserAttributes API 또는 admin-update-user-attributes CLI 명령을 통해 phone_number_verified 속성을 true로 변경하여 이를 수행할 수 있습니다.

중요

형식 규칙에 따라 전화 번호는 더하기(+) 기호로 시작하고 바로 뒤에 국가 코드가 와야 합니다. + 기호와 숫자만 전화 번호에 포함할 수 있습니다. 서비스에 값을 제출하기 전에 전화 번호에서 괄호, 공백 또는 대시(-)와 같은 다른 문자를 제거해야 합니다. 예를 들어, 미국 기반 전화 번호는 +14325551212 형식을 따라야 합니다.

preferred_username

preferred_username을 필수 항목이자 별칭으로 선택할 수 없습니다. preferred_username이 별칭이면 사용자가 UpdateUserAttributes API를 사용하여 확인된 후 속성 값을 추가할 수 있습니다.

 

표준 속성을 편집하려면

  1. 속성 탭에서 사용자 등록에 필요한 속성을 선택합니다. 속성이 필수이고 사용자가 필수 속성을 제공하지 않으면 등록할 수 없습니다.

    중요

    사용자 풀이 생성된 후에는 이 요구 사항을 변경할 수 없습니다.

  2. 이메일, 전화 번호, 주소 또는 선호하는 사용자 이름에 대한 별칭을 생성하려면 Alias(별칭)를 선택합니다. 별칭에 대한 자세한 내용은 별칭 개요를 참조하십시오.

  3. 이동하여 사용자 지정 속성을 생성합니다.

 

사용자 이름 및 선호하는 사용자 이름

username 값은 별도의 속성이며 name 속성과 동일하지 않습니다. username은 사용자를 등록하는 데 항상 필요하며, 사용자가 생성된 후에는 변경할 수 없습니다.

개발자는 preferred_username 속성을 사용하여 변경할 수 있는 사용자 이름을 사용자에게 제공할 수 있습니다. 자세한 내용은 별칭 개요 단원을 참조하십시오.

애플리케이션에서 사용자 이름이 필요하지 않은 경우 사용자 이름을 제공하도록 사용자에게 요청할 필요가 없습니다. 앱이 백그라운드에서 고유한 사용자 이름을 생성할 수 있습니다. 예를 들어, 사용자가 이메일 주소와 암호를 사용하여 등록 및 로그인하게 하려는 경우 유용한 기능입니다. 자세한 내용은 별칭 개요 단원을 참조하십시오.

username은 사용자 풀에서 고유해야 합니다. username은 삭제되고 더 이상 사용되지 않는 경우에만 재사용할 수 있습니다.

별칭 개요

최종 사용자가 별칭을 사용하여 여러 ID로 로그인하도록 허용할 수 있습니다.

기본적으로 사용자는 사용자 이름과 암호를 사용하여 로그인합니다. 사용자 이름은 사용자가 변경할 수 없는 고정 값입니다. 속성을 별칭으로 표시하면 사용자가 사용자 이름 대신 해당 속성을 사용하여 로그인할 수 있습니다. 이메일 주소, 전화 번호 및 선호하는 사용자 이름 속성은 별칭으로 표시할 수 있습니다.

예를 들어, 사용자 풀에 대해 이메일 및 전화를 별칭으로 선택하면 해당 사용자 풀의 사용자는 사용자 이름, 이메일 주소 또는 전화 번호를 암호와 함께 사용하여 로그인할 수 있습니다.

참고

사용자 이름의 대/소문자를 구분하지 않도록 사용자 풀을 구성하면 별칭에서 소문자 또는 대문자를 사용하여 로그인하거나 가입할 수 있습니다. 자세한 내용은 Amazon Cognito 사용자 풀 API 참조CreateUserPool을 참조하십시오.

이메일을 별칭으로 선택하면 사용자 이름이 유효한 이메일 형식에 맞지 않습니다. 마찬가지로 전화 번호를 별칭으로 선택하면 해당 사용자 풀의 서비스가 유효한 전화 번호 패턴에 맞는 사용자 이름을 수락하지 않습니다.

참고

별칭 값은 사용자 풀에서 고유해야 합니다. 이메일 주소나 전화 번호의 별칭이 구성되면 제공된 값이 계정 하나에서만 확인됨 상태가 될 수 있습니다. 가입 중 이미 사용된 다른 계정에서 이메일 주소나 전화 번호가 별칭으로 제공되면 등록이 성공합니다. 그러나 사용자가 이 이메일(또는 전화 번호)로 계정 확인을 시도하고 유효한 코드를 입력하면 AliasExistsException 오류가 발생합니다. 이 오류는 이 이메일(또는 전화 번호)이 있는 계정이 이미 있음을 사용자에게 나타냅니다. 이때 사용자는 새 계정 생성을 중단하고 이전 계정의 암호를 재설정해볼 수 있습니다. 사용자가 계속해서 새 계정을 생성하면 앱이 ConfirmSignUp 옵션으로 forceAliasCreation API를 호출해야 합니다. 그러면 이전 계정에서 새로 생성된 계정으로 별칭이 이동하며, 이전 계정에서 해당 속성이 확인되지 않음으로 표시됩니다.

전화 번호와 이메일 주소가 확인된 경우에만 전화 번호와 이메일 주소가 사용자의 활성 별칭이 됩니다. 따라서 이메일 주소와 전화 번호를 별칭으로 사용할 경우 이메일 주소와 전화 번호의 자동 확인을 선택하는 것이 좋습니다. 사용자의 실제 사용자 이름 값을 변경할 수 없는 경우 사용자가 자신의 사용자 이름을 변경할 수 있도록 preferred_username 속성이 포함됩니다.

사용자가 사용자 이름을 변경할 수 있도록 허용하려면 새 username 값을 preferred_username으로 제출하고 별칭으로 preferred_username을 선택합니다. 그러면 입력한 새 값으로 로그인할 수 있습니다.

preferred_username을 별칭으로 선택하면 계정이 확인되어야 값을 입력할 수 있습니다. 등록 중에는 값을 입력할 수 없습니다.

별칭을 사용하여 사용자 가입 및 로그인 간소화

속성 콘솔 탭에서 사용자가 이메일 주소나 전화 번호를 사용자 이름으로 사용하여 로그인할 수 있도록 허용할지 여부를 선택할 수 있습니다.

참고

사용자 풀이 생성되고 나면 이 설정을 변경할 수 없습니다.

옵션 1: 사용자가 사용자 이름을 사용하여 가입하고 사용자 이름이나 별칭을 사용하여 로그인

이 경우, 사용자가 사용자 이름으로 가입합니다. 또한 선택에 따라 사용자가 다음 별칭 중 하나 이상을 사용하여 로그인할 수 있도록 허용할 수 있습니다.

  • 확인된 이메일 주소

  • 확인된 전화 번호

  • 기본 설정 사용자 이름

사용자가 가입한 후에 이들 별칭을 변경할 수 있습니다.

다음 단계에 따라 별칭을 사용하여 로그인할 수 있도록 콘솔에서 사용자 풀을 구성합니다.

별칭을 사용한 로그인이 가능하도록 사용자 풀을 구성하려면

  1. 속성 탭의 최종 사용자 로그인 방법을 어떻게 설정하시겠습니까?에서 사용자 이름을 선택합니다.

  2. 다음 옵션 중 하나를 선택합니다.

    • 확인된 이메일 주소로 로그인 허용: 사용자가 이메일 주소를 사용하여 로그인할 수 있습니다.

    • 확인된 전화 번호로 로그인 허용: 사용자가 전화 번호를 사용하여 로그인할 수 있습니다.

    • 기본 설정 사용자 이름으로 로그인 허용: 사용자가 기본 설정 사용자 이름을 사용하여 로그인할 수 있습니다. 기본 설정 사용자 이름은 사용자가 변경할 수 있는 사용자 이름입니다.

옵션 2: 사용자가 사용자 이름 대신 이메일 또는 전화 번호를 사용하여 가입 및 로그인

이 경우, 사용자는 이메일 주소나 전화 번호를 사용자 이름으로 사용하여 가입할 수 있습니다. 사용자가 이메일 주소만, 전화 번호만, 또는 둘 중 하나를 사용하여 가입할 수 있도록 허용할지 여부를 선택할 수 있습니다.

이메일이나 전화 번호는 고유해야 하며 다른 사용자가 이미 사용하고 있어서는 안 됩니다. 확인을 받을 필요는 없습니다. 이메일이나 전화 번호를 사용하여 가입을 하고 나면 사용자는 같은 이메일이나 전화 번호로 새 계정을 생성할 수 없습니다. 기존 계정은 재사용만 가능합니다(필요할 경우 암호 재설정). 그러나 이메일이나 전화 번호를 새로 변경할 수는 있습니다. 이미 사용 중인 것이 아니라면 변경된 이메일이나 전화 번호가 새 사용자 이름이 됩니다.

참고

사용자가 이메일 주소를 사용자 이름으로 사용하여 가입한 경우에는 사용자 이름을 다른 이메일 주소로 변경할 수 있으나 전화 번호로 변경할 수는 없습니다. 사용자가 전화 번호를 사용하여 가입한 경우에는 사용자 이름을 다른 전화 번호로 변경할 수 있으나 이메일 주소로 변경할 수는 없습니다.

다음 단계에 따라 이메일이나 전화 번호를 사용하여 가입 및 로그인을 할 수 있도록 콘솔에서 사용자 풀을 구성합니다.

이메일이나 전화 번호를 사용하여 가입 및 로그인을 할 수 있도록 사용자 풀을 구성하려면

  1. 속성 탭의 최종 사용자 로그인 방법을 어떻게 설정하시겠습니까?에서 이메일 주소 또는 전화 번호를 선택합니다.

  2. 다음 옵션 중 하나를 선택합니다.

    • 이메일 주소 허용: 사용자가 이메일을 사용자 이름으로 사용하여 로그인할 수 있습니다.

    • 전화 번호 허용: 사용자가 전화 번호를 사용자 이름으로 사용하여 로그인할 수 있습니다.

    • 이메일 주소 및 전화 번호 허용(사용자가 하나 선택 가능): 사용자가 가입 시 이메일 주소나 전화 번호를 사용자 이름으로 사용할 수 있습니다.

참고

이메일이나 전화 번호를 사용자 풀의 필수 속성으로 지정할 필요가 없습니다.

앱에서 옵션 2를 실행하려면

  1. CreateUserPool API를 호출하여 사용자 풀을 생성합니다. UserNameAttributes 파라미터를 phone_number, email 또는 phone_number | email로 설정합니다.

  2. SignUp API를 호출하고 API의 username 파라미터에서 이메일 주소나 전화 번호를 전달합니다. 이 API는 다음을 수행합니다.

    • username 문자열이 유효한 이메일 형식이면 사용자 풀에서 사용자의 email 속성이 username 값으로 자동으로 채워집니다.

    • username 문자열이 유효한 전화 번호 형식이면 사용자 풀에서 사용자의 phone_number 속성이 username 값으로 자동으로 채워집니다.

    • username 문자열 형식이 이메일이나 전화 번호가 아니면 SignUp API에서 예외가 발생합니다.

    • SignUp API는 사용자에 대해 영구적인 UUID를 생성하고 내부적으로 이를 변경이 불가능한 사용자 이름 속성으로 사용합니다. 이 UUID는 사용자 ID 토큰의 sub 클레임과 동일한 값을 갖습니다.

    • username 문자열에 이미 사용 중인 이메일 주소나 전화 번호가 포함되어 있으면 SignUp API에서 예외가 발생합니다.

ListUsers API를 제외하고 모든 API에서 사용자 이름 자리에 별칭으로 이메일 주소나 전화 번호를 사용할 수 있습니다. ListUsers를 호출하면 email 또는 phone_number 속성으로 검색을 할 수 있습니다. username으로 검색을 하는 경우에는 별칭이 아니라 실제 사용자 이름을 입력해야 합니다.

사용자 지정 속성

사용자 풀에 사용자 지정 속성 25개까지 추가할 수 있습니다. 사용자 지정 속성의 최소 및/또는 최대 길이를 지정할 수 있습니다. 단, 사용자 지정 속성의 최대 길이는 2,048자를 넘을 수 없습니다.

각 사용자 지정 속성:

  • 문자열 또는 숫자로 정의할 수 있습니다.

  • 필수 항목이 될 수 없습니다.

  • 사용자 풀에 추가된 후에는 삭제 또는 변경할 수 없습니다.

  • Amazon Cognito 허용 한도 내에 있는 문자 길이의 이름을 가질 수 있습니다. 자세한 내용은 Amazon Cognito의 할당량 단원을 참조하십시오.

참고

역할 기반 액세스 제어에 대한 규칙 설정 및 코드에서는 표준 속성과 구분하기 위해 사용자 지정 속성에 custom: 접두사가 필요합니다.

콘솔을 사용하여 사용자 지정 속성을 추가하려면

  1. 왼쪽의 탐색 모음에서 속성을 선택합니다.

  2. 새로운 각 속성에 대해

    1. 사용자 지정 속성을 추가하시겠습니까? 에서 다른 속성 추가를 선택합니다.

    2. 데이터 유형(문자열 또는 숫자), 이름, 최소 길이, 최대 길이 등 각 사용자 지정 속성의 속성을 선택합니다.

    3. 사용자가 사용자 지정 속성의 값을 제공한 후 해당 값을 변경할 수 있도록 하려면 변경 가능을 선택합니다.

속성 권한 및 범위

각 사용자 속성의 앱당 읽기 및 쓰기 권한을 설정할 수 있습니다. 권한을 설정하면 사용자에 대해 저장된 각 속성을 확인 및/또는 수정할 수 있는 애플리케이션을 제어할 수 있습니다. 예를 들어, 사용자가 유료 고객인지 여부를 나타내는 사용자 지정 속성이 있을 수 있습니다. 앱에서는 이 속성을 볼 수 있지만 직접 수정할 수 없습니다. 대신 관리 도구 또는 백그라운드 프로세스를 사용하여 이 속성을 업데이트합니다. 사용자 속성에 대한 권한은 Amazon Cognito 콘솔, API 또는 CLI에서 설정할 수 있습니다. 기본적으로 새로운 사용자 지정 속성은 사용자가 그에 대한 읽기 및 쓰기 권한을 설정한 이후에만 사용할 수 있습니다.

콘솔을 사용하여 속성 권한을 설정 또는 변경하려면

  1. 왼쪽의 탐색 모음에서 앱 클라이언트를 선택합니다.

  2. 업데이트할 앱 클라이언트의 세부 정보 표시를 선택합니다.

  3. Set the attribute read and write permissions for each attribute(각 속성에 대해 속성 읽기 및 쓰기 권한 설정)를 선택합니다.

  4. 앱 클라이언트 변경 사항 저장을 선택합니다.

사용자 지정 속성을 사용하여 각 앱마다 이러한 단계를 반복합니다.

각 앱에 대해 속성을 읽기 가능 또는 쓰기 가능으로 표시할 수 있습니다. 표준 속성과 사용자 지정 속성에 모두 해당하는 사항입니다. 앱에서 읽기 가능으로 표시된 속성을 읽을 수 있으며, 쓰기 가능으로 표시된 속성을 쓸 수 있습니다. 앱에서 쓰기가 가능하지 않은 속성을 업데이트하려고 시도할 경우 NotAuthorizedException 예외가 발생합니다. GetUser를 호출하는 앱은 해당 앱에 대해 읽기 가능한 속성만 받습니다. 사후 인증으로 발급된 ID 토큰에는 읽기 가능 속성에 해당하는 클레임만 포함됩니다. 사용자 풀에 대한 필수 속성은 항상 쓸 수 있습니다. CLI 또는 관리자 API를 사용하여 쓰기 가능 속성을 설정하고 필수 속성을 제공하지 않는 경우 InvalidParameterException 예외가 발생합니다.

사용자 풀을 생성한 후 속성 권한과 범위를 변경할 수 있습니다.