翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Express と Amazon Verified Permissions の統合
<a name="integration-express"></a>

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 ミドルウェアを使用した実装例

## 前提条件
<a name="express-integration-prerequisites"></a>

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) ID プロバイダー ( など[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) 適切なアクセス許可で設定されている

## 統合のセットアップ
<a name="express-integration-setup"></a>

### ステップ 1: ポリシーストアを作成する
<a name="setup-create-policy-store"></a>

以下を使用してポリシーストアを作成します AWS CLI。

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

**注記**  
レスポンスで返されたポリシーストア ID を保存して、以降のステップで使用します。

### ステップ 2: 依存関係をインストールする
<a name="setup-install-dependencies"></a>

Express アプリケーションに必要なパッケージをインストールします。

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

## 認可の設定
<a name="express-integration-configuration"></a>

### ステップ 1: Cedar スキーマを生成してアップロードする
<a name="config-generate-cedar-schema"></a>

スキーマは、アプリケーションのエンティティタイプやユーザーが実行できるアクションなど、アプリケーションの認可モデルを定義します。スキーマ[の名前空間](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: 認可ポリシーを作成する
<a name="config-create-authorization-policies"></a>

ポリシーが設定されていない場合、Cedar はすべての認可リクエストを拒否します。Express フレームワーク統合は、以前に生成されたスキーマに基づいてサンプルポリシーを生成することで、このプロセスをブートストラップするのに役立ちます。

本番アプリケーションでこの統合を使用する場合は、Infrastructure as a Code (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)」を参照してください。ポリシーの書式設定にヘルプが必要な場合は、[確認済みアクセス許可/例](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: ID プロバイダーを接続する
<a name="config-connect-identity-provider"></a>

デフォルトでは、Verified Permissions オーソライザーミドルウェアは API リクエストの認可ヘッダー内で提供される JSON ウェブトークン (JWT) を読み取り、ユーザー情報を取得します。Verified Permissions は、認可ポリシーの評価に加えて、トークンを検証できます。

`userPoolArn` および で、次のような名前`identity-source-configuration.txt`の ID ソース設定ファイルを作成します`clientId`。

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

次の AWS CLI コマンドを実行して ID ソースを作成し、 をポリシーストア 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
```

## 認可ミドルウェアの実装
<a name="express-integration-implementing-middleware"></a>

Express アプリケーションを更新して、認可ミドルウェアを含めます。この例では ID トークンを使用していますが、アクセストークンを使用することもできます。詳細については、 の[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);
```

## 統合のテスト
<a name="testing-authorization"></a>

異なるユーザートークンを使用して API エンドポイントにリクエストを行うことで、認可実装をテストできます。認可ミドルウェアは、定義されたポリシーに対して各リクエストを自動的に評価します。

たとえば、異なるアクセス許可を持つ異なるユーザーグループを設定した場合:
+ 管理者: すべてのリソースと管理機能へのフルアクセス
+ 従業員: リソースを表示、作成、更新できる
+ 顧客: リソースのみを表示可能

異なるユーザーでサインインし、さまざまなオペレーションを試みることで、アクセス許可ポリシーが期待どおりに動作していることを検証できます。Express アプリケーションのターミナルには、認可の決定に関する追加の詳細を示すログ出力が表示されます。

## トラブルシューティング
<a name="troubleshooting"></a>

認可に失敗した場合は、以下を試してください。  
+ ポリシーストア ID が正しいことを確認する
+ ID ソースが正しく設定されていることを確認します。
+ ポリシーの形式が正しいことを確認する
+ JWT トークンが有効であることを確認する

## 次の手順
<a name="express-integration-next-steps"></a>

基本的な統合を実装したら、次の点を考慮してください。
+ 特定の認可シナリオ用のカスタムマッパーの実装
+ 認可決定のモニタリングとログ記録の設定
+ さまざまなユーザーロールの追加ポリシーの作成