기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 사용자 지정 속성을 Amazon Cognito로 전송하고 토큰에 주입 *Carlos Alessandro Ribeiro 및 Mauricio Mendoza, Amazon Web Services* ## 요약 Amazon Cognito 인증 프로세스에 사용자 지정 속성을 전송하면 애플리케이션에 추가 컨텍스트를 제공하고, 보다 세분화된 액세스 제어를 활성화하고, 사용자 프로필 및 인증 요구 사항을 더 쉽게 관리할 수 있습니다. 이러한 기능은 다양한 애플리케이션 및 시나리오에서 유용하며 애플리케이션의 전반적인 보안 및 기능을 개선하는 데 도움이 될 수 있습니다. 이 패턴은 애플리케이션이 [액세스 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html) 또는 [ID(ID) 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html)에 추가 컨텍스트를 제공해야 하는 경우 Amazon Cognito 인증 프로세스에 사용자 지정 속성을 보내는 방법을 보여줍니다. Node.js를 백엔드 애플리케이션으로 사용합니다. 애플리케이션은 Amazon Cognito 사용자 [풀에서 사용자를](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html) 인증하고 토큰 생성에 필요한 사용자 지정 속성을 전달합니다. Amazon Cognito[AWS Lambda 용 트리거](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html)를 사용하여 주요 코드 사용자 지정이나 상당한 노력 없이 인증 프로세스를 사용자 지정할 수 있습니다. **중요** 이 패턴의 코드와 샘플은 데모용이므로 프로덕션 워크로드에는 권장되지 않습니다. 프로덕션 워크로드의 경우 클라이언트 측에서 추가 구성이 필요합니다. 이 패턴을 파일럿 또는 proof-of-concept 목적으로만 참조로 사용합니다. ## 사전 조건 및 제한 사항 **사전 조건 ** + 활성 AWS 계정 + Amazon Cognito 사용자 풀 및 AWS Lambda 함수를 생성하고 관리할 수 있는 권한 + AWS Command Line Interface (AWS CLI), [설치](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 및 [구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)됨 + Node.js를 지원하는 통합 개발 환경(IDE) + Node.js 버전 18 이상 설치 + npm 버전 8 이상 설치 + TypeScript [설치](https://www.typescriptlang.org/download/) **제한 사항 ** + 이 패턴은 클라이언트 자격 증명 인증 흐름을 통한 애플리케이션 통합에는 적용되지 않습니다. + 사전 토큰 생성 트리거는 액세스 토큰 및 자격 증명 토큰의 일부 속성만 추가하거나 변경할 수 있습니다. 자세한 내용은 Amazon Cognito 설명서의 [사전 토큰 생성 Lambda 트리거](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html)를 참조하세요. ## 아키텍처 **대상 아키텍처** 다음 다이어그램은 이 패턴의 대상 아키텍처를 보여 줍니다. 또한 Node.js 애플리케이션이 백엔드와 함께 작동하여 데이터베이스를 업데이트하는 방법을 보여줍니다. 그러나 백엔드 데이터베이스 업데이트는이 패턴의 범위를 벗어납니다. ![\[사용자 지정 속성이 있는 액세스 토큰을 Amazon Cognito 사용자 풀에 발급하는 Node.js 애플리케이션입니다.\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/images/pattern-img/9f0855e6-77f9-48c2-846e-f9c317127e1f/images/8c52c88b-8954-4b4c-aed3-fd8c22f84c1d.png) 이 다이어그램은 다음 워크플로를 보여줍니다. 1. Node.js 애플리케이션은 사용자 지정 속성이 있는 액세스 토큰을 Amazon Cognito 사용자 풀에 발급합니다. 1. Amazon Cognito 사용자 풀은 액세스 및 ID 토큰을 사용자 지정하는 사전 토큰 생성 Lambda 함수를 시작합니다. 1. Node.js 애플리케이션은 Amazon API Gateway를 통해 API 직접 호출을 실행합니다. **참고** 이 아키텍처에 표시된 다른 아키텍처 구성 요소는 예를 들어에 불과하며이 패턴의 범위를 벗어납니다. **자동화 및 규모 조정** , , [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) [HashiCorp Terraform](https://www.terraform.io/docs) 또는 지원되는 코드형 인프라(IaC) 도구를 사용하여 Amazon Cognito 사용자 풀[AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html), AWS Lambda 함수, 데이터베이스 인스턴스 및 기타 리소스의 프로비저닝을 자동화할 수 있습니다. 배포를 확장하려면 수동 배포와 관련된 오류를 방지하는 데 도움이 되는 지속적 통합 및 지속적 전달(CI/CD) 파이프라인을 사용합니다. ## 도구 **AWS 서비스** + [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)는 규모와 관계없이 REST, HTTP 및 WebSocket API를 생성, 게시, 유지 관리, 모니터링 및 보호하는 것을 지원합니다. + [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html)는 웹 및 모바일 앱에 대한 인증, 권한 부여 및 사용자 관리를 제공합니다. + [Amazon Elastic Container Service(Amazon ECS)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html)는 클러스터에서 컨테이너를 실행, 중지 및 관리하는 데 도움이 되는 빠르고 확장 가능한 컨테이너 관리 서비스입니다. + [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)는 서버를 프로비저닝하거나 관리할 필요 없이 코드를 실행하는 데 도움이 되는 컴퓨팅 서비스입니다. 필요할 때만 코드를 실행하며 자동으로 확장이 가능하므로 사용한 컴퓨팅 시간만큼만 비용을 지불합니다. + [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html)는 용 JavaScript API를 제공합니다 AWS 서비스. 이 API를 사용하여 Node.js용 또는 브라우저용 라이브러리 또는 애플리케이션을 빌드할 수 있습니다. **기타 도구** + [Node.js](https://nodejs.org/en/docs/)는 확장 가능한 네트워크 애플리케이션 구축을 위해 설계된 이벤트 기반 JavaScript 런타임 환경입니다. + [npm](https://docs.npmjs.com/about-npm)은 Node.js 환경에서 실행되는 소프트웨어 레지스트리로, 패키지를 공유 또는 대여하고 개인 패키지의 배포를 관리하는 데 사용됩니다. ## 모범 사례 다음 모범 사례를 구현하는 것이 좋습니다. + **보안 암호 및 민감한 데이터** - 애플리케이션 내에 시크릿 또는 민감한 데이터를 저장하지 마십시오. , [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html) [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)또는 [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)와 같이 애플리케이션이 데이터를 가져올 수 있는 외부 시스템을 사용합니다. + **표준화된 배포** - CI/CD 파이프라인을 사용하여 애플리케이션을 배포합니다. [AWS CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html) 및와 같은 서비스를 사용할 수 있습니다[AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html). + **토큰 만료** - 액세스 토큰의 짧은 만료 날짜를 설정합니다. + **보안 연결 사용** - 클라이언트 애플리케이션과 백엔드 간의 모든 통신은 SSL/TLS를 사용하여 암호화해야 합니다. [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html)을 사용하여 SSL/TLS 인증서를 생성 및 관리하고 [Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) 또는 [Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/what-is-load-balancing.html)을 사용하여 SSL/TLS 종료를 처리합니다. + **사용자 입력 검증** - 모든 사용자 입력이 주입 공격 및 기타 보안 취약성을 방지하기 위해 검증되었는지 확인합니다. Amazon API Gateway 및와 같은 입력 검증 라이브러리 및 서비스를 사용하여 일반적인 공격 벡터를 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html#waf-intro) 방지합니다. + **IAM 역할 사용** - [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) 역할을 사용하여 AWS 리소스에 대한 액세스를 제어하고 권한이 있는 사용자만 액세스할 수 있도록 합니다. 최소 권한 원칙을 따르고 각 사용자에게 역할을 수행하는 데 필요한 권한만 있는지 확인합니다. + **암호 정책 사용** - 최소 길이, 복잡성 및 만료와 같은 보안 요구 사항을 충족하는 암호 정책을 구성합니다. Secrets Manager 또는 AWS Systems Manager Parameter Store를 사용하여 암호를 안전하게 저장하고 관리합니다. + **다중 인증(MFA) 활성화 -** 모든 사용자에게 MFA를 활성화하여 추가 보안 계층을 제공하고 무단 액세스 리스크를 줄입니다. [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) 또는 Amazon Cognito를 사용하여 MFA 및 기타 인증 방법을 활성화합니다. + **민감한 정보 안전하게 저장** - [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) 또는 기타 암호화 서비스를 사용하여 암호 및 액세스 토큰과 같은 민감한 정보를 안전하게 저장합니다. + **강력한 인증 방법 사용** - 인증 프로세스의 보안을 강화하려면 생체 인증 또는 다중 인증과 같은 강력한 인증 방법을 사용합니다. + **의심스러운 활동 모니터링** - [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) 및 기타 모니터링 도구를 사용하여 의심스러운 활동 및 잠재적 보안 위협을 모니터링합니다. 비정상적인 활동에 대한 자동 알림을 설정하고 [Amazon GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html) 또는 [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html)를 사용하여 잠재적 위협을 탐지합니다. + **보안 정책 정기 검토 및 업데이트** - 보안 정책 및 절차를 정기적으로 검토하고 업데이트하여 변화하는 보안 요구 사항 및 모범 사례를 충족하는지 확인합니다. AWS Config 를 사용하여 보안 정책 및 절차의 변경 사항을 추적하고 감사합니다. + **자동 가입** - Amazon Cognito 사용자 풀에 대한 자동 가입을 활성화하지 마세요. 자세한 내용은 [ Amazon Cognito 사용자 풀을 사용한 사용자 가입 사기 및 SMS 펌프의 위험 감소(블로그 게시물)를 참조하세요](https://aws.amazon.com/blogs/security/reduce-risks-of-user-sign-up-fraud-and-sms-pumping-with-amazon-cognito-user-pools/).AWS 추가 모범 사례는 [ Amazon Cognito 설명서의 Amazon Cognito 사용자 풀에 대한 보안 모범 사례를 참조하세요](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-security-best-practices.html). Amazon Cognito ## 에픽 ### AWS 리소스 설정 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 사용자 풀을 생성합니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)에서 사용자 풀을 설정하는 방법에 대한 자세한 내용과 지침은 사용자 풀 [시작하기 및 사용자 풀](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-user-pools.html)에 기능 및 보안 옵션 추가를 AWS Management Console참조하세요. [https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-next-steps.html](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-next-steps.html) 비용을 줄이려면 Essentials 플랜 또는 Lite 플랜을 사용하여이 패턴을 테스트합니다. 자세한 내용은 [Amazon Cognito 요금](https://aws.amazon.com/cognito/pricing/)을 참조하세요. | 앱 개발자, AWS DevOps | | 사용자 풀에 사용자를 추가합니다. | 다음 명령을 입력하여 Amazon Cognito 사용자 풀에 하나의 사용자를 생성합니다.
aws cognito-idp sign-up \
   --client-id  \
   --username  \
   --password  \
   --user-attributes Name="email",Value="" Name="name",Value=""
| 앱 개발자, AWS DevOps | | 사용자 풀에 앱 클라이언트를 추가합니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | AWS 시스템 관리자, AWS 관리자, AWS DevOps, 앱 개발자 | | 사전 토큰 생성을 위한 Lambda 트리거를 생성합니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | AWS DevOps, 앱 개발자 | | 사용자 풀 워크플로를 사용자 지정합니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)자세한 내용은 Amazon Cognito 설명서의 [Lambda 트리거를 사용하여 사용자 풀 워크플로 사용자 지정](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html)을 참조하세요. | AWS DevOps, 앱 개발자 | ### Node.js 애플리케이션 생성 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | Node.js 애플리케이션을 생성합니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | 앱 개발자 | | 인증 로직을 구현합니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)자체 TypeScript 파일을 생성하거나 사용 사례에 따라 제공된 샘플을 수정할 수 있습니다. | 앱 개발자 | | 환경 변수 및 구성 파일을 구성합니다. | 터미널에서 다음 명령을 입력하여 환경 변수를 생성합니다.
export USERNAME=""
export PASSWORD=""
export USER_POOL_ID=""
export CLIENT_ID=""
시크릿을 하드코딩하거나 자격 증명을 노출하지 마십시오. | 앱 개발자 | | 애플리케이션을 실행합니다. | 다음 명령을 입력하여 애플리케이션을 실행하고 작동 중인지 확인합니다.
npm run build
npm start
| 앱 개발자 | | 사용자 지정 속성이 토큰에 주입되었는지 확인합니다. | IDE의 디버깅 기능을 사용하여 액세스 및 ID 토큰을 봅니다. 사용자 지정 속성이 추가되었는지 확인합니다. 샘플 토큰은 이 패턴의 [추가 정보](#send-custom-attributes-cognito-additional) 섹션을 참조하세요. | 앱 개발자 | ## 문제 해결 | 문제 | Solution | | --- | --- | | 사용자를 인증하려고 할 때 클라이언트 ID가 잘못되었습니다. | 이 오류는 일반적으로 생성된 클라이언트 시크릿과 함께 클라이언트 ID를 사용할 때 발생합니다. 시크릿이 연결되지 않은 상태에서 클라이언트 ID를 생성해야 합니다. 자세한 내용은 [앱 클라이언트를 사용한 애플리케이션별 설정](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html)을 참조하세요. | ## 관련 리소스 + [Lambda 트리거를 사용하여 사용자 풀 워크플로 사용자 지정](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html)(Amazon Cognito 설명서) + [사전 토큰 생성 Lambda 트리거](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html)(Amazon Cognito 설명서) + [CognitoIdentityProviderClient](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cognito-identity-provider/)(AWS SDK for JavaScript 문서) + [cognito-idp](https://awscli.amazonaws.com/v2/documentation/api/2.0.34/reference/cognito-idp/index.html#cli-aws-cognito-idp)(AWS CLI 문서) ## 추가 정보 **샘플 TypeScript 파일** 다음 코드 샘플은 AWS SDK를 사용하여 사용자 지정 속성을 Amazon Cognito로 전송하여 인증 프로세스를 호출하는 TypeScript 파일입니다. ``` import * as AmazonCognitoIdentity from "amazon-cognito-identity-js"; const userPoolId: string = process.env.USER_POOL_ID ?? ''; const clientId: string = process.env.CLIENT_ID ?? ''; const poolData = { UserPoolId: userPoolId, ClientId: clientId }; const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData); export const loginWithCognitoSDK = function (userName: string, password: string) { const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({ Username: userName, Password: password, ClientMetadata: { customGroup: "MyCustomGroup", customApplicationData: "Custom data from a custom application" } }); const userData = { Username: userName, Pool: userPool }; const cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData); // Authenticate the user using the authenticationDetails object cognitoUser.authenticateUser(authenticationDetails, { onSuccess: function (result: any) {}, onFailure: function (err: any) {}, }); } loginWithCognitoSDK(process.env.USERNAME ?? '', process.env.PASSWORD ?? ''); ``` 이 샘플은 SDK for JavaScript의 `AuthenticationDetails` 모델을 사용하여 사용자 이름, 암호 및를 제공합니다`ClientMetadada`. Amazon Cognito에서 인증한 후 액세스 및 ID 토큰에서 클라이언트 메타데이터를 검색할 수 있습니다. **샘플 Lambda 함수** 다음 코드 샘플은 Amazon Cognito의 [사전 생성 토큰](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html)에 연결된 Lambda 함수입니다. Amazon Cognito에서 사용하는 액세스 토큰과 ID 토큰을 사용자 지정하는 데 도움이 됩니다. 토큰은 아키텍처 간의 통합을 통해 전달됩니다. 이 샘플에는 라는 사용자 지정 클레임 속성`customApplicationData`과 라는 사용자 지정 그룹 이름이 포함되어 있습니다`MyCustomGroup`. ``` export const handler = async(event, context, callback) => { event.response = { claimsOverrideDetails: { claimsToAddOrOverride: { customApplicationData: event.request.clientMetadata.customApplicationData }, groupOverrideDetails: { groupsToOverride: [event.request.clientMetadata.customGroup] } } }; callback(null, event); }; ``` **샘플 액세스 토큰** 액세스 토큰을 디코딩하여 추가된 사용자 지정 속성을 시각화할 수 있습니다. 다음은 샘플 액세스 토큰입니다. ``` { "sub": "6daf331f-4451-48b4-abde-774579299204", "cognito:groups": [ "MyCustomGroup" ], "iss": "https://cognito-idp..amazonaws.com/", "client_id": "", "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc", "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e", "token_use": "access", "scope": "aws.cognito.signin.user.admin", "auth_time": 1677979246, "exp": 1677982846, "iat": 1677979246, "jti": "5c9c2708-a871-4428-bd9b-18ad261bea90", "username": "" } ``` **샘플 ID 토큰** 액세스 토큰을 디코딩하여 추가된 사용자 지정 속성을 시각화할 수 있습니다. 다음은 샘플 액세스 토큰입니다. ``` { "sub": "6daf331f-4451-48b4-abde-774579299204", "cognito:groups": [ "MyCustomGroup" ], "iss": "https://cognito-idp..amazonaws.com/", "cognito:username": "", "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc", "customApplicationData": "Custom data from a custom application", "aud": "", "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e", "token_use": "id", "auth_time": 1677979246, "exp": 1677982846, "iat": 1677979246, "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f", "email": "" } ```