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

Express と Amazon Verified Permissions の統合

Verified Permissions Express 統合は、Express.js アプリケーションに認可を実装するためのミドルウェアベースのアプローチを提供します。この統合により、既存のルートハンドラーを変更することなく、きめ細かな認可ポリシーを使用して API エンドポイントを保護できます。統合は、リクエストを傍受し、定義されたポリシーに照らして評価し、承認されたユーザーのみが保護されたリソースにアクセスできるようにすることで、認可チェックを自動的に処理します。

このトピックでは、ポリシーストアの作成から認可ミドルウェアの実装とテストまで、Express 統合の設定について説明します。これらのステップに従うことで、最小限のコード変更で Express アプリケーションに堅牢な認可コントロールを追加できます。

このトピックでは、以下のGitHubリポジトリを参照します。

前提条件

Express 統合を実装する前に、以下を確認してください。

統合のセットアップ

ステップ 1: ポリシーストアを作成する

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

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

ステップ 2: 依存関係をインストールする

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

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

認可の設定

ステップ 1: Cedar スキーマを生成してアップロードする

スキーマは、アプリケーションのエンティティタイプやユーザーが実行できるアクションなど、アプリケーションの認可モデルを定義します。スキーマの名前空間を定義することをお勧めします。この例では、YourNamespace を使用します。Verified Permissions ポリシーストアにスキーマをアタッチすると、ポリシーが追加または変更されると、サービスは自動的にポリシーをスキーマに対して検証します。

@cedar-policy/authorization-for-expressjs パッケージは、アプリケーションの OpenAPI 仕様を分析し、Cedar スキーマを生成できます。具体的には、パスオブジェクトが仕様で必要です。

OpenAPI 仕様がない場合は、 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 ポリシーストアスキーマ。スキーマのフォーマットにヘルプが必要な場合は、Verifiedpermissions/examples 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 フレームワーク統合は、以前に生成されたスキーマに基づいてサンプルポリシーを生成することで、このプロセスをブートストラップするのに役立ちます。

本番アプリケーションでこの統合を使用する場合は、Infrastructure as a Code (IaaC) ツールを使用して新しいポリシーを作成することをお勧めします。詳細については、「AWS CloudFormationによる Amazon Verified Permissions リソースの作成 」を参照してください。

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」を参照してください。ポリシーの書式設定にヘルプが必要な場合は、確認済みのアクセス許可/例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 プロバイダーを接続する

デフォルトでは、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

認可ミドルウェアの実装

Express アプリケーションを更新して、認可ミドルウェアを含めます。この例では ID トークンを使用していますが、アクセストークンを使用することもできます。詳細については、 の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 アプリケーションのターミナルには、認可の決定に関する追加の詳細を示すログ出力が表示されます。

トラブルシューティング

次のステップ

基本的な統合を実装したら、次の点を考慮してください。