メインコンテンツまでスキップ

Kendra で S3 ドキュメントのアクセスコントロールを行う方法

· 約18分
Yusuke Wada

Amazon Kendra (以降、Kendra) は、機械学習 (ML) を利用したインテリジェント検索サービスです。
この記事では、ユーザの権限によって検索ドキュメントのアクセスコントロールを行う方法をご紹介します。
[2023/07/12]：記事の内容をアップデートしました。

本記事で紹介するアクセスコントロールのサンプルコードは、simple-lex-kendra-jp という GitHub リポジトリで公開しておりますので、合わせてご確認ください。

Kendra のアクセスコントロールについて​

Kendra では、AccessControlList を利用してアクセスコントロールを行うことが可能です。AccessControlList は ACL と省略して表現されることもあります。

本記事では、 Amazon S3 (以降、S3) の Data source connection のアクセスコントロールについて解説します。

アクセスコントロールの種類​

Amazon S3 ドキュメントのアクセスコントロールは、「メタデータ使う方法」と「設定ファイルを使う方法」の 2 つがあります。

  • メタデータを使う方法
    • Amazon S3 ドキュメントにはメタデータを設定できますが、そのメタデータのひとつとして AccessControlList があります。
    • AccessControlList にアクセス条件を設定することで、ファイルごとにアクセスコントロールを行うことができます。
    • 本題とはそれますが、FAQ にもアクセスコントロール用のメタデータが用意されているため、そちらを利用することで S3 ドキュメントと同様のアクセスコントロールが可能です（参考）。
  • 設定ファイルを使う方法
    • アクセスコントロール設定用の JSON ファイルを定義することで、一元的にアクセスコントロールを設定することが可能です。
    • フォルダ単位または、ファイル単位で、アクセスコントロールを行うことができます。

メタデータによるアクセスコントロール​

メタデータファイルを使用して、S3 ドキュメントに対してメタデータを設定できます。
メタデータはアクセスコントロール以外の用途でも利用することが可能で、各属性を設定することにより属性を考慮したドキュメント検索（絞り込みやキーワード検索）を行うことが可能になります。
詳細については、こちらのドキュメント (Amazon S3 document metadata) をご確認ください。

アクセスコントロールの定義​

メタデータファイルに AccessControlList を設定することで、ファイルごとにアクセスコントロールを行うことができます。
AccessControlList は以下の通り設定することが可能です。

"AccessControlList": [
  {
      "Name": "group name | user name",
      "Type": "GROUP | USER",
      "Access": "ALLOW | DENY"
  }
],
  • Name: アクセスコントロール対象の「グループ名 or ユーザ名」を設定
  • Type: グループ単位で制御するか、ユーザ単位で制御するかを設定
  • Access: 当該ユーザを「許可」するか「拒否」するかを設定

アクセスコントロールの定義内容と挙動​

AccessControlList が未設定の場合は、すべてのユーザが「アクセス許可」となります。
AccessControlList に 1 つでも定義がある場合は、「アクセス許可」として定義されたユーザを除き、全員が「アクセス拒否」となります。
そのため、あるグループ以外のすべてのグループを「アクセス許可」という設定はできません。

以下のように、AdminGroup のみ ALLOW を設定すると AdminGroup に所属しているユーザのみ、ドキュメントを参照することが可能になります。

"AccessControlList": [
  {
      "Name": "AdminGroup",
      "Type": "GROUP",
      "Access": "ALLOW"
  }
],

以下のように、AdminGroup のみに DENY が設定されているため AdminGroup に所属していないユーザーはこのファイルを参照できそうに思えますが、実際はそうではありません。
ALLOW の設定がないため、このファイルには誰もアクセスすることができません。

"AccessControlList": [
  {
      "Name": "AdminGroup",
      "Type": "GROUP",
      "Access": "DENY"
  }
],

DENY のユースケースとしては、あるグループが内包しているサブグループのみアクセスを拒否したり、特定のユーザのみアクセスを拒否するといったものが考えられます。

"AccessControlList": [
  {
      "Name": "AnyGroup",
      "Type": "GROUP",
      "Access": "ALLOW"
  },
  // AnyGroup が内包している特定のサブグループのみ拒否
  {
    "Name": "AnySubGroup",
    "Type": "GROUP",
    "Access": "DENY"
  },
  // AnyGroup に所属している特定のユーザのみ拒否
  {
    "Name": "AnyUser",
    "Type": "USER",
    "Access": "DENY"
  }
],

設定ファイルによるアクセスコントロール​

アクセスコントロール用の設定ファイル (JSON 形式) を使って、一元的にアクセスコントロールを設定することが可能です。
S3 のデータソースに対して、1 つの設定ファイルを定義できます。
詳細については、こちらのドキュメント (Access control for Amazon S3 data sources) をご確認ください。

アクセスコントロールの定義​

S3 のプレフィックスを利用して、アクセスコントロール対象を指定します。
ディレクトリ単位または、オブジェクト単位で、アクセスコントロールの設定を行うことができます。

プレフィックスの指定は、s3:// から始まるフルパスで指定する必要があるので、ご注意ください。

aclEntries は、「メタデータによるアクセスコントロール」の AccessControlList と同じ定義となります。

[
  {
    "keyPrefix": "s3://prefix1",
    "aclEntries": [
      {
        "Name": "user name",
        "Type": "GROUP | USER",
        "Access": "ALLOW | DENY"
      }
    ]
  }
]

アクセスコントロールの定義内容と挙動​

「メタデータによるアクセスコントロール」と同じ挙動になります。

メタデータと設定ファイルの使い分けについて​

ここまで、メタデータと設定ファイルでアクセスコントロールを実現できることを紹介しました。
メタデータと設定ファイルでは設定方法が異なるだけで、実現できるアクセスコントロールの内容は同じです。
それでは、それぞれの使い分けについての一例をご紹介します。

  • メタデータのユースケース
    • メータデータファイルを自動で生成できる仕組みがある場合（大量のファイルに対して手動でファイル作成するのは現実的ではないため）
      • ファイル単位できめ細やかなアクセスコントロールを行いたい場合
      • アクセスコントロール以外の属性も設定して、検索に活かしたい場合
  • 設定ファイルのユースケース
    • フォルダ単位でアクセスコントロールを行いたい場合
      • 権限を考慮したフォルダ体系であれば、簡単にアクセスコントロールを実装できます
    • 一元的にアクセスコントロールのルールを管理したい場合

ユーザコンテキストについて​

AccessControlList で、ユーザごと・グループごとのアクセスコントロールの定義を行いましたが、Kendra の Query を実行する際に、ユーザの情報を設定しなければアクセスコントロールは実施されません。
ユーザの情報を設定していない場合は、AccessControlList の設定有無に関係なく、すべてのドキュメントが検索されるので、ご注意ください。

ユーザの情報を設定してアクセスコントロールを行う方法は、大きく 2 つあります。

  • ユーザコンテキスト
    • Query の UserContext に、以下の方法でユーザ情報を設定することが可能です。
      • JWT トークン
        • JWT トークンのペイロードを元にアクセスコントロールを行います。
        • 認証基盤に設定されている権限情報をそのまま利用して、アクセスコントロールを行いたい場合に便利です。
      • ユーザ ID とグループ名
        • ユーザ ID とグループ名を直接 Query に設定して、アクセスコントロールを行います。
        • JWT トークンを利用できない場合、認証基盤とは異なる情報でアクセスコントロールを行いたい場合に便利です。
      • DataSourceGroup
        • PutPrincipalMapping の機能を使って、Kendra 用に所属グループの設定を行うことが可能です。
          • 組織構造が複雑な場合や、アクセスコントロールの要件が複雑な場合に便利です。
          • 設定ファイルを用いた管理も可能です。
  • ユーザ属性フィルタリング
    • Query の AttributeFilter を設定することで、メタデータによるフィルタリングを行うことが可能です。
      • AccessControlList で「許可」しているユーザは _user_id、「許可」しているグループは _group_ids という属性でマッピングされています。
      • _user_id と _group_ids をフィルタリングの条件として利用することで、「許可」されたドキュメントのみ検索対象に含めることが可能になります。
      • 条件式によっては、AccessControlList が未設定のドキュメントが検索できないのでご注意ください。

参考：ユーザーコンテキストでのフィルタリング

認証・認可について​

前項で説明した通り、各種認証サービスの発行した JWT トークンを利用してアクセスコントロールを実現することが可能です。この機能は、Kendra 自体のアクセス制限を行うのではなく、ドキュメントの検索可否を制御するだけなのでご注意ください。

今回は Amazon Cognito (以降、Cognito) を利用した認証について解説を行います。
simple-lex-kendra-jp リポジトリの SimpleKendraAuth のスタックはここで紹介する Cognito を利用する方法で実装をしています。
Kendra のトークンを使ったアクセスコントロールについては、こちらのドキュメント (Controlling access to documents in an index) をご覧ください。

Kendra の JWT トークン設定の要否​

前項でも説明した通り、JWT トークンを利用しても Kendra 自体のアクセス制限を行うことはできません。すべてのファイルに AccessControlList を設定していれば、未認証ユーザが検索してもドキュメントは 1 件もヒットしませんが、Kendra への Query 発行はできます。

未認証ユーザの Kendra へのアクセス自体を制限したい場合は、API Gateway の Cognito オーソライザー等を利用して Query を発行する前に、アクセスをブロックする仕組みにする必要があります。simple-lex-kendra-jp の「Amazon Kendra Auth プロジェクト」に、こちらの実装サンプルがあるので合わせてご確認ください。

パターン別の対応方法​

構築するシステムの要件によって、さまざまな Kendra の設定パターンがありますので、よくあるパターン別に対応方法をご紹介します。
こちらは、IAM や VPC の設定が正しくできており、 Kendra へ直接 Query が発行できない状態になっていることを前提としています。
注意：Kendra のアクセスコントロールでは、 S3 バケット自体のアクセス制限はできません。S3 バケットの権限設定は適切に行ってください。

  • 認証ユーザのみ Kendra のアクセスを許可したい
    • 共通
      • API Gateway 等で未認証ユーザをブロックしてください。
    • JWT トークンの情報でドキュメントのアクセスコントロールを実施したい
      • Index に JWT トークンの設定し、Query 発行時に JWT トークンをセットしてください。
    • Kendra 独自のユーザ・グループの定義でドキュメントのアクセスコントロールを実施したい
      • Index に JWT トークンの設定は不要です。
      • Query 発行時に、ユーザ ID・グループ ID または、DataSourceGroup をセットしてください。
        • JWT トークンのペイロードの情報を元に、ユーザ ID・グループ ID または、DataSourceGroup をセットする方法も考えられます。
        • APIGateway + Lambda の構成だと、認証に利用した JWT トークンのペイロードを簡単に取得できます (event.requestContext.authorizer でペイロードが取得できます [参考])。
    • ドキュメントのアクセスコントロールを実施しない
      • Index に JWT トークンの設定は不要です。
      • ドキュメントに AccessControlList を設定しないでください。
      • Query 発行時にユーザコンテキストとユーザ属性フィルタリングの設定をしないでください。
  • 未認証ユーザも Kendra のアクセスを許可したい
    • ドキュメントのアクセスコントロールを実施したい
      • 未認証ユーザに公開したくないドキュメントすべてに AccessControlList を設定してください。
      • 非公開ドキュメントを参照できるユーザは認証を必須としてください。
        • 対応方法は「認証ユーザのみ Kendra のアクセスを許可したい」と同様です。
      • AccessControlList が設定されていないドキュメントは、未認証ユーザでもアクセス可能となります。
        • 未認証ユーザの場合は、Query 発行時にユーザコンテキストとユーザ属性フィルタリングの設定をしないでください。
    • ドキュメントのアクセスコントロールを実施しない
      • Index に JWT トークンの設定は不要です。
      • ドキュメントに AccessControlList を設定しないでください。
      • Query 発行時にユーザコンテキストとユーザ属性フィルタリングの設定をしないでください。

Kendra の JWT トークンの設定方法​

Index の設定​

JWT トークンを利用したアクセス制限を行う際は、Kendra の Index に対して設定を行う必要があります。

Index 設定画面の「Configure user access control (ユーザアクセスコントロールの設定)」の中に「Token configuration（トークン設定）」という項目があり、そこで設定を行うことができます。
Coginito を利用する場合は、「Token Type」で「OpenID」を選択してください。
JWT トークンの正当性を検証するための「Signing key URL」を設定する必要がありますが、Cognito を利用する場合は以下を設定してください。(参考)

https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json

ユーザ名とグループ名について​

Kendra では、ユーザ名とグループ名でアクセスコントロールを行うことができますが、JWT トークンのペイロードの中のどの項目でアクセスコントロールを行うかを設定できます。
たとえば、「Username」に email を設定すればメールアドレスでアクセスコントロールが可能ですし、それ以外のカスタム属性を指定することも可能です。
「Groups」に cognito:groups を設定することで、Cognito ユーザグループでアクセスコントロールを行うことが可能です。
参考：ユーザプール属性
参考：ユーザプルにグループを追加する
参考：ID トークンのペイロード

Kendra の Query 実行​

Query のオプションである --user-context に Token という項目があるので、そちらに Cognito から発行された JWT トークンを設定してください。JWT トークンの検証および、ドキュメントのアクセスコントロールが実施されます。
参考：AWS CLI Referense kendra qurey

Cognito には、アクセストークンと ID トークンの 2 種類の JWT トークンがあります。
Kendra の Query では、どちらのトークンも利用することが可能ですが、認証されたユーザの属性（アイデンティティ）を利用することが主な目的ですので、ID トークンを利用する方が適切です。

さいごに​

以上が、Kendra のアクセスコントロールを行う方法でした。
適切にアクセスコントロールを行うことで、より安全に、より便利に Kendra を利用できるようになります。
気になる方は、simple-lex-kendra-jp のリポジトリで気軽にお試し可能ですので、ぜひお試しください。
バグや要望がございましたら、気軽に Issue を起票していただければ幸いです！