React 웹사이트 인증

React 웹사이트 인증 생성기는 Amazon Cognito를 사용하여 React 웹사이트에 인증 기능을 추가합니다.

이 생성기는 CDK 또는 Terraform 인프라를 구성하여 Cognito 사용자 풀 및 관련 Identity Pool, 사용자 로그인 흐름을 처리하는 호스팅된 UI, 그리고 React 웹사이트와의 통합을 설정합니다.

사용 방법

React 웹사이트에 인증 추가하기

다음 두 가지 방법으로 React 웹사이트에 인증을 추가할 수 있습니다:

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#website#auth
5. 필수 매개변수 입력
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth

yarn

yarn nx g @aws/nx-plugin:ts#website#auth

npm

npx nx g @aws/nx-plugin:ts#website#auth

bun

bunx nx g @aws/nx-plugin:ts#website#auth

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --dry-run

옵션

매개변수	타입	기본값	설명
project 필수	string	-	웹사이트의 루트 디렉토리입니다.
cognitoDomain	string	-	사용할 Cognito 도메인 접두사입니다. 생략하면 npm scope와 웹사이트 프로젝트 이름에서 값이 파생됩니다.
allowSignup	boolean		자가 가입을 허용할지 여부입니다.
iac	inherit | cdk | terraform	inherit	선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력 결과

React 웹사이트에 다음과 같은 변경 사항이 적용됩니다:

• 디렉터리src

  • 디렉터리components

    • 디렉터리CognitoAuth

      • index.tsx 기본 인증 컴포넌트
  • main.tsx CognitoAuth 컴포넌트를 적용하도록 업데이트

인프라

이 생성기는 선택한 iacProvider 기반으로 인프라를 코드 형태로 제공하므로, packages/common 디렉터리에 관련 CDK 구축 요소 또는 Terraform 모듈을 포함하는 프로젝트를 생성합니다.

공통 인프라스트럭처 코드 프로젝트의 구조는 다음과 같습니다:

CDK

• 디렉터리packages/common/constructs

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소

      • …
    • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소

      • …
    • index.ts app의 구축 요소를 익스포트하는 진입점
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 ts#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Terraform

• 디렉터리packages/common/terraform

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기 전용 Terraform 모듈

      • …
    • 디렉터리core/ app 내 모듈에서 재사용되는 일반적 모듈

      • …
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 terraform#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

선택한 iacProvider에 따라 다음 인프라 코드가 생성됩니다:

CDK

• 디렉터리packages/common/constructs/src

  • 디렉터리core

    • user-identity.ts 사용자 풀 및 Identity Pool을 정의하는 Construct

Terraform

• 디렉터리packages/common/terraform/src

  • 디렉터리core

    • 디렉터리user-identity

      • main.tf Identity 구성을 위한 모듈 래퍼
      • 디렉터리identity

        • identity.tf Cognito 사용자 풀 및 Identity Pool을 포함한 핵심 Identity 인프라
      • 디렉터리add-callback-url

        • add-callback-url.tf 기존 사용자 풀 클라이언트에 콜백 URL 추가 모듈

아키텍처

이 생성기는 기존 정적 웹사이트 아키텍처에 Amazon Cognito 사용자 풀(로그인용)과 Identity Pool(로그인한 사용자를 범위가 지정된 IAM 자격 증명으로 페더레이션하기 위한)을 추가합니다:

위협 보호

사용자 풀은 Cognito Plus 기능 플랜에서 생성되며, 표준 인증에 대해 위협 보호가 AUDIT 모드로 설정됩니다. 감사 모드에서 Cognito는 각 로그인에 위험 수준을 할당하고 사용자를 차단하지 않고 평가를 CloudWatch에 기록합니다.

사용자에 대한 위험 평가를 관찰한 후, 위험한 활동에 자동으로 대응하도록(예: MFA 요구 또는 로그인 차단) 전체 기능 적용 모드로 전환할 수 있습니다:

CDK

packages/common/constructs/src/core/user-identity.ts에서 standardThreatProtectionMode를 StandardThreatProtectionMode.FULL_FUNCTION으로 설정하세요.

Terraform

packages/common/terraform/src/core/user-identity/identity/identity.tf의 user_pool_add_ons 블록에서 advanced_security_mode를 ENFORCED로 설정하세요.

웹 애플리케이션 방화벽 (WAF)

기본적으로 사용자 풀은 AWSManagedRulesCommonRuleSet 및 AWSManagedRulesKnownBadInputsRuleSet 관리형 규칙 그룹을 사용하는 AWS WAFv2 Web ACL과 연결됩니다. 자체 Web ACL을 관리하거나 필요하지 않은 경우 이 기능을 비활성화할 수 있습니다:

CDK

new UserIdentity(this, 'Identity', { enableWaf: false });

Terraform

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"

  enable_waf = false
}

인프라 사용 방법

CDK

웹사이트 선언 이전에 사용자 Identity 인프라를 스택에 추가해야 합니다:

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, UserIdentity } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new UserIdentity(this, 'Identity');

    new MyWebsite(this, 'MyWebsite');
  }
}

UserIdentity Construct는 웹사이트가 올바른 Cognito 사용자 풀을 가리킬 수 있도록 필요한 런타임 구성을 자동으로 추가합니다.

SMS 역할 보존

사용자 풀은 Cognito가 SMS 메시지를 전송하기 위해 맡는 IAM 역할로 지원됩니다. 이 역할의 제거 정책은 사용자 풀의 정책을 따릅니다 — 기본적으로 CDK의 UserPool은 RemovalPolicy.RETAIN을 사용하므로, cdk destroy 실행 시 사용자 풀과 SMS 역할이 모두 보존되며 더 이상 필요하지 않은 경우 수동으로 정리해야 합니다.

Terraform

사용자 Identity 모듈을 추가하고 웹사이트가 해당 모듈에 종속되도록 설정해야 합니다:

packages/infra/src/main.tf

# 런타임 구성 추가를 위해 먼저 사용자 Identity 배포
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# 런타임 구성을 포함하기 위해 Identity 이후에 웹사이트 배포
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # 런타임 구성 추가를 위해 Identity 먼저 배포 확인
  depends_on = [module.user_identity]
}

사용자 Identity 모듈은 웹사이트가 올바른 Cognito 사용자 풀을 가리킬 수 있도록 필요한 런타임 구성을 자동으로 추가합니다.

프로덕션 환경에서 localhost 콜백 URL 제거

생성된 사용자 풀 클라이언트는 CloudFront 배포 URL을 OAuth 콜백/로그아웃 URL로 허용하며, 배포된 풀에 대한 로컬 개발을 위해 http://localhost:4200 및 http://localhost:4300도 허용합니다.

프로덕션 스테이지에서는 http://localhost 콜백/로그아웃 URL을 제거하여 허용 목록을 실제 애플리케이션 오리진으로만 제한하는 것이 권장됩니다.

CDK

packages/common/constructs/src/core/user-identity.ts에서 콜백/로그아웃 URL을 편집하세요.

Terraform

packages/common/terraform/src/core/user-identity/identity/identity.tf에서 callback_urls/logout_urls를 편집하세요.

인증된 사용자에게 액세스 권한 부여

API 호출 권한 부여와 같이 인증된 사용자에게 특정 작업 수행 권한을 부여하려면 Identity Pool의 인증된 역할에 IAM 정책 문을 추가할 수 있습니다:

CDK

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, UserIdentity, MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const identity = new UserIdentity(this, 'Identity');
    const api = new MyApi(this, 'MyApi');

    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new MyWebsite(this, 'MyWebsite');
  }
}

Terraform

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# 인증된 사용자가 Fast API 호출할 수 있는 권한 추가
resource "aws_iam_role_policy" "authenticated_fast_api_invoke" {
  name = "authenticated-user-invoke-my-api"
  role = module.user_identity.authenticated_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "execute-api:Invoke"
        ]
        Resource = "${module.my_api.api_execution_arn}/*"
      }
    ]
  })
}