Iceberg クライアントを認証する

このセクションでは、Iceberg クライアントが Foundry の Iceberg カタログで認証する方法を説明します。 Foundry 内で Iceberg を使用する場合、これらの手順は不要です。

Foundry の Iceberg カタログは、Iceberg REST カタログの仕様 ↗ を実装しています。このため、REST カタログをサポートする Iceberg クライアントは、 Foundry の Iceberg カタログとやり取りする際に、仕様で定義された認証メカニズムを使用できます。

Iceberg クライアントを設定する際には、次の認証オプションを利用できます。

方法	説明
OAuth2 クライアント資格情報	クライアントIDとクライアントシークレットを使用して、サービスユーザーとして認証します。設定後、Iceberg クライアントが必要なトークン交換を実行します。
Bearer	API トークン（一般に Bearer トークンと呼ばれます）を使用して、ユーザーとして認証します。

クライアントにクラウドストレージ（S3 や Azure Data Lake Storage (ADLS) など）の資格情報を設定しないでください。カタログを介してクライアントにアクセス権を付与する方法の詳細については、以下のアクセス委任と資格情報の払い出しセクションを参照してください。

API トークンを使用する

API トークンは Bearer トークンとも呼ばれ、認証して利用をはじめるための最も手早い方法です。ユーザー生成トークンのドキュメントに従って、ご自身のユーザー用の API トークンを生成できます。

Bearer トークンを使用して Iceberg クライアントを設定する場合、次のプロパティが必要です。

キー	例	必須かどうか	説明
`uri`	`https://<hostname>/iceberg`	はい	Foundry Iceberg カタログを識別する URI
`token`	`eyJwb...`	はい	Authorization ヘッダーに使用する Bearer トークンの値

以下の例では、Python Iceberg クライアント（PyIceberg）を使用し、 ~/.pyiceberg.yaml ↗ にカタログを設定します。カタログのプロパティはこちら ↗に記載されており、 REST カタログをサポートするほかの Iceberg クライアント実装に合わせて調整できます。

catalog:
  foundry:
    uri: https://your.foundry/iceberg
    token: eyJwb...

生成されたこれらの Bearer トークンは有効期間が長く、ご自身のユーザーに紐付いています。慎重に扱ってください。本番環境では OAuth2 を使用し、トークンベースの認証は開発用途に限定することを推奨します。

OAuth2 を使用する

Iceberg クライアントで OAuth2 を使用すると、API の Bearer トークンを直接指定する場合よりもセキュリティを強化できます。こちらに記載されているとおり、クライアント資格情報グラントを使用するサードパーティ OAuth2 アプリケーションを作成する必要があります。

Iceberg クライアントには、生成されたクライアント資格情報と、クライアント資格情報をアプリケーショントークンに交換する認可サーバーの URL を指定します。Iceberg クライアントがこの交換と、その後のトークンの更新を処理します。

OAuth2 用に Iceberg クライアントを設定する際には、次のプロパティを使用します。

キー	例	必須かどうか	説明
`uri`	`https://<hostname>/iceberg`	はい	Foundry Iceberg カタログを識別する URI
`oauth2-server-uri`	`https://<hostname>/iceberg/v1/oauth/tokens`	はい	認可サーバーを識別する URI
`credential`	`client_id:client_secret`	はい	カタログの初期化時に OAuth2 資格情報フローで使用する資格情報
`scope`	`api:iceberg-read api:iceberg-write`	いいえ	権限を制限するためのスペース区切りのスコープ

これらのプロパティを使用して、以下のように OAuth2 用の PyIceberg カタログクライアントを設定できます。

Copied!1
2
3
4
5
6
catalog:
  default:
    uri: https://your.foundry/iceberg
    oauth2-server-uri: https://your.foundry/iceberg/v1/oauth/tokens  # OAuth2 サーバー URL
    credential: 17f...:037...  # client_id:client_secret
    scope: api:iceberg-read api:iceberg-write  # 任意、スペース区切りのスコープ

scope の設定は任意です。権限のデフォルトは、サードパーティアプリケーション用に作成されたサービスユーザーの権限です。api:iceberg-write を含めずに api:iceberg-read を宣言することで、スコープを読み取りのみを許可するように制限できます。

Foundry は Iceberg 向けの認可サーバーを使用するため、 OAuth2 クライアントで一般的に使用されるエンドポイントとは異なるエンドポイントを使用します。

アクセス委任と資格情報の払い出し

ストレージへのアクセスは、Iceberg の仕様 ↗に記載されているアクセス委任メカニズムを使用して、Iceberg カタログによって委任されます。Foundry のカタログは、次のサポート表に従って、資格情報の払い出し（推奨）またはリモート署名を提供します。

ストレージの場所	資格情報の払い出し	資格情報の更新	リモート署名
ABFS	はい、SAS トークン経由	いいえ	いいえ
S3	はい、STS トークン経由	はい	はい

資格情報の払い出し

資格情報の払い出しでは、Foundry の Iceberg カタログが、スコープを限定した短期間有効な資格情報を払い出すことで、認証済みクライアントにデータへのアクセス権を付与します。この方式は最小権限の原則を徹底し、ストレージの資格情報が露出する機会を最小限に抑えることでセキュリティを強化します。

Iceberg クライアントが Foundry の Iceberg カタログとやり取りする際、ユーザーやアプリケーションがストレージの資格情報を直接指定することはありません。代わりに、Foundry Iceberg カタログが、特定のデータと権限にスコープを厳密に限定した一時的な資格情報を発行します。

資格情報の払い出しプロセスは次のとおりです。

アクセスリクエスト： Iceberg クライアントは、Foundry Iceberg REST カタログ API を使用して、1個以上のテーブルへのアクセスをリクエストします。たとえば、テーブルのメタデータを読み込む際にこのリクエストを行います。
認証： Foundry の REST カタログはクライアントを認証し、リクエストされたテーブルと操作に対する権限を検証します。
資格情報の払い出し： クライアントが認可されると、Foundry のカタログは、有効期間が短くスコープを狭く限定したストレージの資格情報を「払い出し」（つまり、発行）ます。払い出された各資格情報は、特定のファイルに対してのみ、限られた期間だけ有効です。
データアクセス： クライアントはこれらの一時的な資格情報を使用して、基盤となるストレージ（S3 や ABFS など）に直接アクセスし、データを読み書きします。資格情報の有効期限が切れると、アクセス権は自動的に取り消されます。

認証のトラブルシューティング

Foundry Iceberg REST カタログへの接続に問題が発生した場合は、以下の手順で問題を切り分けます。

Bearer トークンで接続を確認する

まず、ローカルの Jupyter ノートブックから API トークンを使用してカタログに接続できることを確認します。これにより、OAuth2 の設定とは独立して、基本的なネットワーク接続とカタログへのアクセスを確認できます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from pyiceberg.catalog import load_rest
from getpass import getpass

token = getpass("Foundry user token:")

catalog = load_rest(
    "foundry",
    {
        "uri": "https://<your_foundry_url>/iceberg",
        "token": token,
    },
)

table = catalog.load_table("<table_rid>")
print(table.snapshots())
del token

<your_foundry_url> をお使いの Foundry ホスト名に、<table_rid> を Iceberg テーブルのリソース識別子に置き換えます。この手順に成功した場合、カタログに到達でき、ご自身のユーザーに適切な権限があることを示しています。

OAuth2 資格情報を検証する

Bearer トークンでの接続を確認した後、ローカルの Jupyter ノートブックから OAuth2 クライアント資格情報をテストします。これにより、サードパーティアプリケーション、そのスコープ、およびサービスユーザーの権限が正しく設定されていることを検証できます。この手順に成功しない場合は、サードパーティアプリケーションとそのスコープが正しく設定されていること、および関連する Compass フォルダーと Iceberg テーブルへのアクセス権がサービスアカウントに付与されていることを確認してください。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from pyiceberg.catalog import load_rest
from getpass import getpass

foundry_url = "https://<your_foundry_url>"
client_id = "<your_client_id>"

client_secret = getpass("OAuth2 client secret:")

catalog = load_rest(
    name="foundry",
    conf={
        "uri": f"{foundry_url}/iceberg",
        "oauth2-server-uri": f"{foundry_url}/iceberg/v1/oauth/tokens",
        "credential": f"{client_id}:{client_secret}",
        "scope": "api:iceberg-read api:iceberg-write",
    },
)

# 名前空間を一覧表示して、カタログへのアクセスを確認します
print(catalog.list_namespaces())

# 特定のテーブルを読み込んで、テーブルレベルの権限を確認します。
# テーブルを読み取れない場合は、サードパーティアプリケーションに関連付けられたサービスアカウントに、そのテーブルへのアクセス権限があることを確認してください。
table = catalog.load_table("<table_rid>")
print(table.snapshots())
del client_secret

<your_foundry_url>、<your_client_id>、<table_rid> を、お使いの環境に固有の値に置き換えます。

←

PREVIOUSガバナンス / リソース使用量

NEXTネットワークアクセスの設定

→