기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 프로필 및 토큰에 IdP 속성 매핑 Amazon Cognito를 포함한 ID 제공업체(IdP) 서비스는 일반적으로 사용자에 대한 추가 정보를 기록할 수 있습니다. 어떤 회사에서 근무하는지, 어떻게 연락하는지, 기타 식별 정보를 알고 싶을 수 있습니다. 그러나 이러한 속성이 사용하는 형식은 제공업체마다 차이가 있습니다. 예를 들어 사용자 풀을 사용하여 서로 다른 세 공급업체에서 세 개의 IdP를 설정하고 각각에서 예제 SAML 어설션, ID 토큰 또는 `userInfo` 페이로드를 검사합니다. 하나는 사용자의 이메일 주소를 `email`로, 다른 하나는 `emailaddress`로, 세 번째는 `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`로 나타냅니다. IdP 사용자 풀과 통합하면 다양한 속성 이름을 일관되고 예측 가능한 공유 속성 이름으로 단일 OIDC 토큰 스키마에 매핑할 수 있다는 이점이 있습니다. 이렇게 하면 개발자가 복잡한 다양한 Single Sign-On 이벤트를 처리하기 위한 로직을 유지할 필요가 없습니다. 이 형식 통합은 속성 매핑입니다. 사용자 풀 속성 매핑은 IdP 속성 이름을 해당 사용자 풀 속성 이름에 할당합니다. 예를 들어 표준 사용자 풀 속성 `email`에 `emailaddress` 클레임 값을 쓰도록 사용자 풀을 구성할 수 있습니다. 각 사용자 풀 IdP에는 별도의 속성 매핑 스키마가 있습니다. IdP에 대한 속성 매핑을 지정하려면 Amazon Cognito 콘솔, AWS SDK 또는 사용자 풀 REST API에서 사용자 풀 ID 제공업체를 구성합니다. ## 매핑에 대해 알아야 할 사항 사용자 속성 매핑 설정을 시작하기 전에 다음 중요 세부 정보를 검토합니다. + 페더레이션 사용자가 애플리케이션에 로그인할 때 사용자 풀에 필요한 각 사용자 풀 속성의 매핑이 있어야 합니다. 예를 들어, 사용자 풀에 로그인용 `email` 속성이 필요한 경우 이 속성을 IdP의 해당 속성에 매핑합니다. + 기본적으로 매핑된 이메일 주소는 확인되지 않습니다. 일회용 코드를 사용하여 매핑된 이메일 주소는 확인할 수 없습니다. 대신 IdP의 속성을 매핑하여 확인 상태를 가져옵니다. 예를 들어 Google과 대부분의 OIDC 공급자는 `email_verified` 속성을 포함합니다. + ID 제공업체(IdP) 토큰을 사용자 풀의 사용자 지정 속성에 매핑할 수 있습니다. 소셜 제공업체는 액세스 토큰을 제시하고, OIDC 제공업체는 액세스 및 ID 토큰을 제공합니다. 토큰을 매핑하려면 최대 2,048자의 사용자 지정 속성을 추가하고, 앱 클라이언트에 속성에 대한 쓰기 권한을 부여하고, IdP에서 사용자 지정 속성으로 `access_token` 또는 `id_token`을 매핑합니다. + 매핑된 각 사용자 풀 속성의 경우 최대 값 길이(2,048자)는 Amazon Cognito가 IdP에서 가져오는 값에 대해 충분히 커야 합니다. 그러지 않으면 사용자가 애플리케이션에 로그인할 때 Amazon Cognito에서 오류를 보고합니다. Amazon Cognito는 토큰 길이가 2,048자를 초과하는 경우 IdP 토큰을 사용자 지정 속성에 매핑하는 것을 지원하지 않습니다. + Amazon Cognito는 다음 표에 설명된 것과 같이 페더레이션 IdP가 전달하는 특정 클레임에서 페더레이션 사용자 프로필의 `username` 속성을 추출합니다. Amazon Cognito는 이 속성 값 앞에 IdP 이름(예: `MyOIDCIdP_[sub]`)을 추가합니다. 페더레이션 사용자가 외부 사용자 디렉터리의 속성과 정확히 일치하는 속성을 갖도록 하려면 해당 속성을 Amazon Cognito 로그인 속성(예: `preferred_username`)에 매핑합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/cognito/latest/developerguide/cognito-user-pools-specifying-attribute-mapping.html) + 사용자 풀이 [대/소문자를 구분하지 않는](user-pool-case-sensitivity.md) 경우 Amazon Cognito는 사용자 이름 소스 속성을 페더레이션 사용자의 자동 생성 사용자 이름에서 소문자로 변환합니다. `MySAML_TestUser@example.com`은 대/소문자를 구분하는 사용자 풀의 사용자 이름 예시입니다. `MySAML_testuser@example.com`은 대/소문자를 *구분하지 않는* 사용자 풀의 사용자 이름과 동일합니다. 대/소문자를 구분하지 않는 사용자 풀의 경우 사용자 이름을 처리하는 Lambda 트리거는 사용자 이름 소스 속성의 대소문자 혼합 클레임에 대해 이러한 수정을 고려해야 합니다. IdP를 현재 사용자 풀과 대/소문자 구분 설정이 다른 사용자 풀에 연결하려면 새 사용자 풀을 생성합니다. + 사용자가 애플리케이션에 로그인할 때 Amazon Cognito는 매핑된 사용자 풀 속성을 업데이트할 수 있어야 합니다. 사용자가 IdP를 통해 로그인하면 Amazon Cognito가 매핑된 속성을 IdP의 최신 정보로 업데이트합니다. Amazon Cognito는 값이 변경될 때만 매핑된 속성을 업데이트합니다. Amazon Cognito가 속성을 업데이트할 수 있는지 확인하려면 다음 요구 사항을 확인하세요. + IdP에서 매핑하는 모든 사용자 풀 사용자 지정 속성은 *변경할 수 있어야* 합니다. 변경 가능한 사용자 지정 속성은 언제든지 업데이트할 수 있습니다. 반대로 사용자 프로필을 처음 만들 때 사용자의 *변경할 수 없는* 사용자 지정 속성 값만 설정할 수 있습니다. Amazon Cognito 콘솔에서 변경 가능한 사용자 지정 속성을 생성하려면 **가입** 메뉴에서 **사용자 지정 속성 추가**를 선택할 때 추가한 속성의 **변경 가능** 확인란을 활성화합니다. 또는 [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API 작업을 사용하여 사용자 풀을 생성하는 경우 이러한 각 속성에 대한 `Mutable` 파라미터를 `true`로 설정할 수 있습니다. IdP가 매핑된 변경 불가능한 속성에 대한 값을 전송하는 경우 Amazon Cognito는 오류를 반환하고 로그인에 실패합니다. + 애플리케이션의 앱 클라이언트 설정에서 매핑된 속성은 *쓰기 가능*해야 합니다. Amazon Cognito 콘솔의 [**앱 클라이언트(App clients)**] 페이지에 쓸 수 있는 속성을 설정할 수 있습니다. 또는 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) API 작업을 사용하여 앱 클라이언트를 생성하는 경우 이러한 속성을 `WriteAttributes` 어레이에 추가할 수 있습니다. IdP가 매핑된 쓰기 불가능한 속성에 대한 값을 전송하는 경우 Amazon Cognito는 속성 값을 설정하지 않고 인증을 진행합니다. + IdP 속성에 여러 값이 포함된 경우 Amazon Cognito는 모든 값을 대괄호 `[` 및 `]`로 묶인 쉼표로 구분된 단일 문자열로 평면화합니다. Amazon Cognito URL은 `.`, `-`, `*`, `_`를 제외한 영숫자가 아닌 문자를 포함하는 값을 양식 인코딩합니다. 이러한 개별 값은 앱에 사용하기 전에 디코딩 및 구문 분석해야 합니다. + 대상 속성은 로그인 또는 관리 작업이 변경하지 않는 한 속성 매핑 규칙이 할당하는 모든 값을 유지합니다. Amazon Cognito는 소스 속성이 더 이상 공급자 토큰 또는 SAML 어설션으로 전송되지 않을 때 사용자의 속성을 제거하지 않습니다. 다음 작업은 페더레이션 사용자의 사용자 풀 프로파일에서 속성 값을 제거합니다. 1. IdP는 소스 속성의 빈 값을 전송하고 매핑 규칙은 빈 값을 대상 속성에 적용합니다. 1. [DeleteUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserAttributes.html) 또는 [AdminDeleteUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDeleteUserAttributes.html) 요청을 사용하여 매핑된 속성의 값을 지웁니다. ## 사용자 풀에 대한 자격 증명 공급자 속성 매핑 지정(AWS Management Console) AWS Management Console 를 사용하여 사용자 풀의 IdP에 대한 속성 매핑을 지정할 수 있습니다. **참고** Amazon Cognito는 수신 토큰에 클레임이 있는 경우에만 수신 클레임을 사용자 풀 속성에 매핑합니다. 이전에 매핑된 클레임이 수신 토큰에 더 이상 존재하지 않으면 삭제되거나 변경되지 않습니다. 애플리케이션에 삭제된 클레임의 매핑이 필요한 경우 사전 인증 Lambda 트리거를 사용하여 인증 중에 사용자 지정 속성을 삭제하고 이러한 속성이 수신 토큰에서 다시 채워지도록 허용할 수 있습니다. **소셜 IdP 속성 매핑을 지정하려면** 1. [Amazon Cognito 콘솔](https://console.aws.amazon.com/cognito/home)에 로그인합니다. 메시지가 표시되면 자격 AWS 증명을 입력합니다. 1. 탐색 창에서 [**사용자 풀(User Pools)**]을 선택한 다음 편집할 사용자 풀을 선택합니다. 1. **소셜 및 외부 제공업체** 메뉴를 선택합니다. 1. **ID 제공업체 추가**를 선택하거나 구성한 **Facebook**, **Google**, **Amazon** 또는 **Apple** IdP를 선택합니다. **속성 매핑(Attribute mapping)**을 찾아서 **편집(Edit)**을 선택합니다. 소셜 IdP 추가에 대한 자세한 내용은 [사용자 풀에서 소셜 ID 제공업체 사용](cognito-user-pools-social-idp.md) 섹션을 참조하세요. 1. 매핑해야 하는 각 속성에 대해 다음 단계를 완료합니다. 1. [**사용자 풀 속성(User pool attribute)**] 열에서 속성을 선택합니다. 사용자 풀의 사용자 프로파일에 할당되는 속성입니다. 사용자 정의 속성은 표준 속성 뒤에 나열됩니다. 1. **** 속성(attribute)** 열에서 속성을 선택합니다. 공급자 디렉터리에서 전달되는 속성입니다. 소셜 공급자의 알려진 속성이 드롭다운 목록에 제공됩니다. 1. IdP와 Amazon Cognito 간에 추가 속성을 매핑하려면 [**다른 속성 추가(Add another attribute)**]를 선택합니다. 1. **변경 사항 저장(Save changes)**을 선택합니다. **SAML 공급자 속성 매핑을 지정하려면** 1. [Amazon Cognito 콘솔](https://console.aws.amazon.com/cognito/home)에 로그인합니다. 메시지가 표시되면 자격 AWS 증명을 입력합니다. 1. 탐색 창에서 [**사용자 풀(User Pools)**]을 선택한 다음 편집할 사용자 풀을 선택합니다. 1. **소셜 및 외부 제공업체** 메뉴를 선택합니다. 1. **자격 증명 공급자 추가(Add an identity provider)**를 선택하거나 구성한 SAML IdP를 선택합니다. **속성 매핑(Attribute mapping)**을 찾아서 **편집(Edit)**을 선택합니다. SAML IdP 추가에 대한 자세한 내용은 [사용자 풀에서 SAML ID 제공업체 사용](cognito-user-pools-saml-idp.md) 섹션을 참조하세요. 1. 매핑해야 하는 각 속성에 대해 다음 단계를 완료합니다. 1. [**사용자 풀 속성(User pool attribute)**] 열에서 속성을 선택합니다. 사용자 풀의 사용자 프로파일에 할당되는 속성입니다. 사용자 정의 속성은 표준 속성 뒤에 나열됩니다. 1. [**SAML 속성(SAML attribute)**] 열에서 속성을 선택합니다. 공급자 디렉터리에서 전달되는 속성입니다. IdP가 샘플 SAML 어설션을 참조용으로 제공할 수도 있습니다. `email`과 같은 간단한 이름을 사용하는 IdP도 있고, 다음과 같이 URL 형식의 속성 이름을 사용하는 IdP도 있습니다. ``` http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ``` 1. IdP와 Amazon Cognito 간에 추가 속성을 매핑하려면 **다른 속성 추가(Add another attribute)**를 선택합니다. 1. **변경 사항 저장**을 선택합니다. ## 사용자 풀(AWS CLI 및 AWS API)에 대한 자격 증명 공급자 속성 매핑 지정 [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) 또는 [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html)에 대한 다음 요청 본문은 SAML 제공업체 “MyIdP” 속성 `emailaddress`, `birthdate` 및 `phone`을 사용자 풀 속성 `email`, `birthdate` 및 `phone_number`에 해당 순서로 매핑합니다. SAML 2.0 제공업체에 대한 전체 요청 본문입니다. 요청 본문은 IdP 유형 및 특정 세부 정보에 따라 달라집니다. 속성 매핑은 `AttributeMapping` 파라미터에 있습니다. ``` { "AttributeMapping": { "email" : "emailaddress", "birthdate" : "birthdate", "phone_number" : "phone" }, "IdpIdentifiers": [ "IdP1", "pdxsaml" ], "ProviderDetails": { "IDPInit": "true", "IDPSignout": "true", "EncryptedResponses" : "true", "MetadataURL": "https://auth.example.com/sso/saml/metadata", "RequestSigningAlgorithm": "rsa-sha256" }, "ProviderName": "MyIdP", "ProviderType": "SAML", "UserPoolId": "us-west-2_EXAMPLE" } ``` 다음 명령을 사용하여 사용자 풀에 대한 IdP 속성 매핑을 지정합니다. **공급자 생성 시 속성 매핑을 지정하려면** + AWS CLI: `aws cognito-idp create-identity-provider` 메타데이터 파일이 포함된 예제: `aws cognito-idp create-identity-provider --user-pool-id --provider-name=SAML_provider_1 --provider-type SAML --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` 여기서 `details.json`에 다음 사항이 포함됩니다. ``` { "MetadataFile": "" } ``` **참고** **에 따옴표(`"`)가 있으면 이스케이프해야 합니다(`\"`). 메타데이터 URL이 포함된 예시: ``` aws cognito-idp create-identity-provider \ --user-pool-id us-east-1_EXAMPLE \ --provider-name=SAML_provider_1 \ --provider-type SAML \ --provider-details MetadataURL=https://myidp.example.com/saml/metadata \ --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ``` + API/SDK: [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) **기존 IdP에 대한 속성 매핑을 지정하려면** + AWS CLI: `aws cognito-idp update-identity-provider` 예시: `aws cognito-idp update-identity-provider --user-pool-id --provider-name --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` + API/SDK: [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) **특정 IdP에 대한 속성 매핑 정보를 가져오려면** + AWS CLI: `aws cognito-idp describe-identity-provider` 예시: `aws cognito-idp describe-identity-provider --user-pool-id --provider-name ` + API/SDK: [DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html)