사용자 지정 속성을 Amazon Cognito로 전송하고 토큰에 주입 - 권장 가이드
요약사전 조건 및 제한 사항아키텍처도구모범 사례에픽문제 해결관련 리소스추가 정보

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

사용자 지정 속성을 Amazon Cognito로 전송하고 토큰에 주입

Carlos Alessandro Ribeiro 및 Mauricio Mendoza, Amazon Web Services

요약

Amazon Cognito 인증 프로세스에 사용자 지정 속성을 전송하면 애플리케이션에 추가 컨텍스트를 제공하고, 보다 세분화된 액세스 제어를 활성화하고, 사용자 프로필 및 인증 요구 사항을 더 쉽게 관리할 수 있습니다. 이러한 기능은 다양한 애플리케이션 및 시나리오에서 유용하며 애플리케이션의 전반적인 보안 및 기능을 개선하는 데 도움이 될 수 있습니다.

이 패턴은 애플리케이션이 액세스 토큰 또는 ID(ID) 토큰에 추가 컨텍스트를 제공해야 하는 경우 Amazon Cognito 인증 프로세스에 사용자 지정 속성을 보내는 방법을 보여줍니다. Node.js를 백엔드 애플리케이션으로 사용합니다. 애플리케이션은 Amazon Cognito 사용자 풀에서 사용자를 인증하고 토큰 생성에 필요한 사용자 지정 속성을 전달합니다. Amazon CognitoAWS Lambda 용 트리거를 사용하여 주요 코드 사용자 지정이나 상당한 노력 없이 인증 프로세스를 사용자 지정할 수 있습니다.

중요

이 패턴의 코드와 샘플은 데모용이므로 프로덕션 워크로드에는 권장되지 않습니다. 프로덕션 워크로드의 경우 클라이언트 측에서 추가 구성이 필요합니다. 이 패턴을 파일럿 또는 proof-of-concept 목적으로만 참조로 사용합니다.

사전 조건 및 제한 사항

사전 조건 

  • 활성 AWS 계정

  • Amazon Cognito 사용자 풀 및 AWS Lambda 함수를 생성하고 관리할 수 있는 권한

  • AWS Command Line Interface (AWS CLI), 설치 및 구성됨

  • Node.js를 지원하는 통합 개발 환경(IDE)

  • Node.js 버전 18 이상, 설치됨

  • npm 버전 8 이상, 설치됨

  • TypeScript, 설치됨

제한 사항

  • 이 패턴은 클라이언트 자격 증명 인증 흐름을 통한 애플리케이션 통합에는 적용되지 않습니다.

  • 사전 토큰 생성 트리거는 액세스 토큰 및 자격 증명 토큰의 일부 속성만 추가하거나 변경할 수 있습니다. 자세한 내용은 Amazon Cognito 설명서의 사전 토큰 생성 Lambda 트리거를 참조하세요.

아키텍처

대상 아키텍처

다음 다이어그램은이 패턴의 대상 아키텍처를 보여줍니다. 또한 Node.js 애플리케이션이 백엔드와 함께 작동하여 데이터베이스를 업데이트하는 방법을 보여줍니다. 그러나 백엔드 데이터베이스 업데이트는이 패턴의 범위를 벗어납니다.

사용자 지정 속성이 있는 액세스 토큰을 Amazon Cognito 사용자 풀에 발급하는 Node.js 애플리케이션입니다.

이 다이어그램은 다음 워크플로를 보여줍니다.

  1. Node.js 애플리케이션은 사용자 지정 속성이 있는 액세스 토큰을 Amazon Cognito 사용자 풀에 발급합니다.

  2. Amazon Cognito 사용자 풀은 액세스 및 ID 토큰을 사용자 지정하는 사전 토큰 생성 Lambda 함수를 시작합니다.

  3. Node.js 애플리케이션은 Amazon API Gateway를 호출합니다.

참고

이 아키텍처에 표시된 다른 아키텍처 구성 요소는 예를 들어에 불과하며이 패턴의 범위를 벗어납니다.

자동화 및 규모 조정

, , AWS 클라우드 개발 키트 (AWS CDK) HashiCorp Terraform 또는 지원되는 코드형 인프라(IaC) 도구를 사용하여 Amazon Cognito 사용자 풀AWS CloudFormation, AWS Lambda 함수, 데이터베이스 인스턴스 및 기타 리소스의 프로비저닝을 자동화할 수 있습니다. 배포 규모를 조정하려면 수동 배포와 관련된 오류를 방지하는 데 도움이 되는 지속적 통합 및 지속적 전달(CI/CD) 파이프라인을 사용합니다.

도구

AWS 서비스

  • Amazon API Gateway는 규모와 관계없이 REST, HTTP 및 WebSocket API를 생성, 게시, 유지 관리, 모니터링 및 보호하는 것을 지원합니다.

  • Amazon Cognito는 웹 및 모바일 앱에 대한 인증, 권한 부여 및 사용자 관리를 제공합니다.

  • Amazon Elastic Container Service(Amazon ECS)는 클러스터에서 컨테이너를 실행, 중지 및 관리하는 데 도움이 되는 빠르고 확장 가능한 컨테이너 관리 서비스입니다.

  • AWS Lambda는 서버를 프로비저닝하거나 관리할 필요 없이 코드를 실행하는 데 도움이 되는 컴퓨팅 서비스입니다. 필요할 때만 코드를 실행하며 자동으로 확장이 가능하므로 사용한 컴퓨팅 시간만큼만 비용을 지불합니다.

  • AWS SDK for JavaScript는 용 JavaScript API를 제공합니다 AWS 서비스. 이를 사용하여 Node.js 또는 브라우저용 라이브러리 또는 애플리케이션을 빌드할 수 있습니다.

기타 도구

  • Node.js는 확장 가능한 네트워크 애플리케이션을 구축하도록 설계된 이벤트 기반 JavaScript 런타임 환경입니다.

  • npm은 Node.js 환경에서 실행되는 소프트웨어 레지스트리로, 패키지를 공유 또는 대여하고 개인 패키지의 배포를 관리하는 데 사용됩니다.

모범 사례

다음 모범 사례를 구현하는 것이 좋습니다.

  • 보안 암호 및 민감한 데이터 - 애플리케이션 내에 보안 암호 또는 민감한 데이터를 저장하지 마십시오. , AWS AppConfig AWS Secrets Manager또는 AWS Systems Manager Parameter Store와 같이 애플리케이션이 데이터를 가져올 수 있는 외부 시스템을 사용합니다.

  • 표준화된 배포 - CI/CD 파이프라인을 사용하여 애플리케이션을 배포합니다. AWS CodeBuild 및와 같은 서비스를 사용할 수 있습니다AWS CodePipeline.

  • 토큰 만료 - 액세스 토큰의 짧은 만료 날짜를 설정합니다.

  • 보안 연결 사용 - 클라이언트 애플리케이션과 백엔드 간의 모든 통신은 SSL/TLS를 사용하여 암호화해야 합니다. AWS Certificate Manager (ACM)을 사용하여 SSL/TLS 인증서를 생성 및 관리하고 Amazon CloudFront 또는 Elastic Load Balancing을 사용하여 SSL/TLS 종료를 처리합니다.

  • 사용자 입력 검증 - 모든 사용자 입력이 주입 공격 및 기타 보안 취약성을 방지하기 위해 검증되었는지 확인합니다. Amazon API Gateway 및와 같은 입력 검증 라이브러리 및 서비스를 사용하여 일반적인 공격 벡터를 AWS WAF 방지합니다.

  • IAM 역할 사용 - AWS Identity and Access Management (IAM) 역할을 사용하여 AWS 리소스에 대한 액세스를 제어하고 권한이 부여된 사용자만 액세스할 수 있도록 합니다. 최소 권한 원칙을 따르고 각 사용자에게 역할을 수행하는 데 필요한 권한만 있는지 확인합니다.

  • 암호 정책 사용 - 최소 길이, 복잡성 및 만료와 같은 보안 요구 사항을 충족하는 암호 정책을 구성합니다. Secrets Manager 또는 AWS Systems Manager Parameter Store를 사용하여 암호를 안전하게 저장하고 관리합니다.

  • 멀티 팩터 인증(MFA) 활성화 - 모든 사용자에게 MFA를 활성화하여 추가 보안 계층을 제공하고 무단 액세스 위험을 줄입니다. AWS IAM Identity Center 또는 Amazon Cognito를 사용하여 MFA 및 기타 인증 방법을 활성화합니다.

  • 민감한 정보 안전하게 저장 - AWS Key Management Service (AWS KMS) 또는 기타 암호화 서비스를 사용하여 암호 및 액세스 토큰과 같은 민감한 정보를 안전하게 저장합니다.

  • 강력한 인증 방법 사용 - 인증 프로세스의 보안을 강화하려면 생체 인증 또는 다중 인증과 같은 강력한 인증 방법을 사용합니다.

  • 의심스러운 활동 모니터링 - AWS CloudTrail 및 기타 모니터링 도구를 사용하여 의심스러운 활동 및 잠재적 보안 위협을 모니터링합니다. 비정상적인 활동에 대한 자동 알림을 설정하고 Amazon GuardDuty 또는 AWS Security Hub를 사용하여 잠재적 위협을 탐지합니다.

  • 보안 정책 정기 검토 및 업데이트 - 보안 정책 및 절차를 정기적으로 검토하고 업데이트하여 변화하는 보안 요구 사항 및 모범 사례를 충족하는지 확인합니다. AWS Config 를 사용하여 보안 정책 및 절차의 변경 사항을 추적하고 감사합니다.

  • 자동 가입 - Amazon Cognito 사용자 풀에 대한 자동 가입을 활성화하지 마세요. 자세한 내용은 Amazon Cognito 사용자 풀을 사용한 사용자 가입 사기 및 SMS 펌프의 위험 감소(블로그 게시물)를 참조하세요.AWS

추가 모범 사례는 Amazon Cognito 설명서의 Amazon Cognito 사용자 풀에 대한 보안 모범 사례를 참조하세요. Amazon Cognito

에픽

작업설명필요한 기술

사용자 풀을 생성합니다.

  1. CLI 터미널에서 다음 명령을 입력하여 Amazon Cognito 사용자 풀을 생성합니다.

    aws cognito-idp create-user-pool \
   --pool-name <MyUserPool>

  2. 다음 명령을 입력하여 SDK for JavaScript와 함께 사용할 클라이언트 ID 및 보안 암호를 생성합니다.

    aws cognito-idp create-user-pool-client \
   --user-pool-id <UserPoolID>  \
   --client-name <MyNewClient> \
   --no-generate-secret \
   --explicit-auth-flows "USER_PASSWORD_AUTH" "ADMIN_NO_SRP_AUTH"

에서 사용자 풀을 설정하는 방법에 대한 자세한 내용과 지침은 사용자 풀 시작하기 및 사용자 풀에 기능 및 보안 옵션 추가를 AWS Management Console참조하세요. https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-next-steps.html

작은 정보

비용을 줄이려면 Essentials 플랜 또는 Lite 플랜을 사용하여이 패턴을 테스트합니다. 자세한 내용은 Amazon Cognito 요금을 참조하세요.

앱 개발자, AWS DevOps

사용자 풀에 사용자를 추가합니다.

다음 명령을 입력하여 Amazon Cognito 사용자 풀에 하나의 사용자를 생성합니다.

aws cognito-idp sign-up \
   --client-id <ClientID> \
   --username <jane@example.com> \
   --password <PASSWORD> \
   --user-attributes Name="email",Value="<jane@example.com>" Name="name",Value="<Jane>"
앱 개발자, AWS DevOps

앱 클라이언트를 사용자 풀에 추가합니다.

  1. Amazon Cognito 콘솔로 이동합니다.

  2. [사용자 풀(User pools)]을 선택합니다.

  3. 이전에 생성한 사용자 풀을 선택합니다.

  4. 애플리케이션 정의에서 인증 및 권한 부여 서비스를 생성하려는 애플리케이션 시나리오에 가장 적합한 애플리케이션 유형을 선택합니다.

  5. 애플리케이션 이름 지정에 설명이 포함된 이름을 입력하거나 기본 이름으로 진행합니다.

  6. 반환 URL 추가에서 사용자가 인증을 완료한 후에 대한 애플리케이션의 리디렉션 경로를 입력합니다.

  7. 애플리케이션 생성을 선택합니다. 앱 클라이언트를 생성한 후 고급 옵션을 설정할 수 있습니다.

AWS 시스템 관리자, AWS 관리자, AWS DevOps, 앱 개발자

사전 토큰 생성을 위한 Lambda 트리거를 생성합니다.

  1. Lambda 콘솔의 함수 페이지를 여세요.

  2. 함수 생성을 선택합니다.

  3. 새로 작성을 선택합니다.

  4. 기본 정보 창의 forFunction 이름에를 입력합니다myPreTokenGenerationLambdaFunction.

  5. 런타임에서 Node.js 22를 선택합니다.

  6. 아키텍처 세트 tox86_64를 그대로 둡니다.

  7. 함수 생성을 선택합니다.

  8. 코드 탭의 코드 소스에서이 패턴의 추가 리소스 섹션에 있는 샘플 Lambda 함수를 입력합니다. 이 Lambda 함수는 사용자 지정 속성을 ID 토큰 및 액세스 토큰에 주입합니다.

AWS DevOps, 앱 개발자

사용자 풀 워크플로를 사용자 지정합니다.

  1. Amazon Cognito 콘솔로 이동합니다.

  2. [사용자 풀(User pools)]을 선택합니다.

  3. 이전에 생성한 사용자 풀을 선택합니다.

  4. 왼쪽 탐색 창의 인증에서 확장을 선택합니다.

  5. Lambda 트리거 추가를 선택합니다.

  6. 사전 토큰 생성 트리거를 추가 또는 편집합니다.

  7. 트리거 유형에서 인증을 선택합니다.

  8. 인증에서 사전 토큰 생성 트리거를 선택합니다.

  9. Lambda 함수 할당에서를 선택합니다myPreTokenGenerationLambdaFunction.

  10. Lambda 트리거 추가를 선택합니다.

  11. 기본 기능의 트리거 이벤트 버전사용자 ID에 대한 액세스 토큰 사용자 지정또는 기본 기능 및 사용자 및 시스템 ID에 대한 액세스 토큰 사용자 지정을 선택합니다. 이 설정은 Amazon Cognito가 함수에 보내는 요청 파라미터를 업데이트하여 액세스 토큰 사용자 지정을 위한 필드를 포함합니다.

자세한 내용은 Amazon Cognito 설명서의 Lambda 트리거를 사용하여 사용자 풀 워크플로 사용자 지정을 참조하세요.

AWS DevOps, 앱 개발자
작업설명필요한 기술

Node.js 애플리케이션을 생성합니다.

  1. 터미널에 다음 명령을 입력합니다.

    mkdir my-app
cd my-app
npm init -y
npm install --save-dev typescript
npm i --save-dev @types/node
npm i amazon-cognito-identity-js
npx tsc --init
mkdir src
touch src/index.ts

  2. TypeScript 컴파일 스크립트를 포함하도록 package.json파일을 수정합니다.

    "scripts": {
  "start": "node src/index.js",
  "build": "tsc"
},
앱 개발자

인증 로직을 구현합니다.

  1. index.ts 파일을 엽니다.

  2. 이 패턴의 추가 리소스 섹션에 제공된 샘플 Typescript를 붙여넣습니다.

  3. index.ts 파일을 저장하고 닫습니다.

참고

자체 TypeScript 파일을 생성하거나 사용 사례에 따라 제공된 샘플을 수정할 수 있습니다.

앱 개발자

환경 변수 및 구성 파일을 구성합니다.

터미널에서 다음 명령을 입력하여 환경 변수를 생성합니다.

export USERNAME="<COGNITO_USER_NAME>"
export PASSWORD="<COGNITO_USER_PASSWORD>"
export USER_POOL_ID="<COGNITO_USER_ID>"
export CLIENT_ID="<COGNITO_CLIENT_ID>"
중요

보안 암호를 하드코딩하거나 자격 증명을 노출하지 마십시오.

앱 개발자

애플리케이션을 실행합니다.

다음 명령을 입력하여 애플리케이션을 실행하고 작동 중인지 확인합니다.

npm run build
npm start
앱 개발자

사용자 지정 속성이 토큰에 주입되었는지 확인합니다.

IDE의 디버깅 기능을 사용하여 액세스 및 ID 토큰을 봅니다. 사용자 지정 속성이 추가되었는지 확인합니다. 샘플 토큰은이 패턴의 추가 정보 섹션을 참조하세요.

앱 개발자

문제 해결

문제Solution

사용자를 인증하려고 할 때 클라이언트 ID가 잘못되었습니다.

이 오류는 일반적으로 생성된 클라이언트 보안 암호와 함께 클라이언트 ID를 사용할 때 발생합니다. 보안 암호가 연결되지 않은 상태에서 클라이언트 ID를 생성해야 합니다. 자세한 내용은 앱 클라이언트를 사용한 애플리케이션별 설정을 참조하세요.

관련 리소스

추가 정보

샘플 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의 사전 생성 토큰에 연결된 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.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "client_id": "<YOUR_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": "<USER_NAME>"
}

샘플 ID 토큰

액세스 토큰을 디코딩하여 추가된 사용자 지정 속성을 시각화할 수 있습니다. 다음은 샘플 액세스 토큰입니다.

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "cognito:username": "<USER_NAME>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "customApplicationData": "Custom data from a custom application",
  "aud": "<YOUR_CLIENT_ID>",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "id",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f",
  "email": "<USER_EMAIL>"
}