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

# Express와 Amazon Verified Permissions 통합
Express 사용

Verified Permissions Express 통합은 Express.js 애플리케이션에서 권한 부여를 구현하는 미들웨어 기반 접근 방식을 제공합니다. 이 통합을 통해 기존 라우팅 핸들러를 수정하지 않고도 세분화된 권한 부여 정책을 사용하여 API 엔드포인트를 보호할 수 있습니다. 통합은 요청을 가로채고, 정의된 정책에 따라 요청을 평가하고, 승인된 사용자만 보호된 리소스에 액세스할 수 있도록 하여 권한 부여 검사를 자동으로 처리합니다.

이 주제에서는 정책 스토어 생성부터 권한 부여 미들웨어 구현 및 테스트에 이르기까지 Express 통합을 설정하는 방법을 안내합니다. 이 단계를 따르면 코드 변경을 최소화하면서 Express 애플리케이션에 강력한 권한 부여 제어를 추가할 수 있습니다.

이 주제 전체에서 다음 GitHub리포지토리가 참조됩니다.
+ [cedar-policy/authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs) - Express.js용 Cedar 권한 부여 미들웨어
+ [verifiedpermissions/authorization-clients-js](https://github.com/verifiedpermissions/authorization-clients-js) - JavaScript에 대한 Verified Permissions 권한 부여 클라이언트
+ [verifiedpermissions/examples/express-petstore](https://github.com/verifiedpermissions/examples/tree/main/express-petstore) - Express.js 미들웨어를 사용한 구현 예제

## 사전 조건


Express 통합을 구현하기 전에 다음을 갖추어야 합니다.
+ Verified Permissions에 액세스할 수 있는 [AWS 계정](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html) 
+ [Node.js](https://nodejs.org/) 및 [npm](https://docs.npmjs.com/) 설치됨
+ [Express.js](https://expressjs.com/) 애플리케이션
+ OpenID Connect(OIDC) 자격 증명 공급자(예: [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html))
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html) 적절한 권한으로 구성됨

## 통합 설정


### 1단계: 정책 스토어 생성


 AWS CLI다음을 사용하여 정책 스토어를 생성합니다.

```
aws verifiedpermissions create-policy-store --validation-settings "mode=STRICT"
```

**참고**  
후속 단계에서 사용할 수 있도록 응답에 반환된 정책 스토어 ID를 저장합니다.

### 2단계: 종속성 설치


Express 애플리케이션에 필요한 패키지를 설치합니다.

```
npm i --save @verifiedpermissions/authorization-clients-js
npm i --save @cedar-policy/authorization-for-expressjs
```

## 권한 부여 구성


### 1단계: Cedar 스키마 생성 및 업로드


스키마는 애플리케이션의 엔터티 유형과 사용자가 수행할 수 있는 작업을 포함하여 애플리케이션에 대한 권한 부여 모델을 정의합니다. 스키마의 [네임스페이스](https://docs.cedarpolicy.com/overview/terminology.html#term-namespaces)를 정의하는 것이 좋습니다. 이 예제에서는 `YourNamespace`을 사용합니다. 스키마를 Verified Permissions 정책 스토어에 연결하면 정책이 추가되거나 수정되면 서비스가 스키마에 대해 정책을 자동으로 검증합니다.

`@cedar-policy/authorization-for-expressjs` 패키지는 애플리케이션의 [OpenAPI 사양을](https://swagger.io/specification/) 분석하고 Cedar 스키마를 생성할 수 있습니다. 특히 경로 객체는 사양에 필요합니다.

OpenAPI 사양이 없는 경우 [express-openapi-generator](https://github.com/nklisch/express-openapi-generator) 패키지의 빠른 지침에 따라 OpenAPI 사양을 생성할 수 있습니다.

OpenAPI 사양에서 스키마를 생성합니다.

```
npx @cedar-policy/authorization-for-expressjs generate-schema --api-spec schemas/openapi.json --namespace YourNamespace --mapping-type SimpleRest
```

그런 다음에 사용할 Cedar 스키마의 형식을 지정합니다 AWS CLI. 필요한 특정 형식에 대한 자세한 내용은 섹션을 참조하세요[Amazon Verified Permissions 정책 스토어 스키마](schema.md). 스키마 형식을 지정하는 데 도움이 필요한 경우 [verifiedpermissions/examples](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts) GitHub리포지토리`prepare-cedar-schema.sh`에 라는 스크립트가 있습니다. 다음은 `v2.cedarschema.forAVP.json` 파일에서 Verified Permissions 형식의 스키마를 출력하는 해당 스크립트에 대한 호출 예제입니다.

```
./scripts/prepare-cedar-schema.sh v2.cedarschema.json v2.cedarschema.forAVP.json
```

형식이 지정된 스키마를 정책 스토어에 업로드하고를 정책 스토어 ID`policy-store-id`로 바꿉니다.

```
aws verifiedpermissions put-schema \
  --definition file://v2.cedarschema.forAVP.json \
  --policy-store-id policy-store-id
```

### 2단계: 권한 부여 정책 생성


정책이 구성되지 않은 경우 Cedar는 모든 권한 부여 요청을 거부합니다. Express 프레임워크 통합은 이전에 생성된 스키마를 기반으로 예제 정책을 생성하여이 프로세스를 부트스트랩하는 데 도움이 됩니다.

프로덕션 애플리케이션에서이 통합을 사용하는 경우 코드형 인프라(IaaC) 도구를 사용하여 새 정책을 생성하는 것이 좋습니다. 자세한 내용은 [를 사용하여 Amazon Verified Permissions 리소스 생성 AWS CloudFormation](cloudformation-verified-permissions.md) 단원을 참조하십시오.

샘플 Cedar 정책 생성:

```
npx @cedar-policy/authorization-for-expressjs generate-policies --schema v2.cedarschema.json
```

그러면 `/policies` 디렉터리에 샘플 정책이 생성됩니다. 그런 다음 사용 사례에 따라 이러한 정책을 사용자 지정할 수 있습니다. 예제:

```
// Defines permitted administrator user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|administrator",
    action,
    resource
);

// Defines permitted employee user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|employee",
    action in
        [YourNamespace::Action::"GET /resources",
         YourNamespace::Action::"POST /resources",
         YourNamespace::Action::"GET /resources/{resourceId}",
         YourNamespace::Action::"PUT /resources/{resourceId}"],
    resource
);
```

와 함께 사용할 정책의 형식을 지정합니다 AWS CLI. 필요한 형식에 대한 자세한 내용은 *AWS CLI 참조*의 [create-policy](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-policy.html)를 참조하세요. 정책 형식 지정에 도움이 필요한 경우 [verifiedpermissions/examples](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts) GitHub리포지토리`convert_cedar_policies.sh`에 라는 스크립트가 있습니다. 다음은 해당 스크립트에 대한 호출입니다.

```
./scripts/convert_cedar_policies.sh
```

형식이 지정된 정책을 Verified Permissions에 업로드하여 `policy_1.json`를 정책 파일의 경로 및 이름으로 바꾸고를 정책 스토어 ID`policy-store-id`로 바꿉니다.

```
aws verifiedpermissions create-policy \
  --definition file://policies/json/policy_1.json \
  --policy-store-id policy-store-id
```

### 3단계: 자격 증명 공급자 연결


기본적으로 Verified Permissions 권한 부여자 미들웨어는 사용자 정보를 가져오기 위해 API 요청의 권한 부여 헤더 내에 제공된 JSON 웹 토큰(JWT)을 읽습니다. Verified Permissions는 권한 부여 정책 평가를 수행하는 것 외에도 토큰을 검증할 수 있습니다.

`userPoolArn` 및를 사용하여 `clientId`다음과 `identity-source-configuration.txt` 같은 이름의 ID 소스 구성 파일을 생성합니다.

```
{
    "cognitoUserPoolConfiguration": {
        "userPoolArn": "arn:aws:cognito-idp:region:account:userpool/pool-id",
        "clientIds": ["client-id"],
        "groupConfiguration": {
            "groupEntityType": "YourNamespace::UserGroup"
        }
    }
}
```

다음 AWS CLI 명령을 실행하여 자격 증명 소스를 생성하고를 정책 스토어 ID`policy-store-id`로 바꿉니다.

```
aws verifiedpermissions create-identity-source \
  --configuration file://identity-source-configuration.txt \
  --policy-store-id policy-store-id \
  --principal-entity-type YourNamespace::User
```

## 권한 부여 미들웨어 구현


권한 부여 미들웨어를 포함하도록 Express 애플리케이션을 업데이트합니다. 이 예제에서는 자격 증명 토큰을 사용하지만 액세스 토큰도 사용할 수 있습니다. 자세한 내용은의 [authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs)를 참조하세요GitHub.

```
const { ExpressAuthorizationMiddleware } = require('@cedar-policy/authorization-for-expressjs');

const { AVPAuthorizationEngine } = require('@verifiedpermissions/authorization-clients');

const avpAuthorizationEngine = new AVPAuthorizationEngine({
    policyStoreId: 'policy-store-id',
    callType: 'identityToken'
});

const expressAuthorization = new ExpressAuthorizationMiddleware({
    schema: {
        type: 'jsonString',
        schema: fs.readFileSync(path.join(__dirname, '../v4.cedarschema.json'), 'utf8'),
    },
    authorizationEngine: avpAuthorizationEngine,
    principalConfiguration: { type: 'identityToken' },
    skippedEndpoints: [],
    logger: {
        debug: (s) => console.log(s),
        log: (s) => console.log(s),
    }
});

// Add the middleware to your Express application
app.use(expressAuthorization.middleware);
```

## 통합 테스트


다른 사용자 토큰을 사용하여 API 엔드포인트에 요청하여 권한 부여 구현을 테스트할 수 있습니다. 권한 부여 미들웨어는 정의된 정책을 기준으로 각 요청을 자동으로 평가합니다.

예를 들어 권한이 다른 다른 사용자 그룹을 설정한 경우:
+ 관리자: 모든 리소스 및 관리 기능에 대한 전체 액세스
+ 직원: 리소스를 보고, 생성하고, 업데이트할 수 있습니다.
+ 고객: 리소스만 볼 수 있음

다른 사용자로 로그인하고 다양한 작업을 시도하여 권한 정책이 예상대로 작동하는지 확인할 수 있습니다. Express 애플리케이션의 터미널에서 권한 부여 결정에 대한 추가 세부 정보를 제공하는 로그 출력을 볼 수 있습니다.

## 문제 해결


권한 부여에 실패한 경우 다음을 시도하세요.  
+ 정책 스토어 ID가 올바른지 확인
+ 자격 증명 소스가 올바르게 구성되었는지 확인
+ 정책 형식이 올바른지 확인
+ JWT 토큰이 유효한지 확인

## 다음 단계


기본 통합을 구현한 후 다음 사항을 고려하세요.
+ 특정 권한 부여 시나리오에 대한 사용자 지정 매퍼 구현
+ 권한 부여 결정을 위한 모니터링 및 로깅 설정
+ 다양한 사용자 역할에 대한 추가 정책 생성