ポリシー管理

ポリシー管理の基本

Speedle ポリシーとは？

ポリシー管理サービス (PMS) は、サービス、認可ポリシー、ロールポリシー、およびカスタム関数を管理します。ポリシーストアは、登録されたストレージバックエンドを使用してそれらのオブジェクトを永続化します。

サービスと認可ポリシー

サービスはそのポリシーのスコープを制限します。認可ポリシーは、プリンシパルに対してリソース上のアクションを実行する権限を付与または拒否し、オプションで条件を設定できます。グローバルロールポリシーを除き、あるサービスのポリシーが別のサービスで自動的に適用されることはありません。

grant group Administrators list,watch,get expr:^c1/default/core/pods/.*$

この正規表現は c1/default/core/pods/ 配下のリソースに一致します。c1/default/core/podssecret や c1 の前に余計なプレフィックスがあるパスには一致しません。expr: はシェルのワイルドカードではなく正規表現を使用します。任意の文字には .* を使用し、完全な識別子に一致させる必要がある場合は ^/$ を使用します。

ロールポリシー

grant user alan manager on res1
grant role manager update res1

最初のステートメントは特定のリソース上のロールを Alan に割り当て、2 番目のステートメントはそのロールに操作権限を付与します。ロールを割り当てるだけでは権限は生成されません。該当する明示的な拒否（deny）は許可（grant）をオーバーライドします。

プリンシパルと条件

プリンシパルには、ユーザー、グループ、エンティティ、またはロールを指定できます。エンティティはサービスなどの人間以外のアイデンティティを表します。統合コードはこれらのアイデンティティを信頼できるソースから取得する必要があります。

AND プリンシパルグループは、リスト内のすべてのプリンシパルが一致することを要求します。個別のグループ間は OR 条件になります。たとえば、以下の例では両方のロールが適用される必要があります:

grant (role designer, role dba) update db_design_doc

リソースは保護対象のオブジェクトを指定し、アクションはアプリケーションの操作を指定します。条件は、信頼できる属性、定数、演算子、およびサポートされている関数から評価されるブール式です。

文法については SPDL を、完全な決定例については RBAC/ABAC を参照してください。

サンプル実行前の準備

クイックスタートの手順に従い、リポジトリルート下の ./bin/spctl、./bin/speedle-pms、./bin/speedle-ads をビルドします。Go 1.26.10 または Go 1.27.3（または同じリリースブランチの新しいパッチバージョン）、Bash、curl、Python 3 が必要です。各ターミナルはリポジトリのルートから実行してください。このページ用に新しいポリシーファイルを使用します。両方のサービスを停止した後にのみファイルをリセットしてください。

空のポリシーファイルを初期化します:

printf '{}\n' > docs-policies.json

macOS: /usr/sbin/spctl は Apple の Gatekeeper ツールであり、引数なしの spctl コマンドを実行した際に選択される場合があります。Speedle の CLI は完全なパスで呼び出すか、それを含むディレクトリから ./spctl を使用してください。以下の例では ./bin/spctl を使用しています。シェルがどの実行可能ファイルを選択するかを確認するには、command -v spctl を実行します。ダウンロードしたリリースに speedle-spctl_<os>_<arch> アセットが含まれている場合、それは Apple のツールと衝突しない名前の同じ CLI です。

ターミナル 1 で PMS を起動し、実行したままにします:

./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --grpc-endpoint 127.0.0.1:0 --insecure=true

ターミナル 2 で ADS を起動し、実行したままにします:

./bin/speedle-ads --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6734 --grpc-endpoint 127.0.0.1:0 --insecure=true

残りのコマンドは 3 つ目のターミナルで実行します。PMS と ADS は同じファイルを共有し、変更は watch を通じて非同期に伝播します。新しいポリシーに依存する前に、更新が反映されていることを確認してください。--insecure=true はローカルのループバック用です。本番環境の接続についてはセキュリティを参照してください。明示的な PMS アドレスの指定により、~/.spctlconfig を変更する必要はありません。完了したら、両方のサーバーターミナルで Ctrl-C を押して終了します。

spctl によるサービスとポリシーの管理

新しいストアに対して以下のシーケンスを実行します。ID はライブクエリのレスポンスから取得され、古い実行からの固定値ではありません。削除はサービスを必要とするすべての操作の後に行われます。

./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create service test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get service test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get service --all
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create policy policy1 -c "grant user alan read book" --service-name test
policy_id=$(./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get policy --all --service-name test | python3 -c 'import json,sys; print(next(p["id"] for p in json.load(sys.stdin) if p.get("name")=="policy1"))')
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get policy "$policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create rolepolicy rolepolicy01 -c "grant user alan manager on res1" --service-name test
role_policy_id=$(./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get rolepolicy --all --service-name test | python3 -c 'import json,sys; print(next(p["id"] for p in json.load(sys.stdin) if p.get("name")=="rolepolicy01"))')
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get rolepolicy "$role_policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ delete policy "$policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ delete rolepolicy "$role_policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ delete service test

Speedle Cloud

Speedle Cloud のサインインはまもなく開始されます。API トークンが利用可能になると、spctl はセルフホストの PMS と同じコマンドを使用して Cloud サービスとポリシーを管理できます。管理エンドポイントを使用します:

https://cloud.speedle.io/policy-mgmt/v1

コマンドに必要なスコープを持つ API トークンを選択します。pms:read は get および discover の読み取りに対応し、pms:write は create、delete、および検出のリセットに対応します。ADS スコープのみを持つトークンではポリシーを管理できず、403 insufficient_scope で拒否されます。

エンドポイントをグローバルフラグとして渡し、SPCTL_TOKEN からトークンを読み取ります。対話型シェルでは、これによりシークレットがコマンド引数やシェル履歴に残らなくなります:

read -rsp 'API token: ' SPCTL_TOKEN; echo
export SPCTL_TOKEN
./bin/spctl --pms-endpoint https://cloud.speedle.io/policy-mgmt/v1 get service --all
unset SPCTL_TOKEN

互換性のために --token フラグも引き続き利用できますが、環境変数を使用するとコマンド引数によるトークンの漏洩を防ぐことができます。すべてのグローバルフラグには環境変数も用意されています。プレフィックス SPCTL_ を付け、フラグ名を大文字にしてハイフンをアンダースコアに置き換えます。たとえば、SPCTL_PMS_ENDPOINT は pms-endpoint を設定し、SPCTL_SKIPVERIFY は skipverify を設定します。

設定を保存するには ~/.speedle を使用します。形式はコマンドラインと同じフラグ名を持つ、1 行あたり 1 つの name=value ペアです:

pms-endpoint=https://cloud.speedle.io/policy-mgmt/v1
token=<api-token>

コマンド引数にトークンを含めずにこのファイルを作成または更新します:

read -rsp 'API token: ' SPCTL_TOKEN; echo
printf '%s\n' "$SPCTL_TOKEN" | ./bin/spctl config token --stdin
unset SPCTL_TOKEN

spctl config token --stdin はパーミッション 0600 で ~/.speedle を書き込みます。手動でファイルを編集する場合は、install -m 600 /dev/null ~/.speedle で作成するか、後で chmod 0600 ~/.speedle を実行してください。パーミッションがグループまたはその他のアクセスを許可しているファイルからトークンを読み取ると、spctl は標準エラー出力に警告を出力します。spctl config --list は設定されたトークンを ******** としてマスクします。

明示的なコマンドラインフラグは環境変数をオーバーライドし、環境変数は両方の設定ファイルをオーバーライドします。ファイル間では、~/.speedle が ~/.spctlconfig をオーバーライドします。spctl config でトークン以外のキーを設定すると、それが ~/.spctlconfig に書き込まれ、~/.speedle から対応するコピーが削除されます。

トークンは、証明書の検証が有効になっている HTTPS 経由でのみ Authorization: Bearer 認証情報として送信されます。トークンを使用した平文 HTTP は、127.0.0.1、::1、localhost などのループバックホストに対してのみ許可されます。spctl はリモートの HTTP エンドポイントおよび HTTPS から HTTP へのダウングレードリダイレクトに対しては認証情報を送信する前に拒否します。HTTPS エンドポイントの場合、--skipverify=true が指定されているとトークンの送信も拒否されます。代わりに --cacert を使用してプライベートまたは自己署名の認証局を信頼してください。トークンは通常のコマンド出力やエラーメッセージには含まれません。

Cloud のエラーはゼロ以外の終了ステータスを生成します。401 の後はトークンを確認し、403 insufficient_scope の後はそのスコープを確認してください。404 は存在しないリソースを示し、409 service_exists および 409 policy_exists は重複を示します。429 の場合は、返された Retry-After の値を尊重し、有界なバックオフを使用してください。日次またはポリシーのクォータエラーの場合は、リセットを待つか使用量を減らす必要があります。短い間隔でループ再試行しないでください。

その他のインターフェース

PMS REST API は JSON を使用し、文字列 ID を持つフラットなポリシーオブジェクトを返します。Go アプリケーションは PMS インターフェースを直接呼び出すことができます。gRPC クライアントは公開されている PMS proto を使用します。管理操作にはトランスポートおよび呼び出し元のアクセス制御を適用してください。