このガイドでは、OpenAI プロジェクトを作成し、再利用できるアクセス制御を設定します。プロジェクトロールで各アイデンティティに許可する操作を定義し、アクセスが必要なアイデンティティを組織のグループにまとめて、そのグループをプロジェクトに関連付けます。
一連の手順を終えると、次の操作を繰り返し実行できる構成が完成します。
- アプリケーション用の OpenAI プロジェクトを作成
- 必要最小限の権限を持つプロジェクトロールを定義
- アクセスが必要なアイデンティティ用に組織グループを作成
- ロールを通じてグループにプロジェクトへのアクセス権を付与
- 組織の既存ユーザーをグループに追加
事前準備
Terraform プロバイダーのセットアップを完了し、管理者 API キーを環境変数 OPENAI_ADMIN_KEY としてエクスポートします。組織の既存ユーザーの ID と、アプリケーションでの使用が承認された権限の識別子も用意してください。手順を試す際は、テスト用の組織を使用してください。
openai_project を削除すると、プロジェクトは完全に削除されず、アーカイブされます。アーカイブしたプロジェクトは復元できません。
プロジェクトの作成と管理範囲
アプリケーション用のプロジェクトを作成します。
resource "openai_project" "application" {
name = "example-application-development"
}プロジェクトは、アプリケーションの API 使用量、サービスアカウント、レート制限、支出アラート、プロジェクト設定を管理する単位です。Terraform が作成時に取得した ID は openai_project.application.project_id で参照できます。プロジェクトレベルのリソースがこの値を参照すると、Terraform はそれらのリソースより先にプロジェクトを作成します。
ここではプロジェクト名を直接指定しています。後述の構成例では、複数の環境で構成を再利用できるように、この名前を変数に置き換えます。
プロジェクト権限の定義
アプリケーションでの使用が承認された権限を持つプロジェクトロールを作成します。
resource "openai_project_role" "application" {
project_id = openai_project.application.project_id
role_name = "Application API access"
description = "Permissions approved for this application"
permissions = ["api.webhooks.read"]
}openai_project_role リソースは、アイデンティティがプロジェクト内で実行できる操作を定義します。この例では、Webhook の設定を読み取る権限を付与します。api.webhooks.read をアプリケーションでの使用が承認された権限の識別子に置き換え、最初は必要な権限だけを付与してください。
permissions を変更すると、ロールが更新されます。変更を適用する前に terraform plan を実行し、追加または削除される権限をすべて確認してください。
グループの作成または再利用
グループのライフサイクルを Terraform で管理する場合は、組織グループを作成します。
resource "openai_group" "application_access" {
name = "example-application-development-access"
}グループは組織レベルで作成されるため、複数のプロジェクトで再利用できます。グループ名の末尾に -access を付けると、単にチームを表すグループではなく、メンバーにアクセス権を付与するためのグループだと分かります。
既存のグループを別のシステムで管理している場合は、次のようにそのグループを読み取ります。
data "openai_group" "application_access" {
group_id = "group_123"
}データソースはグループの情報を読み取るだけなので、グループのライフサイクルは引き続き元のシステムが管理します。SCIM で管理されているグループも読み取れますが、メンバーの追加や削除は、そのグループを管理するアイデンティティ管理システムで行ってください。
グループへのプロジェクトアクセス権の付与
プロジェクト内のカスタムロールをグループに割り当てます。
resource "openai_project_group_role" "application_access" {
project_id = openai_project.application.project_id
group_id = openai_group.application_access.group_id
role_id = openai_project_role.application.role_id
}この例では、Terraform で管理するグループを使用しています。データソースを使って既存のグループを再利用する場合は、group_id に指定する式を data.openai_group.application_access.group_id に置き換えてください。
この割り当てでは、次の 3 つのオブジェクトを関連付けます。
project_idは、グループにアクセスを許可するプロジェクトを指定します。group_idは、アクセス権を付与するアイデンティティのグループを指定します。role_idは、グループに付与する権限を定めたロールを指定します。
グループのメンバーは、このプロジェクトでカスタムロールを継承します。ロールやグループを追加しただけではアクセス権は付与されません。グループにロールを割り当てることで、アクセス権が付与されます。
ユーザーなどのアイデンティティの追加
Terraform で管理する組織グループにアイデンティティを追加するには、openai_group_user を使用します。
resource "openai_group_user" "application_developer" {
group_id = openai_group.application_access.group_id
user_id = "user_123"
}user_id には、組織の既存ユーザーまたはサービスアカウントの ID を指定できます。サービスアカウントを追加する場合は、openai_project_service_account.application.id を user_id に指定します。グループを通じたサービスアカウントへのアクセス権の付与、認証、認証情報のライフサイクルに関する要件は、サービスアカウントを参照してください。
グループを通じたアクセス権の付与が適さない場合は、ロールを直接割り当てます。
resource "openai_project_user_role" "application_developer" {
project_id = openai_project.application.project_id
user_id = "user_123"
role_id = openai_project_role.application.role_id
}組織全体に適用される権限を付与するには、組織ロールを作成し、直接またはグループを通じて割り当てます。
variable "organization_role_permissions" {
type = list(string)
}
resource "openai_role" "platform_operator" {
role_name = "Platform operator"
description = "Organization permissions for the platform team"
permissions = var.organization_role_permissions
}
resource "openai_user_role" "platform_operator" {
user_id = "user_123"
role_id = openai_role.platform_operator.role_id
}organization_role_permissions には、承認された組織レベルの権限の識別子を指定します。各ロールの割り当てで権限の範囲を必要最小限に抑えるため、組織の権限とプロジェクトの権限は分けて管理してください。
現在のロール割り当ての確認
アクセス権を変更する前に、対象のアイデンティティに割り当てられている組織ロールとプロジェクトロールを確認します。
data "openai_user_roles" "current" {
user_id = "user_123"
}
data "openai_project_user_roles" "current" {
project_id = openai_project.application.project_id
user_id = "user_123"
}
output "organization_roles" {
value = data.openai_user_roles.current.roles
}
output "project_roles" {
value = data.openai_project_user_roles.current.roles
}データソースは現在の割り当てを読み取ります。読み取った割り当てが Terraform の管理対象になることはありません。
ロール割り当ての削除
Terraform がすでに割り当てを管理している場合、対応するリソースブロックを削除すると、次の実行計画にリモート側の割り当ての削除が含まれます。実行計画を確認し、必要なアクセス権が引き続き別の経路で付与されることを確かめてください。
Terraform の管理下にない既存の割り当てを削除する場合は、まず対応するリソースを宣言し、ドキュメントに記載された形式の複合 ID を使って割り当てをインポートします。最初の実行計画に変更がないことを確認してから、構成からリソースを削除し、割り当ての削除を適用します。
Terraform で削除できるのは、Terraform の状態に記録されている割り当てだけです。既存のデフォルトの割り当てを削除するには、まず対応する Terraform リソースにインポートします。次に、そのリソースを構成から削除し、生成された削除計画を適用します。このようにインポートしてから削除する手順が組織で許可されていない場合は、組織が承認した手順に従い、ダッシュボードまたは Administration API を使って割り当てを削除してください。
インポート時の ID の形式と、既存のリソースを安全に管理下に置く手順は、インポートと整合性の確認を参照してください。
構成例全体の実行
ここまでの例では、各リソースの関係が分かるように具体的な値を指定しました。以下の構成例では、繰り返し使う環境固有の値を変数に置き換えているため、リソース定義を変更せずに構成を再利用できます。
次の構成を main.tf として保存します。
terraform {
required_version = ">= 1.0"
required_providers {
openai = {
source = "openai/openai"
version = ">= 1.0.0"
}
}
}
provider "openai" {}
variable "project_name" {
type = string
}
variable "project_role_permissions" {
type = list(string)
}
variable "user_id" {
type = string
}
resource "openai_project" "application" {
name = var.project_name
}
resource "openai_project_role" "application" {
project_id = openai_project.application.project_id
role_name = "Application API access"
description = "Permissions approved for this application"
permissions = var.project_role_permissions
}
resource "openai_group" "application_access" {
name = "${var.project_name}-access"
}
resource "openai_project_group_role" "application_access" {
project_id = openai_project.application.project_id
group_id = openai_group.application_access.group_id
role_id = openai_project_role.application.role_id
}
resource "openai_group_user" "application_developer" {
group_id = openai_group.application_access.group_id
user_id = var.user_id
}
output "project_id" {
value = openai_project.application.project_id
}
output "group_id" {
value = openai_group.application_access.group_id
}
output "project_role_id" {
value = openai_project_role.application.role_id
}terraform.tfvars を作成し、一意のプロジェクト名、組織の既存ユーザーの ID、承認された権限を指定します。
project_name = "example-application-development"
user_id = "user_123"
project_role_permissions = [
"api.webhooks.read",
]Terraform を初期化し、実行計画を保存してから、内容を確認して適用します。
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan最初の実行計画では、追加予定のリソースが 5 件あることを確認してください。適用すると、ユーザーはグループを通じてカスタムプロジェクトロールを継承し、terraform output でプロジェクト、グループ、プロジェクトロールの各 ID を表示できます。terraform plan をもう一度実行し、この構成で追加の変更が発生しないことを確認してください。
利用者をさらに追加するには、ユーザーごとに一意の Terraform リソース名を付け、同じ方法でグループに追加します。人以外のアイデンティティを設定する場合は、サービスアカウントを参照してください。プロジェクトに利用制限や支出管理の仕組みを追加するには、モデル、ツール、データの制御とレート制限と支出を参照してください。