매핑에 대해 알아야 할 사항 사용자 풀에 대한 자격 증명 공급자 속성 매핑 지정(AWS Management Console)사용자 풀에 대한 자격 증명 공급자 속성 매핑 지정(AWS CLI 및 AWS API)

프로필 및 토큰에 IdP 속성 매핑

Amazon Cognito 를 포함한 자격 증명 공급자(IdP ) 서비스는 일반적으로 사용자에 대한 추가 정보를 기록할 수 있습니다. 어떤 회사에서 근무하고 있는지, 어떻게 연락하는지, 기타 식별 정보를 알고 싶을 수 있습니다. 그러나 이러한 속성이 사용하는 형식은 공급자 간에 차이가 있습니다. 예를 들어 사용자 풀을 사용하여 서로 다른 세 공급업체 IdPs 중 세 곳을 설정하고 각각에서 예제 어SAML설션, ID 토큰 또는 userInfo페이로드를 검사합니다. 하나는 사용자의 이메일 주소를 로email, 다른 하나는 로emailaddress, 세 번째는 로 나타냅니다http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

사용자 풀 IdPs 과의 통합에서 얻을 수 있는 주요 이점은 일관되고 예측 가능한 공유 속성 이름을 사용하여 다양한 속성 이름을 단일 OIDC 토큰 스키마에 매핑하는 기능입니다. 이렇게 하면 개발자가 복잡한 다양한 Single Sign-On 이벤트를 처리하기 위한 로직을 유지할 필요가 없습니다. 이 형식 통합은 속성 매핑입니다. 사용자 풀 속성 매핑은 IdP 속성 이름을 해당 사용자 풀 속성 이름에 할당합니다. 예를 들어 표준 사용자 풀 속성 에 emailaddress 클레임 값을 쓰도록 사용자 풀을 구성할 수 있습니다email.

각 사용자 풀 IdP에는 별도의 속성 매핑 스키마가 있습니다. IdP 에 대한 속성 매핑을 지정하려면 Amazon Cognito 콘솔, AWS SDK또는 사용자 풀 에서 사용자 풀 자격 증명 공급자를 구성합니다RESTAPI.

매핑에 대해 알아야 할 사항

사용자 속성 매핑 설정을 시작하기 전에 다음 중요 세부 정보를 검토합니다.

페더레이션 사용자가 애플리케이션에 로그인할 때 사용자 풀에 필요한 각 사용자 풀 속성의 매핑이 있어야 합니다. 예를 들어, 사용자 풀에 로그인용 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.

ID 제공업체	`username` 소스 속성
Facebook	`id`
Google	`sub`
Login with Amazon	`user_id`
Apple로 로그인	`sub`
SAML 공급자	`NameID`
OpenID Connect(OIDC) 공급자	`sub`

사용자 풀이 대/소문자를 구분하지 않는 인 경우 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 콘솔에서 변경 가능한 사용자 지정 속성을 생성하려면 가입 환경(Sign-up experience) 탭에서 사용자 지정 속성 추가(Add custom attributes)를 선택할 때 추가한 속성의 변경 가능(Mutable) 확인란을 활성화합니다. 또는 CreateUserPool API 작업을 사용하여 사용자 풀을 생성하는 경우 이러한 각 속성의 Mutable 파라미터를 로 설정할 수 있습니다true. IdP가 매핑된 변경 불가능한 속성에 대한 값을 전송하는 경우 Amazon Cognito는 오류를 반환하고 로그인에 실패합니다.
- 애플리케이션의 앱 클라이언트 설정에서 매핑된 속성은 쓰기 가능해야 합니다. Amazon Cognito 콘솔의 [앱 클라이언트(App clients)] 페이지에 쓸 수 있는 속성을 설정할 수 있습니다. 또는 CreateUserPoolClient API 작업을 사용하여 앱 클라이언트를 생성하는 경우 이러한 속성을 WriteAttributes 배열에 추가할 수 있습니다. IdP가 매핑된 쓰기 불가능한 속성에 대한 값을 전송하는 경우 Amazon Cognito는 속성 값을 설정하지 않고 인증을 진행합니다.
IdP 속성에 여러 값이 포함된 경우 Amazon Cognito는 모든 값을 쉼표로 구분된 단일 문자열로 평평하게 만들고 영숫자가 아닌 문자(‘.’, ‘-’, ‘*’ 및 ‘_’ 문자 제외)를 포함하는 값을 URL 양식 인코딩합니다. 이러한 개별 값은 앱에 사용하기 전에 디코딩 및 구문 분석해야 합니다.

사용자 풀에 대한 자격 증명 공급자 속성 매핑 지정(AWS Management Console)

AWS Management Console 를 사용하여 사용자 풀의 IdP에 대한 속성 매핑을 지정할 수 있습니다.

참고

Amazon Cognito는 수신 토큰에 클레임이 있는 경우에만 수신 클레임을 사용자 풀 속성에 매핑합니다. 이전에 매핑된 클레임이 수신 토큰에 더 이상 존재하지 않으면 삭제되거나 변경되지 않습니다. 애플리케이션에 삭제된 클레임의 매핑이 필요한 경우 사전 인증 Lambda 트리거를 사용하여 인증 중에 사용자 지정 속성을 삭제하고 이러한 속성이 수신 토큰에서 다시 채워지도록 허용할 수 있습니다.

소셜 IdP 속성 매핑을 지정하려면

Amazon Cognito 콘솔에 로그인합니다. 메시지가 표시되면 AWS 자격 증명을 입력합니다.
탐색 창에서 [사용자 풀(User Pools)]을 선택한 다음 편집할 사용자 풀을 선택합니다.
로그인 환경(Sign-in experience) 탭을 선택하고 페더레이션 로그인(Federated sign-in)을 찾습니다.
자격 증명 공급자 추가(Add an identity provider)를 선택하거나 구성한 Facebook, Google, Amazon 또는 Apple IdP를 선택합니다. 속성 매핑(Attribute mapping)을 찾아서 편집(Edit)을 선택합니다.

소셜 IdP 추가에 대한 자세한 내용은 사용자 풀에서 소셜 자격 증명 공급자 사용 섹션을 참조하세요.
매핑해야 하는 각 속성에 대해 다음 단계를 완료합니다.
1. [사용자 풀 속성(User pool attribute)] 열에서 속성을 선택합니다. 사용자 풀의 사용자 프로파일에 할당되는 속성입니다. 사용자 정의 속성은 표준 속성 뒤에 나열됩니다.
2. 에서 속성을 선택합니다. <provider> 속성 열. 공급자 디렉터리에서 전달되는 속성입니다. 소셜 공급자의 알려진 속성이 드롭다운 목록에 제공됩니다.
3. IdP와 Amazon Cognito 간에 추가 속성을 매핑하려면 [다른 속성 추가(Add another attribute)]를 선택합니다.
Save changes(변경 사항 저장)를 선택합니다.

SAML 공급자 속성 매핑을 지정하려면

Amazon Cognito 콘솔에 로그인합니다. 메시지가 표시되면 AWS 자격 증명을 입력합니다.
탐색 창에서 [사용자 풀(User Pools)]을 선택한 다음 편집할 사용자 풀을 선택합니다.
로그인 환경(Sign-in experience) 탭을 선택하고 페더레이션 로그인(Federated sign-in)을 찾습니다.
자격 증명 공급자 추가를 선택하거나 구성한 SAML IdP를 선택합니다. 속성 매핑(Attribute mapping)을 찾아서 편집(Edit)을 선택합니다. SAML IdP 추가에 대한 자세한 내용은 섹션을 참조하세요사용자 풀에서 SAML 자격 증명 공급자 사용.
매핑해야 하는 각 속성에 대해 다음 단계를 완료합니다.
1. [사용자 풀 속성(User pool attribute)] 열에서 속성을 선택합니다. 사용자 풀의 사용자 프로파일에 할당되는 속성입니다. 사용자 정의 속성은 표준 속성 뒤에 나열됩니다.
2. 속성 열에서 SAML 속성을 선택합니다. 공급자 디렉터리에서 전달되는 속성입니다.
  
  IdP는 참조를 위해 샘플 어SAML설션을 제공할 수 있습니다. 일부는 와 같은 간단한 이름을 IdPs 사용하는 반면email, 다른 일부는 다음과 비슷한 URL형식의 속성 이름을 사용합니다.
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
3. IdP와 Amazon Cognito 간에 추가 속성을 매핑하려면 다른 속성 추가(Add another attribute)를 선택합니다.
Save changes(변경 사항 저장)를 선택합니다.

사용자 풀에 대한 자격 증명 공급자 속성 매핑 지정(AWS CLI 및 AWS API)

다음 요청 본문은 SAML 공급자 “MyIdP” 속성 emailaddress, birthdate및 를 phone 사용자 풀 속성 email, 및 birthdate에 phone_number해당 순서로 UpdateIdentityProvider 매핑CreateIdentityProvider합니다. 이는 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 <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": "<SAML metadata XML>"
}
```
참고
만약 <SAML metadata XML> 에는 따옴표(")가 포함되어 있으므로 이스케이프해야 합니다(\").

메타데이터가 있는 예제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

기존 IdP에 대한 속성 매핑을 지정하려면

AWS CLI: aws cognito-idp update-identity-provider

예시: aws cognito-idp update-identity-provider --user-pool-id <user_pool_id> --provider-name <provider_name> --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
API/SDK: UpdateIdentityProvider

특정 IdP에 대한 속성 매핑 정보를 가져오려면

AWS CLI: aws cognito-idp describe-identity-provider

예시: aws cognito-idp describe-identity-provider --user-pool-id <user_pool_id> --provider-name <provider_name>
API/SDK: DescribeIdentityProvider

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

OIDC 사용자 풀 IdP 인증 흐름

페더레이션 사용자 연결