diff --git a/content/docs/cloud/ai-credits-and-limits.ja.mdx b/content/docs/cloud/ai-credits-and-limits.ja.mdx new file mode 100644 index 0000000..e26104b --- /dev/null +++ b/content/docs/cloud/ai-credits-and-limits.ja.mdx @@ -0,0 +1,66 @@ +--- +title: AI クレジットと上限 +seoTitle: "ObjectOS Cloud の AI 利用枠：週ごとの上限、ペース、クレジットパック" +description: ObjectOS Cloud で製品内 AI がどう計量されるか。構築と質問のための 1 つの利用枠、ローリングする週ごとの上限と 5 時間のペース、クレジットパック、各プランが使うモデル、そして拒否されたときのメッセージ。 +editions: [cloud, enterprise] +translation: + source_sha: 67429e9e53ae8850c44792b0659fead909aa7791fb06d24d6153d6be29182837 + guide_rev: 1 + mode: auto +--- + +ObjectOS Cloud では私たちが AI モデルを実行するので、製品内 AI（[AI Builder](/docs/build/ai-builder) と、データについての質問に答えるアシスタント）は **AI 利用枠**を消費します。セルフマネージドの ObjectOS Enterprise のデプロイメントでは代わりに自分のモデルを用意し、このページの上限はどれも適用されません。[ObjectOS Enterprise の場合](#on-objectos-enterprise)を参照してください。 + +## すべての AI の作業に 1 つの利用枠 [#one-allowance-for-all-ai-work] + +アプリの構築、データについての質問、アシスタントを通じたアクションの実行は、すべて**同じ利用枠**を消費します。作業の種類ごとの別々の予算はありません。各リクエストは、モデルがそのために行う作業に比例して利用枠を消費し、プランで選択肢がある場合、より高性能なモデルはより多くを消費します。 + +利用枠は**環境**ごとに数えられます。クラウドコンソールの **Home** に、今週の利用枠をどれだけ使ったかが表示されます。 + +## 2 つのローリングウィンドウ [#two-rolling-windows] + +すべてのプランに同じ 2 つの上限があり、どちらも**ローリング**です。使用量は一定の時間だけ数えられた後に外れるので、余裕はカレンダーの日付ではなく、連続的に戻ってきます。[cloud#2059](https://github.com/objectstack-ai/cloud/issues/2059) で決定されました。 + +| ウィンドウ | 内容 | Free | Team 以上 | +|---|---|---|---| +| **7 日** | 予算：1 週間に収まる AI の作業量 | 環境ごとに週 1 回分の利用枠。厳格な上限です | AI シートごとのより大きな利用枠に、組織の AI シートの数を掛けたもの。[クレジットパック](#buy-ai-credits)で引き上げられます | +| **5 時間** | ペース：短い集中した利用に収まる量。暴走したセッション 1 つが 1 週間分を使い切れないようにします | 適用されますが、Free の週ごとの利用枠より上にあります | AI シートごとで、シートの数を掛けます。クレジットパックでは引き上げられません | + +ObjectOS Cloud が[パブリックプレビュー](/docs/editions/public-preview)の間は、利用枠の正確な大きさは公表されません。Free の利用枠は、最初の体験全体（アプリを構築し、何度か変更し、それでもまだ質問できる）に合わせた大きさです。 + +## 上限に達したとき [#when-a-limit-is-reached] + +リクエストは HTTP `429` で拒否され、チャットにはどの上限に達したか、いつ空くかを示すメッセージが表示されます。 + +| 状況 | コード | メッセージ | +|---|---|---| +| Free、週ごとの利用枠を使い切った | `AI_DESIGN_QUOTA_EXHAUSTED` | *You've used this week's free AI quota. It resets on DATE — upgrade to keep going.* | +| 有料、週ごとの利用枠を使い切った | `AI_ALLOWANCE_EXHAUSTED` | *Your AI allowance for this week is used up. It resets on DATE, or buy a credit pack to continue now.* | +| どのプランでも、5 時間のペースに達した | Free では `AI_DESIGN_QUOTA_EXHAUSTED`、有料プランでは `AI_ALLOWANCE_EXHAUSTED` | *You've hit the five-hour AI usage limit. It resets within five hours — then you're good to go.* | + +日付は、まだ数えられている最も古い使用量がウィンドウから外れる時点です。エラーの `details.resetsAt` は、同じ時点を ISO タイムスタンプで持っています。環境のほかのものには影響しません。アプリ、データ、連携は動き続けます。 + +## AI クレジットを購入する [#buy-ai-credits] + +有料プランでは、オーナーまたは管理者が、一回限りの **AI クレジットパック**で週ごとの利用枠を補充できます。環境の **Settings → Plan and billing** を開き、**AI credits** → **Buy AI Credits** を選びます。新しいタブで安全なチェックアウトが開きます。 + +- クレジットパックが引き上げるのは **7 日**の予算だけです。5 時間のペースはレート制限であり、購入で引き上げることはできません。 +- Free はクレジットパックを受け付けません。Free の週ごとの上限を超える方法は [Team へのアップグレード](/docs/cloud/plans-and-seats#upgrade)です。 +- 組織でクレジットパックがまだ販売されていない場合、ボタンはチェックアウトを開く代わりにそのことを伝えます。 + +## どのモデルが答えるか [#which-model-answers] + +すべてのプランは**同じデフォルトのモデル**で答えます。有料プランが Free と違うのは利用枠の大きさであって、より強力なモデルではありません。有料の環境でモデルの選択肢が提供されている場合は、AI チャットで選べます。より高性能なモデルは利用枠をより早く減らします。 + +## 自分のクライアントを通じた AI はここでは計量されない [#ai-through-your-own-client-is-not-metered-here] + +[MCP](/docs/configure/mcp) で接続するエージェント（Claude Code、Cursor など）は、**あなたの**モデルとあなた自身のトークンで動きます。AI 利用枠は消費しません。その制限となるのは、環境の MCP リクエストの上限です（[ストレージと上限](/docs/cloud/storage-and-limits#mcp-limits)）。 + +## ObjectOS Enterprise の場合 [#on-objectos-enterprise] + +セルフマネージドの Enterprise のデプロイメントは、[AI サービス](/docs/configure/ai)で設定する独自のモデルとキーを用意し、モデルのプロバイダーに直接支払います。プラットフォームの AI クレジットも、利用枠も、計量もありません。AI シートごとの料金はライセンスであって、使用量のパッケージではありません。デプロイメントがどれだけの AI の作業をするかは、自分のプロバイダーのアカウントによってのみ制限されます。 + +## 次へ [#next] + +- [プランと AI シート](/docs/cloud/plans-and-seats)：各プランに含まれるもの。 +- [AI Builder](/docs/build/ai-builder)：AI が構築できるもの。 diff --git a/content/docs/cloud/apps.ja.mdx b/content/docs/cloud/apps.ja.mdx new file mode 100644 index 0000000..8ff87dc --- /dev/null +++ b/content/docs/cloud/apps.ja.mdx @@ -0,0 +1,113 @@ +--- +title: アプリ +seoTitle: "ObjectOS Cloud のアプリ：インストール、更新、公開、CLI からのデプロイ" +description: ObjectOS Cloud の環境にアプリをインストールし、更新を確認し、環境のアプリを組織向けのパッケージとして公開し、ローカルでビルドしたアプリを os CLI からデプロイします。 +editions: [cloud] +translation: + source_sha: 0adc0c246817f68e5c28824736e064a5591eadd4b69aa953dd25f91a3c85a4a0 + guide_rev: 1 + mode: auto +--- + +アプリが ObjectOS Cloud の環境に届く方法は 3 つあります。マーケットプレイスまたは組織のレジストリから**インストール**する、環境の中で（[AI Builder](/docs/build/ai-builder) を使うか手作業で）**構築**する、または自分のマシンから `os` CLI で**公開**する、のいずれかです。どの方法でも、インストールされるのは[パッケージ](/docs/build/packages)、つまりオブジェクト、ビュー、フローなどをまとめたバージョン付きのバンドルです。 + +## アプリをインストールする [#install-an-app] + +クラウドコンソールで環境の **Settings → Apps** を開き、**Install an app**（**Install Application**）を選びます。アプリを選んでから、次を設定します。 + +- **Include sample data**：パッケージのデモレコードで環境を埋め、すぐに試せるようにします。クリーンな本番環境ではチェックを外したままにします。 +- **Accept additional permissions**：初回のインストールではチェックを外したままにします。これは、以前に付与された権限より多くの権限を求める更新のためのものです（[更新を確認する](#check-for-updates)を参照）。 + +アプリは再起動なしで、環境への次のリクエストから表示されます。インストール後のメッセージには、どのように反映されたか（インストール、再インストール、更新、ロールバックのいずれかと、そのバージョン）と、知っておくべきこと（アプリが使う機能のうちプランに含まれないものなど）が表示されます。 + +環境の中からインストールすることもできます。環境の **Marketplace** を開き、アプリを見つけて **Install** を選びます。どちらの方法でも、同じパッケージが同じ環境にインストールされます。[マーケットプレイス](/docs/build/marketplace)を参照してください。 + +インストールは組織のオーナーと管理者が行います。 + +## 更新を確認する [#check-for-updates] + +**Settings → Apps → Check for app updates** は、インストール済みの各アプリを公開されている最新バージョンと比較し、更新があるか、すべてのアプリが最新か、まだ何もインストールされていないかを表示します。 + +アプリを更新するには、もう一度インストールします。すでにインストールされているアプリをインストールすると、その場で公開済みの最新バージョンに移行します。 + +新しいバージョンが、アプリに以前付与されていなかった権限を求める場合、更新は `PERMISSION_RECONSENT_REQUIRED` で拒否され、メッセージに追加される各権限が一覧表示されます。内容を確認してから、**Accept additional permissions** にチェックを入れてもう一度インストールし、権限を付与します。 + +## 環境をパッケージとして公開する [#publish-an-environment-as-a-package] + +**Settings → Apps → Publish as a package**（**Publish to Registry**）は、この環境で構築したアプリを、組織のレジストリにあるパッケージの新しいバージョンとして公開します。そこから組織の他のどの環境にもインストールできます。開発環境で構築したアプリは、この方法で本番環境に届きます。 + +| フィールド | 意味 | +|---|---| +| **App Name** | レジストリに表示される名前。デフォルトは環境の名前です。 | +| **Version** | `1.2.0` のようなセマンティックバージョン。空欄のままにすると、最新バージョンの次のパッチとして公開されます。 | +| **Visibility** | **Private**：自分の組織だけがインストールできます。**Organization**：組織全体で共有されます。 | +| **Description** | アプリ全体として何をするか。 | +| **Release notes** | このバージョンでの変更点。バージョンとともに表示されます。 | +| **Package ID**（詳細設定） | 逆ドメイン形式の識別子。空欄の場合は環境の名前から導出されます。 | + +公開マーケットプレイスへの掲載は、審査を伴う別の手順であり、ここでは提供されません。サイドバーの **Advanced → Packages** に、組織が公開したものがすべて一覧表示されます。 + +## CLI からデプロイする [#deploy-from-the-cli] + +アプリをコードとして（自分のマシン上の ObjectStack プロジェクトとして）開発している場合、`os` CLI でそれを組織に公開し、環境にインストールできます。流れは **ログイン → ビルド → 公開 → インストール** です。 + +必要なものは、ObjectStack プロジェクト（[Path B — `os init`](/docs/start/community#path-b--os-init-developer) を参照）、`os` CLI、そして環境を持つ ObjectOS Cloud アカウントです。 + +### 1. ログイン [#1-log-in] + +```bash +os cloud login +``` + +これはブラウザのサインインを開き、クラウドトークンを `~/.objectstack/cloud.json` に保存します。サインインリンクを開く代わりに表示するには `--no-browser` を使います。CI ではログインを省略し、`--token` または `OS_CLOUD_API_KEY` 変数で `os package publish` に API キーを渡します。 + +クラウドログインは、ランタイムにサインインする `os login` とは別のものです。公開には常にクラウドログインが使われます。 + +### 2. ビルド [#2-build] + +```bash +os build +``` + +これはプロジェクトをひとつのアーティファクト `dist/objectstack.json` にコンパイルします。オブジェクト、ビュー、アプリ、ダッシュボード、フロー、サンプルデータが含まれます。後でアップロードされるのはこのアーティファクトだけで、ソースファイル、`node_modules`、ローカルの認証情報がアップロードされることはありません。 + +### 3. 公開 [#3-publish] + +```bash +os package publish +``` + +プロジェクトのルートで実行します。パッケージを組織に登録し（初回のみ。`com.acme.crm` のような逆ドメイン形式のパッケージ id をキーとします）、アーティファクトを新しい不変のバージョンとして公開します。同じバージョンを 2 回公開することはできません。`manifest.version` を上げるか、`--version` を渡します。 + +| フラグ | 目的 | +|---|---| +| `--manifest-id ` | 逆ドメイン形式のパッケージ id。デフォルト：アーティファクトから導出 | +| `--version ` | 公開するバージョン。デフォルト：`manifest.version` | +| `--visibility ` | 誰が表示・インストールできるか。ObjectOS Cloud では新しいパッケージのデフォルトは `org` です。既存のパッケージの公開範囲を維持するにはフラグを省略します | +| `--install` | 新しいバージョンをすぐに環境にインストールします | +| `--env ` | `--install` の対象環境。デフォルト：`os environments switch` で選択した環境 | +| `--seed-sample-data` | インストール時にアーティファクトのサンプルデータを含めます | +| `--note ""` | リリースノート | +| `--submit` | `marketplace` パッケージの新しいバージョンを審査に提出します | + +### 4. インストール [#4-install] + +利用者は環境からインストールします。環境の **Marketplace** を開き、パッケージを見つけて **Install** を選ぶか、[前述](#install-an-app)のクラウドコンソールの **Install an app** を使います。 + +既知の環境にデプロイするパイプラインは、ひとつのコマンドで公開とインストールを行えます。 + +```bash +os package publish --env --install --seed-sample-data +``` + +これは全か無かです。インストールが拒否された場合（その環境にインストールできない、環境が存在しない、またはそのバージョンがその環境で承認されていない）、何も公開されません。コマンドは拒否内容を表示してゼロ以外で終了するため、パイプラインは失敗します。原因を修正し、同じバージョンをもう一度公開してください。 + +### マーケットプレイスへの掲載 [#marketplace-listings] + +`--visibility marketplace` はパッケージを公開カタログの対象にしますが、新しいバージョンはそれぞれ**下書き**として届きます。審査に送るには `--submit` を渡します。プライベートと組織のパッケージは審査が不要で、組織はすぐにインストールできます。 + +## 次へ [#next] + +- [パッケージ](/docs/build/packages)：パッケージに含まれるものと、バージョンの仕組み。 +- [マーケットプレイス](/docs/build/marketplace)：環境の中からの閲覧とインストール。 +- [CLI リファレンス](/docs/reference/cli)：すべての `os` コマンド。 diff --git a/content/docs/cloud/cloud-connection.ja.mdx b/content/docs/cloud/cloud-connection.ja.mdx new file mode 100644 index 0000000..0956e77 --- /dev/null +++ b/content/docs/cloud/cloud-connection.ja.mdx @@ -0,0 +1,63 @@ +--- +title: クラウド接続 +seoTitle: "セルフホストの ObjectOS サーバーを ObjectOS Cloud の組織に接続する" +description: セルフホストの ObjectOS Community または Enterprise サーバーをワンタイムコードで ObjectOS Cloud の組織にリンクし、その Marketplace に組織のパッケージを表示します。取り消しや切断で何が失われるかも説明します。 +editions: [community, cloud, enterprise] +translation: + source_sha: f32aef27f0099041cbdc82e55e1d2ab1c2b73289b0b3f87ca5cc8e9b0af6ca26 + guide_rev: 1 + mode: auto +--- + +セルフホストの ObjectOS サーバー（Community または Enterprise）は、ObjectOS Cloud の組織に接続できます。接続すると、サーバーの **Marketplace** に公開パッケージと並んで組織自身のパッケージが表示され、サーバー自身の認証情報でそれらをインストールします。接続はサーバー側で開始し、クラウド側でワンタイムコードを使って承認します。サーバーに何かを入力する必要はありません。 + +接続には 2 つの側面があり、このページは両方を扱います。 + +- **サーバー側**（Community、Enterprise）：接続の開始と切断。前提条件、サーバーが保存するもの、パネルに表示されうるすべてのメッセージを含むサーバー側の完全なリファレンスは、[objectstack.ai の Cloud Connection](https://objectstack.ai/docs/deployment/cloud-connection) にあります。 +- **クラウドの組織側**（Cloud）：リクエストの承認と、**Advanced → Connected Runtimes** での接続済みサーバーの管理。 + +## 接続で得られるもの [#what-connecting-gives-you] + +- **サーバーの Marketplace に表示される組織のパッケージ**："Your organization" の下に、[公開](/docs/cloud/apps#publish-an-environment-as-a-package)したプライベートおよび組織のパッケージが表示され、サーバー自身の認証情報で閲覧・インストールされます。 +- **組織内の登録**：Connected Runtimes に一覧表示され、サーバーの名前とバージョン、承認したアカウント、接続日時と最終使用日時が示されます。 + +接続が**不要な**こと：公開マーケットプレイスの閲覧と公開パッケージのインストールは、接続していないサーバーでも動作します。また、コンパイル済みのアーティファクトからのインストールはクラウドを一切呼び出しません。 + +## 接続する [#connect] + +1. **サーバー側で**、**Manage Platform Settings** 権限を持つユーザーとしてサインインし、**Setup → Integrations → Cloud Connection** を開きます。**Connect** を選びます。 +2. サーバーはクラウドにワンタイムコードを要求し、新しいウィンドウで承認ページを開きます。コードはサーバーのページにも表示されます。 +3. **クラウド側で**、サーバーが参加すべき組織の ObjectOS Cloud アカウントにサインインし、コードが一致することを確認して承認します。 +4. サーバーは自動的に完了します。ページが **Connected to ObjectStack Cloud** に変わり、ランタイム、組織、承認したアカウント、日時が表示されます。 + +時間内に誰も承認しないとコードは期限切れになります。**Connect** からやり直してください。 + +**承認できる人。** ロールにかかわらず、組織のどのメンバーでも承認できます。サーバーは承認者の**アクティブな**組織に参加します。複数の組織に所属している場合は、承認する前にクラウドコンソールで正しい組織に切り替えてください。 + +サーバーにはクラウドへのアウトバウンド HTTPS が必要で、作業ディレクトリは永続ストレージでなければなりません。接続はそこにファイルとして保持されます。ObjectOS Cloud 自体がホストするサーバーはプラットフォームによって接続されるため、Cloud Connection ページはありません。 + +## クラウドで接続済みサーバーを管理する [#manage-connected-servers-in-the-cloud] + +クラウドコンソールの **Advanced → Connected Runtimes** には、組織に接続されたすべてのサーバーが、名前、ランタイムのバージョン、承認したアカウント、ステータス、接続日時、最終使用日時とともに一覧表示されます。各行には次の操作があります。 + +| 操作 | 内容 | +|---|---| +| **Rename** | ここと承認ページに表示される名前を変更します。 | +| **Revoke** | サーバーを即座に切り離します。認証情報が機能しなくなるため、再び承認されるまで、そのサーバー上での組織のパッケージの閲覧、インストール、更新は失敗します。サーバーにすでにインストールされているアプリは動作し続けます。 | +| **Remove** | もう接続されていないサーバー向け：その行を削除します。サーバーはいつでも新しいデバイスとして再接続できます。 | + +## サーバーから切断する [#disconnect-from-the-server] + +サーバーの **Cloud Connection** ページで **Disconnect** を選びます。サーバーはクラウドに接続の取り消しを依頼し、結果にかかわらず認証情報を削除します。その Marketplace には組織のパッケージが表示されなくなります。 + +切断しても、次の 2 つは保持されます。 + +- **インストール済みのすべて。** サーバーにすでにインストールされているパッケージは、インストールされたまま動作し続けます。 +- **サーバーのランタイム id。** 再接続すると、新しい行を追加するのではなく、Connected Runtimes の同じ行に紐づきます。 + +切断時にクラウドに到達できなかった場合でも、サーバーは認証情報を破棄しますが、クラウドには通知されていません。Connected Runtimes を確認し、そこで該当の行を **Revoke** してください。 + +## 次へ [#next] + +- [マーケットプレイス](/docs/build/marketplace)：任意のサーバーへのアプリのインストール。 +- [アプリ](/docs/cloud/apps)：組織向けのパッケージの公開。 diff --git a/content/docs/cloud/domains.ja.mdx b/content/docs/cloud/domains.ja.mdx new file mode 100644 index 0000000..a45990d --- /dev/null +++ b/content/docs/cloud/domains.ja.mdx @@ -0,0 +1,68 @@ +--- +title: ドメイン +seoTitle: "ObjectOS Cloud のドメイン：プラットフォームのサブドメインと独自のドメイン" +description: すべての ObjectOS Cloud のプランにはブランド付きのプラットフォームのサブドメインが含まれます。Team 以上では、TXT レコードで所有を証明し、証明書が発行される独自のドメインを本番環境に追加できます。 +editions: [cloud] +translation: + source_sha: e09fb1bee012ece2c40eb7165542858668830bbe291102a95f4b038ffa7c7e77 + guide_rev: 1 + mode: auto +--- + +ObjectOS Cloud の環境には、2 種類のアドレスでアクセスできます。 + +| | **プラットフォームのサブドメイン** | **独自のドメイン** | +|---|---|---| +| 見た目 | プラットフォームのドメイン上の `acme` | `app.acme.com` | +| プラン | Free を含むすべてのプラン | Team 以上 | +| 環境 | 本番。開発環境は固定のアドレスのまま | 本番のみ | +| 数 | いくつでも追加できます | Team では本番環境ごとに 1 つ。契約によりそれ以上 | +| 証明書 | プラットフォーム自身のものでカバーされます | 所有が証明されると発行されます | + +このページのルールは、[cloud#1087](https://github.com/objectstack-ai/cloud/issues/1087)（プラットフォームのサブドメインはすべてのプランで無料）と [cloud#2136](https://github.com/objectstack-ai/cloud/issues/2136)（独自のドメイン）で決定されました。 + +## プラットフォームのサブドメイン [#platform-subdomains] + +本番環境のアドレスは、プラットフォームのドメイン上の組織の[スラッグ](/docs/cloud/organization#the-organization-slug)です。これはすべてのプランで無料で、自分で選ぶほかのブランド付きのラベルも同じく無料です。 + +変更するには、環境の **Settings → Name and domain** を開き、**Change Hostname** を選びます。ラベルだけを入力します。プラットフォームのドメインは自動で付きます。ラベルは 4〜63 文字の小文字、数字、ダッシュで、両端にダッシュは使えず、2 つ続けることもできません。いくつかの予約語は拒否されます。組織のスラッグで始まる必要はありません。 + +最初のものを置き換えるのではなく 2 つ目のプラットフォームのサブドメインを追加するには、同じセクションの **Add Domain** を使います。環境の **Overview** に表示されるアドレスが、人に伝えるべきアドレスです。 + +## 独自のドメイン [#your-own-domain] + +**Team** 以上では、本番環境は、`app.acme.com` のような、所有するドメインのサブドメインでも応答できます。 + +1. **追加します。** **Settings → Name and domain** で **Add Domain**（または **Change Hostname**）を選び、完全なホスト名を入力します。サブドメイン（少なくとも 3 つのラベル）でなければなりません。`acme.com` のようなルートドメインは拒否されます。`www.acme.com` などのサブドメインを使ってください。 +2. **所有を証明します。** ドメインは **Pending Verification** として作成され、コンソールに公開すべき TXT レコードが表示されます。名前は `_objectos-challenge.` で、値はこのドメインに固有のものです。ホスト名が向けるべき CNAME のターゲットも表示されます。 +3. **確認します。** TXT レコードを公開したら、ドメインで **Verify DNS** を選びます。ObjectOS Cloud はレコードを確認し、それから証明書を要求します。ドメインは **Verified** と **Provisioning Certificate** を経て **Active** になります。途中のステップで止まった場合は、もう一度 **Verify DNS** を選んで先に進めます。 +4. **プライマリにします**（省略可能）。**Set as Primary** は、サインインのリダイレクト、メールのリンク、共有リンクがどのアドレスを使うかを決めます。プラットフォームのサブドメインも並んで機能し続けます。 + +セッションは 1 つのアドレスに属します。プラットフォームのサブドメインと独自のドメインを切り替えると、もう一度サインインすることになります。 + +### うまくいかないとき [#when-something-goes-wrong] + +| 表示されるもの | 理由と対処 | +|---|---| +| `403 CUSTOM_DOMAIN_PLAN_LOCKED` | 組織が Free です。Team にアップグレードしてください。 | +| `403 DEV_ENV_DOMAIN_LOCKED` | これは開発環境です。ドメインは本番環境に追加してください。 | +| www またはサブドメインを求める `400 INVALID_FORMAT` | ルートドメインを入力しました。`www.acme.com` のようなサブドメインを使ってください。 | +| `403 CONTACT_SALES_PLAN` | 環境はすでに 1 つのドメインを持っています。複数持つには Enterprise の契約が必要です。 | +| `409 DUPLICATE_VALUE` | 別の環境がすでにそのホスト名を提供しています。 | +| 確認の応答が、TXT レコードがまだ見えないと言う | DNS が伝播していないか、レコードの名前または値が異なります。応答には期待されるレコードが繰り返し示されます。 | +| **Failed** | 証明書を発行できませんでした。CNAME を確認し、もう一度 **Verify DNS** を選んでください。まず所有を証明し直します。 | + +### ダウングレードとアップグレード [#downgrade-and-upgrade] + +ダウングレードは独自のドメインを**一時停止**します。決して解放はしません。ドメインは **Suspended** になって提供を止め、証明書は取り下げられますが、レコードは残ります。それがプライマリだった場合、リンクは影響を受けないプラットフォームのサブドメインにフォールバックします。後でアップグレードすると、CNAME がまだ私たちを向いていれば、ドメインは自動的に再プロビジョニングされます。「N 日後に解放」というものはありません。 + +一時停止されたドメインが、そのホスト名の所有を証明できるほかの誰かを妨げることはありません。別の環境がそれを証明すれば、一時停止されていた主張は放棄されます。 + +### ドメインを削除する [#removing-a-domain] + +ドメインの **Delete** は提供を止め、ホスト名を解放します。環境を完全に削除すると、そのすべてのドメインもあわせて削除されます。 + +## 次へ [#next] + +- [環境](/docs/cloud/environments)：本番と開発。 +- [プランと AI シート](/docs/cloud/plans-and-seats)：Team が追加するもの。 diff --git a/content/docs/cloud/environments.ja.mdx b/content/docs/cloud/environments.ja.mdx new file mode 100644 index 0000000..c58768a --- /dev/null +++ b/content/docs/cloud/environments.ja.mdx @@ -0,0 +1,87 @@ +--- +title: 環境 +seoTitle: "ObjectOS Cloud の環境：本番、開発、ライフサイクル" +description: ObjectOS Cloud の本番環境と開発環境。プランごとに誰がどれを得るか、環境の作成、そして一時停止、アーカイブ、復元、削除がそれぞれデータに何をするか。 +editions: [cloud] +translation: + source_sha: 697f7e55052fc9b88c5feb928caad9c8197a04cc0f52c2e514abe2b95c4995b6 + guide_rev: 1 + mode: auto +--- + +**環境**は、独自のデータベース、ファイル、アプリ、アドレスを持つ、ObjectOS の稼働中のコピー 1 つです。組織のアプリは環境の中にあり、チームはそれを使うために環境にサインインします。ObjectOS Cloud には 2 種類があります。 + +| | **本番** | **開発** | +|---|---|---| +| 数 | どのプランでも、組織ごとにちょうど 1 つ | 有料プランのみ：2 つに加えて AI シートごとに 1 つ。組織全体で共有されます | +| アドレス | プラットフォームのドメイン上の組織のスラッグ。[独自のドメイン](/docs/cloud/domains)を付けられます | プラットフォームが割り当てる `dev-` という形式の固定のアドレス。ブランド付きのサブドメインや独自のドメインには決してなりません | +| アイドル | 非アクティブによるアーカイブは決してされません | 使われないまま 7 日経つと自動的にアーカイブされます | +| 用途 | チームが使うアプリ | 変更が本番に届く前に構築して試す | + +組織が作成する**最初の**環境が本番環境で、それ以降のすべてが開発環境です。 + +## 誰がどれを得るか [#who-gets-which] + +**Free：本番環境が 1 つだけで、ほかには何もありません。** 本番で直接構築します。2 つ目の環境の作成は `403 DEV_ENV_PLAN_LOCKED` で拒否され、コンソールは代わりにアップグレードを提示します。 + +**Team 以上：本番に加えて開発環境のプール。** プールは開発環境 2 つに加えて、組織が支払う AI シートごとに 1 つで、組織全体で数えられます。開発環境はシートの料金に含まれており、請求書に行が追加されることは決してありません。有料プランでの通常の流れは、開発環境で構築し、[パッケージとして公開](/docs/cloud/apps#publish-an-environment-as-a-package)して、そのパッケージを本番にインストールすることです。 + +そもそも開発環境が存在するかどうかはプランが決めます（[cloud#1252](https://github.com/objectstack-ai/cloud/issues/1252) で決定）。1 つの本番環境はどのプランでも同じです。 + +## 環境を作成する [#create-an-environment] + +**Environments** で **Create Environment** を選び、名前を付けます。アドレスはプラットフォームが割り当てます。本番環境のアドレスは後から **Change Hostname**（[ドメイン](/docs/cloud/domains)）で変更できます。開発環境は、与えられた固定のアドレスのままです。新しい環境は **Provisioning** で始まり、データベースの準備ができると **Active** になります。 + +環境に入るには **Open** を選びます。新しいタブで環境自身のコンソールが、あなたとしてサインインした状態で開きます。 + +## 環境のページ [#the-environment-page] + +各環境には、2 つのタブを持つページがあります。 + +- **Overview**：アドレス、ステータス、プランと種類、インストールされているアプリ、アクセスの設定。折りたたまれた **Features that need a higher plan** の行は、現在のプランに含まれていないものを数え、開くとその一覧を表示します。 +- **Settings**：すべてのアクションが 5 つのセクションにあります。**Apps**、**Plan and billing**、**Name and domain**、**Access and sign-in**（[AI エージェントのアクセス](/docs/configure/mcp#on-objectos-cloud)を含む）、**Lifecycle and danger zone** です。 + +環境を変更するアクションは、組織のオーナーと管理者に提示されます。 + +## ライフサイクル [#lifecycle] + +| 状態 | 意味 | データ | +|---|---|---| +| **Active** | リクエストを処理しています | — | +| **Suspended** | 再開するまで、ランタイムへのすべてのトラフィックがブロックされます | 保持されます | +| **Archived** | アクティブな表示から外され、訪問されても起動しなくなります | 保持期間が終わるまで保持され、その後削除されます | +| **Failed** | プロビジョニングが完了しませんでした | 何も作成されていません | + +**一時停止と再開。** 一時停止すると、人からも連携からも、環境へのすべてのリクエストがブロックされます。何も削除されず、**Resume** で元どおりに戻ります。 + +**アーカイブと復元。** アーカイブすると、環境は使われなくなり、その保持期間のカウントが始まります。**Restore** はその期間内に環境を戻し、次の訪問で再び起動します。 + +**削除。** 削除は 2 段階の操作なので、1 回のクリックでデータが失われることは決してありません。 + +1. まだアーカイブされていない環境は、完全な削除を求めた場合でも**アーカイブ**されます。 +2. **アーカイブ済み**の環境を、**Delete permanently if already archived** にチェックを入れて削除すると、そのデータベースとすべてのファイルが一度に破棄され、復旧はできません。 + +本番環境を削除するときは、さらに **Force-delete the production environment** にチェックを入れるよう求められます。プロビジョニングに失敗した環境はデータを持たないので、即座に削除されます。 + +### アーカイブされた環境がどれだけ保持されるか [#how-long-an-archived-environment-is-kept] + +| アーカイブのされ方 | 保持期間 | +|---|---| +| あなたによる（**Archive**、または **Delete** の第 1 段階） | 少なくとも 30 日。Business では 90 日、Enterprise では 1 年 | +| 自動的に、7 日間アイドルだった開発環境 | プランの期間：Team では 30 日、Business では 90 日、Enterprise では 1 年 | + +アーカイブされた環境が削除される少し前に環境のオーナーに警告が届くので、復元する時間があります。期間を過ぎると、データベース、ファイル、ドメインとともに完全に削除されます。 + +### アイドル状態の開発環境 [#idle-development-environments] + +**7 日間**誰も訪問も構築もしていない開発環境は、自動的にアーカイブされます。環境を使うことと、その中で開発すること（公開、インストール、パッケージの編集）の両方がアクティビティとして数えられます。本番環境がこの方法でアーカイブされることは決してありません。 + +### Free へのダウングレード後 [#after-a-downgrade-to-free] + +ダウングレードはさかのぼって適用されません。組織がすでに動かしている開発環境は**動き続けます**。ダウングレードによって一時停止やアーカイブされることはありません。Free が拒否するのは*追加*です。開発環境の作成や、アーカイブされた開発環境の復元は、組織が再びアップグレードするまで `403 DEV_ENV_PLAN_LOCKED` で応答します。アーカイブされた開発環境は、その後 Free の期間である 7 日間保持されます（[cloud#2253](https://github.com/objectstack-ai/cloud/issues/2253) と [cloud#2204](https://github.com/objectstack-ai/cloud/issues/2204) で決定）。 + +## 次へ [#next] + +- [プランと AI シート](/docs/cloud/plans-and-seats)：有料プランが追加するもの。 +- [ストレージと上限](/docs/cloud/storage-and-limits)：環境ごとのストレージの割り当て。 +- [アプリ](/docs/cloud/apps)：環境でアプリをインストール、更新、公開する。 diff --git a/content/docs/cloud/meta.ja.json b/content/docs/cloud/meta.ja.json new file mode 100644 index 0000000..1f134b7 --- /dev/null +++ b/content/docs/cloud/meta.ja.json @@ -0,0 +1,5 @@ +{ + "title": "Cloud 組織", + "defaultOpen": false, + "pages": ["organization", "environments", "plans-and-seats", "ai-credits-and-limits", "storage-and-limits", "domains", "apps", "cloud-connection"] +} diff --git a/content/docs/cloud/organization.ja.mdx b/content/docs/cloud/organization.ja.mdx new file mode 100644 index 0000000..72ae0d3 --- /dev/null +++ b/content/docs/cloud/organization.ja.mdx @@ -0,0 +1,73 @@ +--- +title: 組織とメンバー +seoTitle: "ObjectOS Cloud の組織：スラッグ、メンバー、招待、ロール" +description: ObjectOS Cloud の組織。そのスラッグ、クラウドコンソール、メンバーの招待、5 つのメンバーシップのロール、そしてサインインが環境ではなくクラウドにある理由。 +editions: [cloud] +translation: + source_sha: 45e832e16685da44f31911d619138580836770640112ee1300fc5cc35796ac0d + guide_rev: 1 + mode: auto +--- + +ObjectOS Cloud では、所有するものはすべて**組織**に属します。環境、アプリとパッケージ、プラン、メンバーです。組織はサインアップ時に作成し（[ObjectOS Cloud で始める](/docs/start/cloud)）、[cloud.objectos.ai](https://cloud.objectos.ai) の**クラウドコンソール**で管理します。 + +## クラウドコンソール [#the-cloud-console] + +コンソールのサイドバーが、このセクションの地図です。 + +| サイドバーの項目 | 中身 | ページ | +|---|---|---| +| **Home** | 組織の概要：本番環境、アプリ、メンバー、今週の AI 利用枠 | — | +| **Environments** | すべての環境と、その設定とライフサイクル | [環境](/docs/cloud/environments) | +| **Members** | 組織の人と、保留中の招待 | このページ | +| **Billing** | プランの比較とアップグレード | [プランと AI シート](/docs/cloud/plans-and-seats) | +| **Advanced → Connected Runtimes** | この組織にリンクされたセルフホストのサーバー | [クラウド接続](/docs/cloud/cloud-connection) | +| **Advanced → Packages** | 組織が公開したパッケージ | [アプリ](/docs/cloud/apps) | + +各環境にも、その環境自身のアドレスに独自のコンソールがあります。チームがアプリを使うのはそこで、クラウドコンソールはそれらを取り巻く組織を管理する場所です。 + +## 組織のスラッグ [#the-organization-slug] + +**スラッグ**は組織の短い識別子で、サインアップ時に選びます。本番環境のアドレスでもあり、スラッグの後にプラットフォームのドメインが続きます。 + +- 4〜30 文字：小文字、数字、ダッシュ。 +- 先頭と末尾にダッシュは使えず、ダッシュを 2 つ続けることもできません。 +- 予約語の短いリストは拒否されます（`admin`、`api`、`www`、`docs`、`default` など、プラットフォーム自身が使うもの）。 + +オーナーまたは管理者は、組織のレコードの **Change Slug** でスラッグを変更できます。変更は 90 日に 1 回までです。組織のすべてのプラットフォームのサブドメインが新しいスラッグに書き換えられ、古いスラッグは 90 日間保持されるので、その間にほかの誰かがそれを取ることはできません。独自のドメイン（[ドメイン](/docs/cloud/domains)）はスラッグの変更の影響を受けません。 + +## メンバーと招待 [#members-and-invitations] + +サイドバーで **Members** を開きます。このページには 2 つのタブがあります。ロール付きのメンバーと、まだ保留中の招待です。 + +誰かを追加するには、**Invite members** を選び、メールアドレスを入力してロールを選びます。相手は招待を受け取り、それを承諾すると組織のメンバーになります。 + +**組織の招待が、その環境に入る唯一の方法です。** 環境には独自の招待もセルフサインアップもありません。ここで招待した全員が組織の環境に入ることができ、環境の中で何ができるかは、その環境の[権限](/docs/configure/permissions)が決めます。 + +リストから、組織を管理する人は**メンバーのロールを変更**、**メンバーを削除**、保留中の招待を**再送**または**取り消し**できます。 + +## ロール [#roles] + +メンバーシップのロールは、人が組織の中で何に届くかを決めます。これは権限セットではありません。環境の中でレコードに対して何ができるかは、その環境の[権限セットとポジション](/docs/configure/permissions)から来ます。 + +| ロール | 用途 | 招待できる人 | +|---|---|---| +| **Owner** | 組織、そのプラン、その環境の完全な管理 | オーナー | +| **Admin** | 組織を管理します：メンバー、環境、請求 | オーナーまたは管理者 | +| **Delegated Admin** | 管理者でなくても招待のエンドポイントに届きます。人をどこに配置できるかは、別に付与される管理のスコープから来ます | オーナーまたは管理者 | +| **Member** | 組織の環境とアプリを使います | 招待できる人なら誰でも | +| **External** | ポータルのユーザー（仕入先や顧客）で、自分の行と明示的に共有されたものだけを見ます。事業単位のツリーには決して含まれません | 招待できる人なら誰でも | + +このセクションで「組織を管理する人」と言うのは、オーナーと管理者のことです。彼らには、プラン、アップグレード、何かを変更する環境のアクションが表示されます。一般のメンバーは環境を見て開けますが、完了できないアクションは提示されません。 + +## サインインのある場所 [#where-sign-in-lives] + +ObjectOS Cloud では、すべてのアカウントがクラウドのアカウントです。ObjectOS Cloud が人をサインインさせ、環境がその人を受け入れます。環境が各人について保持するのは**認可だけ**、つまりポジション、権限セット、共有です。すべてのホスト型の環境は、どのプランでもデフォルトでこの単一のサインインを使うので、人は ObjectOS Cloud のアカウントで一度サインインし、環境の間を移動できます。 + +**環境を自社のインフラストラクチャに移す場合。** アカウントは環境ではなく ObjectOS Cloud にあるので、環境とともに移動はしません。セルフマネージドのデプロイメントでは、そこで人に新しい認証情報を発行するか、自社のアイデンティティプロバイダーにバインドしてそれを通じてサインインさせます。[認証](/docs/configure/authentication)を参照してください。 + +## 次へ [#next] + +- [環境](/docs/cloud/environments)：本番と開発、そしてそのライフサイクル。 +- [プランと AI シート](/docs/cloud/plans-and-seats)：Free、Team、Enterprise のそれぞれに含まれるもの。 +- [権限](/docs/configure/permissions)：環境の中でメンバーができること。 diff --git a/content/docs/cloud/plans-and-seats.ja.mdx b/content/docs/cloud/plans-and-seats.ja.mdx new file mode 100644 index 0000000..36b415c --- /dev/null +++ b/content/docs/cloud/plans-and-seats.ja.mdx @@ -0,0 +1,75 @@ +--- +title: プランと AI シート +seoTitle: "ObjectOS Cloud のプラン：Free、Team、Enterprise と AI シート" +description: ObjectOS Cloud のプラン（Free、Team、Enterprise）、唯一の有料シートである AI シート、アップグレードの方法、そしてプランに含まれないものをコンソールのどこで確認できるか。 +editions: [cloud] +translation: + source_sha: c5f15cf821325b61b91091b0b7377b4a9750dc285a87202f969b73eae1eb8b97 + guide_rev: 1 + mode: auto +--- + +ObjectOS Cloud には 3 つのプランがあります。プランは**組織**に属し、そのすべての環境に適用されます。料金がかかるのは **AI シート**だけで、組織のそれ以外の全員は無料でアプリを使い、閲覧できます。 + +| | **Free** | **Team** | **Enterprise** | +|---|---|---|---| +| 料金 | $0 | AI シートあたり月額 $24、または年払いで AI シートあたり月額 $20 | 契約による | +| 本番環境 | 1 | 1 | 1 | +| [開発環境](/docs/cloud/environments) | — | 2 つに加えて AI シートごとに 1 つ | ✓ | +| アーカイブされた開発環境の保持 | — | 30 日 | 1 年 | +| [AI 利用枠](/docs/cloud/ai-credits-and-limits) | 週ごとの利用枠 | AI シートとともに増える、より大きな利用枠と [AI クレジットパック](/docs/cloud/ai-credits-and-limits#buy-ai-credits) | AI シートとともに増える利用枠と AI クレジットパック | +| [環境ごとのストレージ](/docs/cloud/storage-and-limits) | 1 GB | 20 GB | 上限なし | +| [AI エージェントのアクセス（MCP）](/docs/configure/mcp#on-objectos-cloud) | 1 分あたり 20 リクエスト、1 日 1,000 | 1 分あたり 120 リクエスト、1 日の上限なし | 1 分あたり 120 リクエスト、1 日の上限なし | +| ブランド付きのプラットフォームのサブドメイン | ✓ | ✓ | ✓ | +| [独自のドメイン](/docs/cloud/domains) | — | 本番環境ごとに 1 つ | ✓ | +| 承認ワークフロー | — | — | ✓ | +| サインイン | ObjectOS Cloud のサインイン | ObjectOS Cloud のサインイン | ObjectOS Cloud のサインイン。契約により、自社のアイデンティティプロバイダーによるシングルサインオン | +| サポート | コミュニティ | 標準 | 優先 | + +ObjectOS Cloud は[パブリックプレビュー](/docs/editions/public-preview)中です。料金はプレビュー期間の料金であり、変更があれば事前に告知されます。 + +## AI シート [#the-ai-seat] + +**AI シート**は、AI で構築し、データについて AI に質問できるメンバーです。[AI Builder](/docs/build/ai-builder) とアプリ内のアシスタントのことです。これが唯一の有料シートです。AI シートを持たないメンバー、閲覧者、そして [MCP](/docs/configure/mcp) 経由で自分の AI クライアントを使って構築する開発者には料金がかかりません。 + +購入する AI シートの数は組織の設定で、チェックアウト時に選び、後から変更できます。それによって 3 つのものの大きさが決まります。 + +- 組織の **AI 利用枠**。シートごとです（[AI クレジットと上限](/docs/cloud/ai-credits-and-limits)）。 +- **開発環境のプール**。2 つに加えてシートごとに 1 つです（[環境](/docs/cloud/environments)）。 +- 人ごとのシートの割り当てが有効になっている環境で、AI シートを**割り当てられる**人の数。 + +## アップグレード [#upgrade] + +アップグレードは、オーナーまたは管理者が環境のページ（そのヘッダー、または **Settings → Plan and billing**）から行います。 + +1. **Upgrade Plan** を選びます。ダイアログで、プラン（Team）、請求の周期（月払い、または AI シートあたり月額 $20 の年払い）、AI シートの数を尋ねられます。 +2. 新しいタブで安全なチェックアウトが開きます。請求先は 1 つの環境ではなく、組織です。 +3. 支払いが完了すると組織のプランが変わり、そのすべての環境が再デプロイなしに新しいプランを取り込みます。 + +組織でまだオンライン決済が利用できない間は、ボタンは **Upgrade to Team** と表示され、代わりに **Billing** を開きます。そこで Team の **Contact sales** ボタンを押すと、私たちとともにアップグレードを始められます。 + +Enterprise は営業担当者が支援します。**Billing** の Enterprise の列にある **Contact sales** を使ってください。 + +## プランに含まれないものを確認する [#see-what-your-plan-leaves-out] + +コンソールの 2 か所で、営業ページを挟まずに確認できます。 + +- **Billing** は 3 つのプランを並べて比較し、現在のプランに **Current plan** の印を付けます。すべてのメンバーが読めますが、そのボタンが表示されるのはオーナーと管理者だけです。 +- 環境の **Overview** タブには、折りたたまれた **Features that need a higher plan: N · View** の行があります。開くと、現在のプランに含まれない各機能が、それを含むプランとともに一覧されます。ロックされた機能がコンソールのほかの場所に現れる場合は、**Team plan and above** のような、そのプランの名前を示す短い印が付き、**Billing** へ移動できます。 + +## ダウングレード [#downgrading] + +下位のプランに下げても、データが削除されることは決してありません。 + +- 開発環境は動き続けます。Free が拒否するのは、その作成と復元だけです（[環境](/docs/cloud/environments#after-a-downgrade-to-free)）。 +- Free のストレージの割り当てを超えた環境は、すべてのバイトを保持し、読み取りとエクスポートができる状態のまま、アップロードとインポートを受け付けなくなります（[ストレージと上限](/docs/cloud/storage-and-limits)）。 +- 独自のドメインは解放されずに一時停止され、後でアップグレードすると自動的に戻ります（[ドメイン](/docs/cloud/domains#downgrade-and-upgrade)）。 + +## Business [#business] + +**Business** は、ホスト型サービスにおける ObjectOS Enterprise の契約オプションで、**Billing** からではなく[営業](/docs/editions/license)が販売します。ObjectOS Cloud では、承認ワークフローと、アーカイブされた開発環境の 90 日間の保持期間を追加します。料金と契約がカバーする内容は[ライセンスと料金](/docs/editions/license)にあります。 + +## 次へ [#next] + +- [エディションの比較](/docs/editions/compare)：Community と Enterprise と並べたプラン。 +- [AI クレジットと上限](/docs/cloud/ai-credits-and-limits)：AI 利用枠の仕組み。 diff --git a/content/docs/cloud/storage-and-limits.ja.mdx b/content/docs/cloud/storage-and-limits.ja.mdx new file mode 100644 index 0000000..26f20f4 --- /dev/null +++ b/content/docs/cloud/storage-and-limits.ja.mdx @@ -0,0 +1,61 @@ +--- +title: ストレージと上限 +seoTitle: "ObjectOS Cloud の上限：環境ごとのストレージと MCP リクエストの上限" +description: ObjectOS Cloud の環境の使用上限。1 GB と 20 GB のストレージの割り当て、いっぱいになった環境が止めるものと決して止めないもの、80% の警告、そしてプランごとの MCP リクエストとドラフトの上限。 +editions: [cloud] +translation: + source_sha: d814bf7b8ecb5b58b6975c5ccb4927b9788c2e96517b9d44980d7da7b2c72a30 + guide_rev: 1 + mode: auto +--- + +各 ObjectOS Cloud の環境には、独自の上限がいくつかあります。このページでは、それぞれの数値が属するプランとともに一覧します。AI 利用枠には専用のページがあります：[AI クレジットと上限](/docs/cloud/ai-credits-and-limits)。 + +| 上限 | Free | Team 以上 | Enterprise | +|---|---|---|---| +| [環境ごとのストレージ](#storage) | 1 GB | 20 GB | 上限なし | +| [1 分あたりの MCP リクエスト](#mcp-limits) | 20 | 120 | 120 | +| [UTC の 1 日あたりの MCP リクエスト](#mcp-limits) | 1,000 | 1 日の上限なし | 1 日の上限なし | +| [UTC の 1 日あたりの MCP 経由の作成の書き込み](#drafts-and-authoring-writes) | 200 | 2,000 | 2,000 | +| [環境ごとの未公開のドラフト](#drafts-and-authoring-writes) | 500 | 500 | 500 | + +## ストレージ [#storage] + +すべての環境には**ストレージの割り当て**があります。Free では **1 GB**、Team では **20 GB** で、**環境ごと**に数えられます。開発環境も本番と同じ割り当てを得ます。Enterprise 契約にはストレージの数値はありません（プロダクトオーナーの決定、2026-09-08：数値は確定です）。 + +**数えられるもの。** 環境のデータベースと添付ファイルです。使用量はおよそ 1 時間ごとに測り直されるので、大きなアップロードやインポートは 1 時間以内に測定値に現れます。この遅れは意図的なものです。 + +**いっぱいになった環境が止めるもの。** 割り当ての 100% から、2 つのことが拒否されます。 + +- **添付ファイルのアップロード**（ファイルと画像のフィールド） +- レコードの**一括インポート** + +拒否は、コード `STORAGE_LIMIT_REACHED` とアップグレードの方法とともに `403` で返されます。 + +**決して止めないもの。** 単一のレコードの作成、編集、削除。何かを読むこと。エクスポート。そして空き容量を作るための添付ファイルの削除です。環境が割り当てに近づいているせいで、その環境で構築されたアプリを使う人がフォームを保存できなくなることは決してありません。 + +**警告。** **80%** でコンソールにバナーが表示されます。これは警告であって上限ではありません。アップロードとインポートは 100% まで引き続き通ります。 + +**ダウングレードは何も削除しません。** ダウングレードの後で Free の割り当てを超えてしまった環境は、すべてのバイトを保持し、読み取りとエクスポートができる状態のまま、再びアップグレードされるか空き容量ができるまで、アップロードとインポートを受け付けなくなるだけです。 + +## MCP の上限 [#mcp-limits] + +すべての環境の [MCP エンドポイント](/docs/configure/mcp#on-objectos-cloud)が受け付けるリクエストの数は決まっており、その環境に接続しているすべてのエージェントで共有されます。[cloud#3203](https://github.com/objectstack-ai/cloud/issues/3203) で決定されました。 + +- **Free：** 1 分あたり 20 リクエスト、UTC の 1 日あたり 1,000。 +- **Team 以上：** 1 分あたり 120 リクエスト、1 日の上限なし。 + +リクエストは 1 つの MCP メッセージです。ツールの呼び出し、一覧の取得、接続のハンドシェイクの各ステップです。バッチはその中の各メッセージを数え、その日の残りの数に収まらないバッチは丸ごと拒否されます。1 分あたりの割り当ては連続的に補充されるので、1 分あたりの数値までの短い集中した利用は問題ありません。 + +上限を超えると、エンドポイントは `Retry-After` ヘッダー付きの `429 Too Many Requests` で応答し、本文の `error.code` は `RATE_LIMIT_EXCEEDED` です。メッセージには、どの上限に達したか、いつリセットされるかが示され、Free では Team へのアップグレードも案内されます。拒否されたリクエストは実行されておらず、どちらの上限も消費しません。待った後の次のリクエストは通常どおり処理されます。人が操作するエージェントは有料プランの上限を十分に下回ります。上限に達するエージェントは、たいていは同じツールを繰り返し呼び出すループです。 + +## ドラフトと作成の書き込み [#drafts-and-authoring-writes] + +アプリの設計への変更は、公開されるまで**ドラフト**としてステージングされます。環境が保持できる**未公開のドラフトは最大 500 件**で、どのプランでも、どの方法で作られたものでも同じです。それを超えると、さらにドラフトをステージングする変更は、ドラフトが公開または破棄されるまで拒否されます。これは時間でリセットされることはありません。 + +MCP 経由で届く作成の書き込み（メタデータを作成または変更するビルドツール）も、UTC の 1 日ごとに数えられます。Free では **200**、Team 以上では **2,000** です。読み取りとチェックは数えられません。どちらの拒否も、リクエストの上限と同じ `RATE_LIMIT_EXCEEDED` の応答を使い、その数、上限、いつリセットされるかを示します。[cloud#3303](https://github.com/objectstack-ai/cloud/issues/3303) で決定されました。 + +## 次へ [#next] + +- [プランと AI シート](/docs/cloud/plans-and-seats)：各プランに含まれるもの。 +- [AI ツールを接続する（MCP）](/docs/configure/mcp#on-objectos-cloud)：環境の MCP エンドポイントを有効にする。 diff --git a/content/docs/configure/permissions/field-level-security.ja.mdx b/content/docs/configure/permissions/field-level-security.ja.mdx new file mode 100644 index 0000000..e3aa636 --- /dev/null +++ b/content/docs/configure/permissions/field-level-security.ja.mdx @@ -0,0 +1,157 @@ +--- +title: フィールドレベルのセキュリティ +seoTitle: "フィールドレベルのセキュリティ：付与と API での強制" +description: 個々のフィールドを隠す、マスクする、ロックする。付与の意味、サーバー側での強制、そしてフォーム、ビュー、API で FLS がどう動作するか。 +editions: [community, cloud, enterprise] +translation: + source_sha: 58871db7d6fcecf258805b25fbf6750df2977a64c4fc479c32004dad5e19422b + guide_rev: 1 + mode: auto +--- + +フィールドレベルのセキュリティ（FLS）は、オブジェクトの権限と[レコードアクセス](/docs/configure/permissions/record-access)がユーザーにそもそもレコードへの到達を許した*後で*、個々のフィールドの表示と編集の可否を制御します。「サポートは取引先を見られるが、その `annual_revenue` は見られない」や「営業担当者は外部 ID を読めるが、決して変更できない」のための層です。 + +FLS のルールは[権限セット](/docs/configure/permissions/permission-sets)にあります。このページは、そこにある[フィールドのセキュリティの付録](/docs/configure/permissions/permission-sets#field-security-appendix)よりも、付与の意味と強制について掘り下げます。 + +## フィールドの権限の付与 [#field-permission-grants] + +フィールドの権限は `.` をキーとし、`readable` / `editable` を使います。 + +```ts +// Keys of a permission set; its other keys are omitted. +fields: { + // Read-only: visible but not editable + 'account.annual_revenue': { readable: true, editable: false }, + 'account.description': { readable: true, editable: true }, + // Hidden: not visible at all + 'account.ssn': { readable: false, editable: false }, + 'opportunity.amount': { readable: true, editable: true }, + 'opportunity.probability': { readable: true, editable: false }, +} +``` + +2 つのフラグで 3 つの状態が生まれます。 + +| 状態 | ルール | 効果 | +|---|---|---| +| **非表示** | `{ readable: false, editable: false }` | フィールドはまったく見えません。すべてのレスポンスから取り除かれます | +| **読み取り専用** | `{ readable: true, editable: false }` | フィールドは返されますが、それへの書き込みは拒否されます | +| **編集可能** | `{ readable: true, editable: true }` | フィールドは見えて、書き込めます | + +> フィールドの権限のキーは、常に**オブジェクトで修飾して**書きます（`budget` ではなく `crm_lead.budget`）。ObjectStack 14.4 以降、`security-fls-unqualified-key` の lint はコンパイル時に素のキーを拒否します。それらは黙って何にも一致していなかったからです。 + +## マスクされたフィールド [#masked-fields] + +ObjectStack 17.1 以降、フィールドは**マスク**することもできます。値の大部分を置き換えて提供するので、開示されることなく識別できる状態が保たれます。マスクは権限セットではなく、フィールドそのものに宣言します。 + +```ts +// Fields of an object; the object around them is omitted. +mobile: Field.phone({ + label: 'Mobile', + maskingRule: 'phone', // served as 138****5678 + requiredPermissions: ['view_pii'], // holders of view_pii see the stored value +}), +tax_id: Field.text({ + label: 'Tax ID', + maskingRule: { keepHead: 2, keepTail: 2 }, // keep two characters at each end +}), +``` + +`maskingRule` は 5 つのプリセット（`phone`、`id_card`、`bank_account`、`email`、`name`）のいずれか、または両端に残す文字数を表す `{ keepHead, keepTail }` を取ります。マスクは決定的で、値の長さを保ちます。 + +保存された値を見られるのは誰か： + +| 呼び出し元 | 見えるもの | +|---|---| +| フィールドの `requiredPermissions` の機能を**すべて**持っている | 保存された値 | +| フィールドが `requiredPermissions` を宣言している場合の、それ以外の全員 | マスク | +| フィールドが `requiredPermissions` を宣言していない場合の、システムのコンテキスト以外の全員 | マスク | +| `readable: false` の付与によってフィールドが隠される呼び出し元 | 何も見えません。フィールドは隠されたままです | + +`requiredPermissions` の機能は、ほかの機能と同じく権限セットで付与されます。マスクが隠されたフィールドを広げることは決してありません。`readable: false` の付与は、引き続きフィールドを完全に取り除きます。 + +マスクはすべての画面で 1 つの値です。API のレスポンス、リストビューとフォーム、CSV と XLSX のエクスポート、AI エージェントが読むコンテキストのすべてが、同じマスクを提供します。漏洩を防ぐためのルールがさらに 2 つあります。 + +- **マスクされたフィールドはクエリできません。** それによるフィルター、並べ替え、グループ化、集計は、隠されたフィールドと同じく拒否されます。[API での強制](#enforcement-in-the-api)を参照してください。 +- **マスクが値を上書きすることは決してありません。** マスクされたプレースホルダーを送り返す書き込み（読み取ったレコード全体を再送信するクライアント）は、`138****5678` を保存する代わりに `400 VALIDATION_ERROR` で拒否されます。 + +## 付与はどう組み合わさるか [#how-grants-combine] + +FLS は**デフォルトで表示（ブロックリスト）の意味**を使います。明示的なルールのないフィールドは、そのまま通過します。読み取り可能*かつ*書き込み可能です。権限セットが制約するのは、明示的に列挙したフィールドだけです。 + +フィールドの付与は、ユーザーのセットをまたいで**最も許容的に**合算されます。あるセットの `readable: true` は、別のセットの `false` に勝ちます。減算的なミュートの層（ADR-0066 ⑧ として予約）が導入されるまでは、`{ readable: false }` のルールがフィールドを隠すのは、**ユーザーが持つほかのどのセットも**それを `readable: true` と宣言していない間だけです。実際的な結果： + +- 機密性の高いフィールドは、それが必要なセットで**だけ**付与することで保護します。あるセットの `false` のルールが別の場所の `true` を上書きすることに頼ってはいけません。 +- 広く付与されたオブジェクト上の機密性の高いフィールドは、見直すべき兆候として扱ってください。 + +宣言されたルールそのものは安全側に倒れて強制されます。隠されたフィールドは読み取り時に取り除かれ、編集不可能なフィールドへの書き込みは例外を投げます。 + +## API での強制 [#enforcement-in-the-api] + +SecurityPlugin のミドルウェアは、リクエストが REST、ObjectQL、そのほかのどの経路で届いたかにかかわらず、サーバーでフィールドのルールを強制します。下位レベルの API を通る裏口はありません。 + +**読み取り時**：`find` / `findOne` の結果は、レスポンスがエンジンを離れる前に、すべてのレコードから読み取り不可能なフィールドが取り除かれ、マスクされたフィールドはマスクに置き換えられます。 + +**クエリ時**：呼び出し元が読めない、またはマスクされた状態でしか読めないフィールドは、行の選択にも使えません。どの行が一致するかによって、1 回の探りごとにその値が開示されてしまうからです。それによるフィルター、並べ替え、グループ化、集計は `403 PERMISSION_DENIED` で拒否されます。ObjectStack 17.6 以降、これはデータ API のフィルターと並べ替えだけでなく、すべてのクエリの入口で成り立ちます。 + +- フィルターや集計の中で、比較の右辺として指定されたフィールド +- 分析のクエリ +- アクティビティストリーム、[監査ログ](/docs/operate/audit-logs)、承認のスナップショットにコピーされた値に対するフィルターと並べ替え。フィルターが等価比較で 1 つのオブジェクトを指定し、呼び出し元がそのすべてのフィールドを読める場合を除いて拒否されます + +**書き込み時**：`insert` / `update` のリクエストは、操作がドライバーに届く**前に**チェックされます。呼び出し元が編集を許されていないフィールドがペイロードに含まれていれば、エンジンは問題のフィールド名とともに `PermissionDeniedError`（HTTP 403）を投げます。 + +```json +{ + "error": { + "code": "PERMISSION_DENIED", + "message": "[Security] Field write denied: not permitted to edit [salary, ssn] on 'employee'", + "details": { + "operation": "insert", + "object": "employee", + "forbiddenFields": ["salary", "ssn"] + } + } +} +``` + +**なぜ黙って取り除かずに例外を投げるのか？** 黙って取り除くと、誠実なクライアントからはセキュリティの境界が見えなくなり（更新が「保存されない」のに理由がわからない）、*しかも*探りを入れるクライアントにも、どちらの方向にも何の手がかりも与えません。例外を投げれば、境界はどちらの方向にも観察できるようになります。正当な UI は修正すべき実用的なエラーを受け取り、探りを入れるクライアントは、すでに推測できた以上のことを何も知りません。 + +強制についての詳細がさらに 2 つあります。 + +- **一括の挿入**は行ごとにチェックされます。どの行であれ問題のフィールドが 1 つでもあれば、バッチ全体がアトミックに拒否されます。 +- **システムの操作**（`ExecutionContext { isSystem: true }`）はチェックを完全にすり抜けます。マイグレーション、初期データの読み込み、監査ログの書き込みに使われます。 + +## フォームとビューでの FLS [#fls-in-forms-and-views] + +生成されたフォームとインラインのグリッドは、編集不可能なフィールドを UI から隠しますが、それは **UX の層にすぎません**。上のサーバー側のチェックが正であるので、動作はどこでも一貫しています。 + +| 画面 | 非表示のフィールド | マスクされたフィールド | 読み取り専用のフィールド | +|---|---|---|---| +| レコードのフォーム / インラインのグリッド | レンダリングされません | 値はマスクされて表示されます。マスクを書き戻すと `400 VALIDATION_ERROR` で拒否されます | 編集用のコントロールなしでレンダリングされます。直接の書き込みの試みは 403 で拒否されます | +| リストビュー、関連リスト、エクスポート | 列の値はレスポンスから取り除かれます | マスクされた値が表示されます。CSV と XLSX のエクスポートでも同じです | 値は通常どおり表示されます | +| REST / ObjectQL | 結果から取り除かれます | マスクされた値が返されます | 読み取り時は返されます。書き込みは `forbiddenFields` とともに `PERMISSION_DENIED` を投げます | +| MCP / AI エージェント | 取り除かれます。エージェントは[呼び出したユーザーとして実行されます](/docs/configure/mcp#permission-enforcement) | REST と同じ | REST と同じ | +| フィルター、並べ替え、グループ化、集計 | `403 PERMISSION_DENIED` で拒否されます | `403 PERMISSION_DENIED` で拒否されます | 許可されます | + +読み取りはエラーにならずに取り除かれるので、隠されたフィールドはそのユーザーには単に存在しないように見えます。それが狙いです。それに対するクエリは例外で、上のとおり `403` で応答します。 + +## FLS を確認してレビューする [#verifying-and-reviewing-fls] + +- **判定ごとに、実行時に**：[explain エンジン](/docs/configure/permissions#diagnose--audit)は、ほかのすべての層と並べて FLS の層の判定を報告し、寄与した権限セットの名前を示します。また、マスクされたフィールドを隠されたものではなくマスクされたものとして報告します。ユーザーがフィールドが「ない」と報告してきたときに使ってください。 +- **変更ごとに、ビルド時に**：アプリがアクセスマトリクスのスナップショットのゲートを有効にしている場合、`os compile` は導出された（権限セット × オブジェクト）の機能のマトリクスを、コミットされた `access-matrix.json` と比較し、ずれがあれば失敗します。そのため機能の変更は、レビューできる意味上の差分としてプルリクエストに載ります。 + +```bash +os compile --update-access-matrix +``` + +> フィールドが機密性の高いデータを持つ場合は、読み取り専用ではなく**非表示**をデフォルトにします。読み取り専用でも、値はレスポンスとログに漏れます。フィールドのルールは実際の職務に合った権限セットにまとめ、コンプライアンスのケースでは監査ログの保持と組み合わせてください。作成のパターンはほかにもあります：[Permission Sets](/docs/configure/permissions/permission-sets#field-security-appendix)。 + +## 次に進む [#where-to-go-next] + +| タスク | ページ | +|---|---| +| 権限セットの中でフィールドのルールを作成する | [権限セット](/docs/configure/permissions/permission-sets) | +| そもそもどの行に到達できるかを制御する | [レコードアクセス](/docs/configure/permissions/record-access) | +| 階層化されたモデルの全体を見る | [権限](/docs/configure/permissions) | +| 特定のユーザーのアクセスを確認する | [アクセスの管理](/docs/configure/permissions/managing-access) | +| AI エージェントが何を読めるかを確認する | [AI ツールを接続する（MCP）](/docs/configure/mcp) | diff --git a/content/docs/configure/permissions/hierarchy-visibility.ja.mdx b/content/docs/configure/permissions/hierarchy-visibility.ja.mdx new file mode 100644 index 0000000..9b372dc --- /dev/null +++ b/content/docs/configure/permissions/hierarchy-visibility.ja.mdx @@ -0,0 +1,106 @@ +--- +title: 階層による表示範囲 +seoTitle: "階層による表示範囲：マネージャーに部下のレコードを見せる" +description: 読み手がどこに位置するか（その事業単位、その下の単位、またはその報告ライン）によって、誰がレコードを読めるかを広げます。unit、unit_and_below、own_and_reports のスコープを使います。 +editions: [cloud, enterprise] +translation: + source_sha: 11e8c60b7087869d03eca49ac3513df7dd066eef47d302fd1b95ffe53d110258 + guide_rev: 1 + mode: auto +--- + +**階層による表示範囲**は、組織の中で*どこに位置するか*によって、人が読めるレコードを広げます。地域マネージャーは自分の地域の誰かが所有するすべてのレコードを見られ、チームリーダーは直属と間接の部下のレコードを見られます。これは[権限セット](/docs/configure/permissions/permission-sets)でオブジェクトごとに、読み取り（または書き込み）の**スコープ**として設定します。 + +> **利用できる場所。** セルフマネージドの ObjectOS Enterprise のデプロイメントで、`hierarchySecurity` 機能を含むライセンスのもと。ObjectOS Cloud では、Enterprise 契約のもと。それ以外のどこでも、このページの 3 つのスコープは所有者自身のレコード以上のものを何も付与しません。*開いた*側に倒れて失敗することは決してありません。[要件](#requirements)を参照してください。 + +## 3 つのスコープ [#the-three-scopes] + +`own`（レコードの所有者）と `org`（組織内の全員）はすべてのエディションで機能します。3 つの階層のスコープは、その間に位置します。 + +| スコープ | 読み手が見られるのは、次の人が所有するレコード | 構築の元 | +|---|---|---| +| `unit` | 読み手と、読み手の事業単位のほかのすべてのメンバー。下へは降りません。 | 読み手のポジションの割り当て、なければ単位のメンバーシップ | +| `unit_and_below` | 読み手の事業単位**とツリーでその下にあるすべての単位**、そしてそのすべてのメンバー | 事業単位のツリー | +| `own_and_reports` | 読み手と、管理の連鎖でその下にいる全員（直属と間接） | 各ユーザーのマネージャー | + +スコープは、人が読めるものを**広げる**だけです。共有ルールとレコードの共有に追加され、誰かがすでに持っているアクセスを取り除くことはなく、`org` を越えることもありません。スコープが決めるのは権限が*どのレコード*に適用されるかであって、新しい権限を付与することは決してありません。 + +### 例 [#example] + +事業単位のツリーには **Region** があり、その下に **Team**、そして兄弟の単位 **Other** があります。Alice と Carol は Region に、Bob は Team に、Dave は Other にいます。Bob は Alice の部下です。 + +- `unit` の Alice が見られるのは **Alice、Carol** です。Bob と Dave は見られません。 +- `unit_and_below` の Alice が見られるのは **Alice、Carol、Bob** です。Region は Team へ降ります。兄弟の単位の Dave は外れたままです。 +- `unit_and_below` の Bob が見られるのは **Bob だけ**です。下に何もない単位が、親へと*上に*広がることはありません。 +- `own_and_reports` の Alice が見られるのは **Alice、Bob** です。Bob の単位がどこであっても、彼女の部下だからです。 + +## スコープを設定する [#set-a-scope] + +権限セットのオブジェクトのエントリに `readScope`（必要なら `writeScope` も）を設定します。地域全体を読む営業担当者： + +```ts +// Keys of a permission set; its other keys are omitted. +objects: { + opportunity: { allowRead: true, allowEdit: true, readScope: 'unit_and_below' }, +} +``` + +自分の報告ラインに限られるチームリーダー： + +```ts +// Keys of a permission set; its other keys are omitted. +objects: { + opportunity: { allowRead: true, readScope: 'own_and_reports' }, +} +``` + +階層のスコープを使う、コードで書かれたスタックは `requires: ['hierarchy-security']` を宣言しなければなりません。なければスタックはビルドされません。スコープを解決できない環境は、それを使うメタデータの公開を拒否し、そのようなドラフトが保存されたときに警告します。 + +## どの単位があなたのものか [#which-unit-is-yours] + +`unit` と `unit_and_below` では、読み手の単位はまず**ポジションの割り当て**から取られます。現在の各割り当てが配置されている事業単位です。配置された割り当てを持たない読み手だけが、**メンバー**である単位にフォールバックします。 + +これは、複数の単位に属していても 1 つしか管理していない人にとって重要です。Alice は **Region** と部門横断の **Project** 単位のメンバーですが、彼女のセールスマネージャーのポジションは Region で割り当てられています。`unit` では、彼女が見られるのは Region のメンバーだけです。Project のメンバーシップが、彼女の読めるものを広げることはありません。 + +- **配置された割り当てが複数あれば合算されます**：読み手の単位はそのすべてです。 +- **期限切れの割り当ては数えられません**：valid-from / valid-until の期間外にある割り当ては、その単位の付与を止めます。 + +割り当てと事業単位のツリーについては[ポジション](/docs/configure/permissions/positions)を参照してください。 + +## 投入するデータ [#what-to-populate] + +スコープは、ディレクトリや人事のソースが SCIM、連携、管理画面を通じて提供するデータを読みます。 + +| データ | 使うもの | +|---|---| +| 事業単位のツリー（各単位の親） | `unit_and_below` | +| ポジションの割り当て（事業単位と有効期間付き） | `unit`、`unit_and_below`（第一候補） | +| 事業単位のメンバーシップ | `unit`、`unit_and_below`（フォールバック） | +| 各ユーザーの**マネージャー** | `own_and_reports` | + +どちらのたどり方も 20 階層までに制限されているので、不正なツリーや偶然の報告の循環が無限ループになることはありません。結果はユーザーごとに短時間キャッシュされ、ツリー、メンバーシップ、割り当て、またはユーザーのマネージャーが変わるたびに消去されます。 + +## 報告ラインは 1 つの組織の中にとどまる [#a-reporting-line-stays-inside-one-organization] + +複数の組織を持つデプロイメントでは、マネージャーとその部下は少なくとも 1 つの組織を共有していなければなりません。 + +- **組織をまたいでマネージャーを設定することは拒否されます。** 部下と提案されたマネージャーがどちらも組織に属していて、1 つも共有していない場合、書き込みは `400 INVALID_REFERENCE`（`reason: 'cross-organization-manager'`）で拒否されます。管理画面、API、インポート、システムのコードのいずれからでも同じです。修正するには、2 人に共有の組織を与えるか、部下自身の組織の中からマネージャーを選びます。 +- **「同じ組織」ではなく「組織を共有する」です。** グループと工場の両方のメンバーであるグループレベルのマネージャーは、どちらの人も管理できます。 +- **まだ組織を持たないユーザーが拒否されることは決してなく**、たどる対象から外されることもありません。 +- **読み取りも同じルールに従います。** `own_and_reports` は境界で止まります。別の組織にだけ属する部下は外され、その下の全員も外されます。 + +グループレベルの監督のためには、その人に監督する組織のメンバーシップを与えてそこでより広いスコープの権限セットを付与するか、1 つの組織の中で事業単位のツリーを使ってください。 + +## 要件 [#requirements] + +- **セルフマネージドの ObjectOS Enterprise：** 機能に `hierarchySecurity` を含むライセンス（デフォルトの Enterprise の機能セットは含みます）。なければ、スコープは `own` として動作します。 +- **ObjectOS Cloud：** Enterprise 契約。Free と Team ではスコープは `own` として動作し、環境はそれを使うメタデータの公開を拒否します。 +- **ObjectOS Community：** 利用できません。スコープは `own` として動作します。 + +ほかのすべての Enterprise の機能と同じく、権利を失うとアクセスが狭まります。ランタイムが止まることは決してありません。 + +## 次へ [#next] + +- [権限セット](/docs/configure/permissions/permission-sets)：スコープを設定する場所。 +- [レコードアクセス](/docs/configure/permissions/record-access)：スコープが追加される先の、共有ルールとレコードの共有。 +- [ポジション](/docs/configure/permissions/positions)：割り当てと事業単位のツリー。 diff --git a/content/docs/configure/permissions/index.ja.mdx b/content/docs/configure/permissions/index.ja.mdx new file mode 100644 index 0000000..8ab681a --- /dev/null +++ b/content/docs/configure/permissions/index.ja.mdx @@ -0,0 +1,141 @@ +--- +title: 権限 +seoTitle: "権限モデル：ポジション、権限セット、レコードアクセス" +description: アイデンティティ、ポジション、権限セット、レコードアクセス、フィールドのセキュリティ。アクセスモデルの全体を 1 ページで。 +editions: [community, cloud, enterprise] +translation: + source_sha: 62da1addaebe59555e84667986dd672e36ad681514d179b84709100b01fc0b61 + guide_rev: 1 + mode: auto +--- + +ObjectOS は、エンタープライズソフトウェアで 20 年にわたって機能してきた定石から借りた、階層化されたアクセスモデルを持っています。アイデンティティ → ポジション → 権限セット → レコードアクセス → フィールドのセキュリティです。各層は異なる問いに答え、必要のない層は無視できます（ObjectStack 13 では、旧来の Roles と Profiles の概念が**ポジション**に統合されました。[ポジション](/docs/configure/permissions/positions)を参照してください）。 + +## 1 枚の図で見るモデル [#the-model-in-one-diagram] + +```text +Authentication Who is the caller? + ↓ +Identity Which user/org/membership is active? + ↓ +Positions Which job functions do they hold? + ↓ +Permission sets What CAN they do — apps, objects, fields, system? + ↓ +Record access WHICH records can they touch? + ↓ +Field security For those records, which FIELDS are readable / writable? +``` + +各層はセキュリティプラグインによって強制されます。シンプルなアプリでは権限セットだけ（ポジションも共有ルールもなし）を使い、要件が出てきたところで残りを追加できます。 + +## 第 1 層：アイデンティティ [#layer-1--identity] + +アイデンティティのオブジェクトはプロジェクトのデータベースにあります。最も重要なもの： + +| オブジェクト | 表すもの | +|---|---| +| `sys_user` | 認証できる人、またはサービスアカウント | +| `sys_organization` | テナント / ワークスペースの境界（マルチテナントのアプリ） | +| `sys_member` | 組織におけるユーザーのメンバーシップ | +| `sys_business_unit`、`sys_team` | 共有ルールのための省略可能な組織構造 | +| `sys_invitation` | 承諾を待っている保留中の招待 | +| `sys_session` | アクティブな認証済みセッション | +| `sys_api_key` | ユーザーに結び付いた、長期間有効なプログラム用の認証情報 | + +マルチテナントのデプロイメントでは： + +- ユーザーはプロジェクトのデータベースにスコープされます。 +- セッションはプロジェクトのホスト名にスコープされます。 +- 行レベルのチェックは、現在のユーザーの組織と権限を使います。 +- コントロールプレーンのユーザーが自動的に業務ユーザーになることは**ありません**。プラットフォーム SSO または明示的なプロビジョニングで対応付ける必要があります。 + +これらは実行時に **Setup**（`/_console/`）で作成 / 管理するか、新しい環境のために `objectstack.config.ts` で初期投入します。 + +## 第 2 層：ポジション [#layer-2--positions] + +ポジションは職務（「Sales Manager」、「Support Agent」）をモデル化します。ポジションはフラットです。階層は事業単位のツリーにあるので、共有ルールやレポートは「レコードの所有者の単位とその下位の単位」のような言い方をします。初期投入される対象者のアンカー `everyone`（認証されたすべてのユーザー）を使えば、カスタムのフォールバックのロジックなしにベースラインの権限セットをバインドできます。その対になる `guest`（匿名の呼び出し元）は何も付与しません。匿名の訪問者がデータに届くのは、公開フォームや共有リンクのように、それを宣言した画面を通じてだけです。ポジションは職務ごとに権限セットを配布するのに使い、フラットなチームではカスタムのポジションを省略してください。 + +[ポジション](/docs/configure/permissions/positions)を参照してください。 + +## 第 3 層：権限セット [#layer-3--permission-sets] + +権限セットは、機能を付与する主な方法です。ユーザーに直接、またはポジションを通じて付けます。 + +### 何を付与するか [#what-they-grant] + +| 種類 | 例 | +|---|---| +| アプリケーションへのアクセス | CRM を開く、サポートポータルを開く | +| オブジェクトの権限 | オブジェクトのレコードを作成 / 読み取り / 更新 / 削除する | +| フィールドの権限 | 特定のフィールドを読み取る、または更新する | +| システムの権限 | Setup にアクセスする、レポートを実行する、監査ログを表示する | +| 連携の権限 | API キーを使う、Webhook を設定する、管理アクションを実行する | + +### オブジェクトの権限フラグ [#object-permission-flags] + +セキュリティプラグインがチェックする、正確なフラグの名前です。 + +| フラグ | 意味 | +|---|---| +| `allowRead` | レコードアクセスによってユーザーが見られるレコードを読み取ります | +| `allowCreate` | 新しいレコードを作成します | +| `allowEdit` | ユーザーが見られるレコードを更新します | +| `allowDelete` | ユーザーが見られるレコードを削除します | +| `allowExport` | オブジェクトのレコードの、機械可読な一括コピーを取ります | +| `viewAllRecords` | レコードアクセスのルールを無視して、そのオブジェクトの**すべての**レコードを読み取ります | +| `modifyAllRecords` | **すべての**レコードを更新 / 削除します。`viewAllRecords` を含意します | + +`viewAllRecords` と `modifyAllRecords` は、そのオブジェクトについてのテナント全体のスーパーユーザーの付与です。明示的な管理用の権限セットのために取っておき、ユーザー向けのどのポジションにも含めないでください。 + +**エクスポートは独立したオプトインの付与です。** `allowExport` が未設定なら**拒否**を意味します。`allowRead` から継承されることはなく、`viewAllRecords` / `modifyAllRecords` もそれを与え**ません**。レコードを読むことと、テーブル全体の機械可読なコピーを取ることは別の行為であり、これはその 2 つを分ける職務分掌の軸です。エクスポートすべき人が持つすべてのセットで、オブジェクトのエントリ（またはワイルドカード `'*'`）に明示的に付与してください。[Permission Sets](/docs/configure/permissions/permission-sets#export-is-its-own-grant) を参照してください。 + +[権限セット](/docs/configure/permissions/permission-sets)を参照してください。 + +## 第 4 層：レコードアクセス [#layer-4--record-access] + +`viewAllRecords` を持た**ない**ユーザーは、どの行を見られるのでしょうか。 + +このモデルは次のものをサポートします。 + +- 暗黙の所有（ユーザーが作成した、または所有している行） +- 共有ルール（宣言的。「チーム A はチーム A のレコードを見られる」） +- 明示的な共有（`sys_record_share` の行。ユーザー、ポジション、または単位とその配下に付与する一回限りの共有） +- 組織によるスコープ（行の `organization_id` がユーザーの組織と一致する） + +ObjectStack 13 以降、所有者のフィールドを持つカスタムオブジェクトの共有モデルのデフォルトは**非公開**です。公開するには `sharingModel` を明示的に宣言してください。 + +[レコードアクセス](/docs/configure/permissions/record-access)を参照してください。 + +## 第 5 層：フィールドのセキュリティ [#layer-5--field-security] + +ユーザーがレコードを見られる場合でも、個々のフィールドは次のようにできます。 + +- **非表示**：フィールドは API と UI のレスポンスから取り除かれます。 +- **読み取り専用**：フィールドは返されますが、書き込みは拒否されます。 +- **マスク**：呼び出し元がそのフィールドの要求する機能を持っていない限り、値の大部分が置き換えられて返されます（`138****5678`）（ObjectStack 17.1）。 + +非表示と読み取り専用はオブジェクトごと + 権限セットごとに設定し、マスクはフィールドそのものに宣言します。典型的な使い方： + +- `sys_user` の `salary` を、人事以外の全員から隠す。 +- `external_account_id` を、サポート担当者には読めるが編集できないようにする。 +- 顧客の電話番号を、顧客に電話をかけるチーム以外の全員には `138****5678` と表示する。 + +これはオブジェクトの権限と同じ評価器で強制されるので、REST、ObjectQL、UI のすべてに一様に適用されます。[フィールドレベルのセキュリティ](/docs/configure/permissions/field-level-security)を参照してください。 + +## どこから始めるか [#where-to-start] + +| 構築しているもの | 使うもの | +|---|---| +| 単一チームの社内ツール | 権限セットだけ | +| マネージャーがレポートを見る複数チームのアプリ | 事業単位 + ポジション + 権限セット | +| マルチテナントの SaaS 型アプリ | 組織によるスコープ + 権限セット | +| 個人情報を扱う規制対象のアプリ | その上にフィールドのセキュリティを追加 | +| 複雑な CRM 型アプリ | すべての層 | + +## 診断と監査 [#diagnose--audit] + +- **explain エンジン**（`explain(principal, object, operation)`）は、必要な権限、オブジェクトの CRUD、フィールドのセキュリティ、OWD のベースライン、共有、行レベルセキュリティの各層の判定を順に、層ごとの帰属とともに報告します。Studio の **Access** の柱は、これを「Why can this user access?」パネルとして表示します。ほかのユーザーについて説明するには `manage_users` 機能が必要です。 +- `/_console/` は、任意のユーザーの実効的な権限を、評価されるとおりに表示します。 +- 監査ログ（`sys_audit_log`）は、権限に関わる変更（付与、ロールの割り当て、権限セットの編集）を記録します。 +- 拒否されたリクエストは失敗したルール（オブジェクトの権限か、レコードアクセスか、フィールドのセキュリティか）を記録するので、サポートは「なぜこれが見えないのか？」に素早く答えられます。 diff --git a/content/docs/configure/permissions/managing-access.ja.mdx b/content/docs/configure/permissions/managing-access.ja.mdx new file mode 100644 index 0000000..5eb868c --- /dev/null +++ b/content/docs/configure/permissions/managing-access.ja.mdx @@ -0,0 +1,145 @@ +--- +title: アクセスの管理 +seoTitle: "アクセスの管理：入社、ロールの変更、退社" +description: 日々の管理の手引き。新入社員を迎え入れ、ロールを変更し、誰かが何を見られるかを確認し、きれいに退社させます。 +editions: [community, cloud, enterprise] +translation: + source_sha: be810828c60d389cf16c7b89bedd3c8e68110d089cd9da60fb2c59a3a67321be + guide_rev: 1 + mode: auto +--- + +これは、管理者が毎週扱うアクセスの問題のためのタスクガイドです。[モデルの概要](/docs/configure/permissions)は各層が*どう*機能するかを説明し、このページは*何をクリックするか*を説明します。 + +> **日々の管理作業の 90% は、人をポジションに割り当てることです。** ポジション、その背後にある権限セット、セキュリティのベースラインは、プラットフォームとインストールしたアプリとともに提供されます。機能を一から作ることはほとんどなく、そうすべきでもありません。 + +ユーザーの実効的なアクセスは加算的です。 + +```text +effective access = union of permission sets reached through positions + + direct grants + + the built-in member_default baseline +``` + +制限は*付与しない*ことで行います。保守すべき減算のルールはありません。 + +## 新入社員を迎え入れる [#onboard-a-new-hire] + +順序のある 4 つのステップで、それぞれが前のステップに依存します。 + +| ステップ | 場所 | 内容 | +|---|---|---| +| 1. ユーザーを作成する | Setup → People & Organization → Users | **Invite**、**Create**、または **Import**。[ユーザーと組織](/docs/configure/users#add-people)を参照してください | +| 2. 組織ツリーに配置する | 同じリスト → Business Unit Member の行 | ユーザー + 事業単位、1 つを*主*としてマークします。深さに基づく表示範囲はこれを通じて解決されます | +| 3. ポジションを割り当てる | Setup → Access Control → Positions | 日々の 90%。下記を参照してください | +| 4. 確認する | Impersonate + Explain | テストせずに「準備できました」と伝えてはいけません。下記を参照してください | + +### ポジションを割り当てる [#assigning-positions] + +割り当ては 1 つの行です。**User Position**（`sys_user_position`）= *ユーザー* + *ポジション* + 省略可能な、そのポジションを保持する**事業単位**。このアンカーが、ポジションの深さの付与が*どこに*適用されるかを決めます。「**East の**セールスマネージャー」は、会社全体ではなく East のレコードを見ます。 + +**Setup → Access Control → Positions** でポジションを開き、その関連リストから割り当てを追加します（または User Position の行を直接作成します）。これらの書き込みは統制されています。テナントレベルの管理者は通過し、委任された管理者は自分のサブツリーの中で、許可リストにあるセットだけを割り当てられます。自分自身の権限の昇格は構造的に拒否されます（[委任された管理](/docs/configure/permissions/permission-sets#delegated-administration)を参照）。 + +隣接する 2 つの画面で全体像が完成します。 + +- **直接の付与**：権限セットのレコードページ（**Setup → Access Control → Permission Sets**）にある **Assigned Users** パネルは、ポジションなしにユーザーごとの付与を追加します。*ポジションを通じて*保持されている行も表示されますが、削除はここではなくポジションで行います。 +- **事業単位のメンバーシップ**：ステップ 2 のものです。割り当てのアンカーとは独立しています。 + +## 誰かのロールを変更する [#change-someones-role] + +誰かが部署や職務を変えたとき： + +1. その人の **Business Unit Member** の行を新しい単位に更新します。 +2. **User Position の行を付け直します。** 古い単位をアンカーとする割り当てを削除または編集し、新しい単位の割り当てを追加します。 +3. 古いロールに属していた直接の付与を削除します。 +4. 確認します（下記）。 + +割り当ては `valid_from` / `valid_until` の期間を持てます。期限切れの付与は即座に解決されなくなるので、計画的な異動や一時的な代行のロールを扱うきれいな方法です。[権限セット](/docs/configure/permissions/permission-sets)を参照してください。 + +## 誰かが何を見られるかを確認する [#verify-what-someone-can-see] + +組み込みの確認ツールが 2 つあります。 + +- **Impersonate。** Users のリスト → 行のメニュー → **Impersonate User**。そのユーザーのセッションを得られます。その人が開くアプリを開き、見えるべきものが見え、見えるべきでないものが見え*ない*ことを確認します。なりすましは正当なサポートと確認のためのもので、セッションは記録されます。 +- **Explain。** Studio の **Access** の柱 → **Explain access**：ユーザー、オブジェクト、操作を選ぶと、エンジンが判定とすべての評価の層を返します。どの権限セットが付与したか、それをどのポジションを通じて保持しているか、どの共有ルールが広げたか、どのポリシーが絞り込んだかです。 + +同じレポートは REST でも利用できます。 + +```bash +# GET, query-string form +curl -H "Authorization: Bearer $TOKEN" \ + "$BASE/api/v1/security/explain?object=crm_lead&operation=read&userId=usr_123" + +# POST, body form +curl -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ + -d '{"object":"crm_lead","operation":"read","userId":"usr_123"}' \ + "$BASE/api/v1/security/explain" +``` + +`operation` は `read | create | update | delete | transfer | restore | purge` のいずれかです（デフォルトは `read`）。`userId` を省略すると**自分自身**について説明します。自分自身についての説明は常に許可されます。*ほかの*ユーザーについて説明するには、`manage_users` 機能か、そのユーザーをカバーする委任された管理のスコープが必要です。 + +> 何かが誤って解決されたときは、推測して切り替えるより、まず説明させるほうがうまくいきます。レポートが、修正すべき正確な権限セットと層を示します。[診断と監査のセクション](/docs/configure/permissions#diagnose--audit)を参照してください。 + +## 誰かを退社させる [#offboard-someone] + +1. **Ban User**：サインインを即座にブロックします。急ぐ必要があるのはこのステップだけです。 +2. ポジションの割り当てと直接の付与を、落ち着いて削除します。 +3. Business Unit Member の行を削除するか、親を付け替えます。 +4. そのユーザーに結び付いた API キーを失効させます。キーはそのユーザーとして動作し、基になる付与が存在する間は機能し続けます。 + +## 提供されたポジションが合わないとき [#when-the-shipped-positions-dont-fit] + +権限は Studio で*設計し*、Setup で*割り当てます*。提供されたポジションでは足りない場合は、機能する最小の変更を次の順で選んでください。 + +1. **既存の権限セットをポジションにバインドします。** +2. **提供されたセットを複製して調整します。** +3. Studio の権限セットのマトリクスエディターで**新しいセットを作成します**。オブジェクトの CRUD、フィールドレベルのセキュリティ、機能のための構造化されたスプレッドシートで、JSON を手で書くことはありません。 + +アプリとともに提供されたセットを編集すると、*環境のオーバーレイ*が作られます。あなたの変更が優先され、アップグレードを越えて残り、ベンダーのベースラインにリセットすることもできます。加算的なモデルを念頭に置いてください。まとまりのある機能の束を作成し、「減算のセット」は決して作らないでください。[権限セット](/docs/configure/permissions/permission-sets)を参照してください。 + +要件を変更に落とし込むときは、対応する層を選びます。 + +| 要件 | 層 | 扱っている場所 | +|---|---|---| +| オブジェクトの種類を読み取り / 作成 / 編集 / 削除できる | オブジェクトの権限 | [権限セット](/docs/configure/permissions/permission-sets) | +| 特定のフィールドを見られる / 編集できる | フィールドレベルのセキュリティ | [フィールドレベルのセキュリティ](/docs/configure/permissions/field-level-security) | +| ユーザーがどの*行*を見るか | レコードアクセス | [レコードアクセス](/docs/configure/permissions/record-access) | +| オブジェクトのレコードを一括エクスポートできる | オブジェクトの権限：`allowExport`。読み取りでは与えられ**ない**オプトインの付与です | [Export is its own grant](/docs/configure/permissions/permission-sets#export-is-its-own-grant) | +| 機能上の能力（ユーザーの管理、監査ログの表示） | システムの権限 | [権限セット](/docs/configure/permissions/permission-sets#system-permissions) | +| アプリやナビゲーションのエントリを開ける | アプリケーションへのアクセス | [権限セット](/docs/configure/permissions/permission-sets) | + +## よく使う手順 [#quick-paths] + +| やりたいこと | すること | +|---|---| +| 新しい従業員を迎え入れる | ユーザーを Invite/Create → Business Unit Member の行 → ポジションを割り当てる | +| 誰かを退社させる | **Ban User**（サインインを即座にブロック）、その後で割り当てを落ち着いて削除する | +| 「サインインできない」 | ユーザーのレコード → Ban されている？ロックされている？**Unlock Account** または **Set Password**（一時的で、変更が必須） | +| 「なぜ X が見えないのか？」 | Studio → Access → そのユーザー + オブジェクトについて **Explain access** | +| 誰かが部署を移った | その人の Business Unit Member の行を更新し、User Position の行を付け直す | +| 子会社に自社のスタッフを管理させる | [委任された管理のスコープ](/docs/configure/permissions/permission-sets#delegated-administration)を持つセットを付与する | +| 1 人のユーザーに機能を 1 つ追加する | 権限セットのレコード → **Assigned Users** → 追加（直接の付与） | + +## どこに何があるか [#where-is-everything] + +| もの | 場所 | +|---|---| +| ユーザー、招待 | Setup → People & Organization → Users / Invitations | +| 事業単位のツリー | Setup → People & Organization → Business Units | +| チーム | Setup → People & Organization → Teams | +| ポジション、権限セット | Setup → Access Control | +| 共有ルール、レコードの共有 | Setup → Access Control | +| パスワードのポリシー、MFA、ロックアウト、SSO | Setup → Configuration → Authentication | +| セッション、通知のイベント、監査ログ | Setup → Diagnostics | +| 権限のマトリクスエディター、Explain access | Studio → Access | + +## 次に進む [#where-to-go-next] + +| タスク | ページ | +|---|---| +| ユーザーを作成し、組織ツリーを作る | [ユーザーと組織](/docs/configure/users) | +| ポジションと対象者のアンカーを理解する | [ポジション](/docs/configure/permissions/positions) | +| 権限セットを作成または調整する | [権限セット](/docs/configure/permissions/permission-sets) | +| 人がどの行を見るかを制御する | [レコードアクセス](/docs/configure/permissions/record-access) | +| 機密性の高いフィールドを隠す、またはロックする | [フィールドレベルのセキュリティ](/docs/configure/permissions/field-level-security) | +| サインインのポリシーと SSO | [認証](/docs/configure/authentication) | diff --git a/content/docs/configure/permissions/permission-sets.ja.mdx b/content/docs/configure/permissions/permission-sets.ja.mdx new file mode 100644 index 0000000..3d5bf13 --- /dev/null +++ b/content/docs/configure/permissions/permission-sets.ja.mdx @@ -0,0 +1,152 @@ +--- +title: 権限セット +seoTitle: "権限セット：オブジェクト、フィールド、システムの付与" +description: アプリケーション、オブジェクト、フィールド、システムの権限を付与します。 +editions: [community, cloud, enterprise] +translation: + source_sha: a358f4bda450dc16411f50560d7b6c74d2257257f89d2e6a509da19a9b8f70eb + guide_rev: 1 + mode: auto +--- + +権限セットは、機能を付与する主な方法です。ユーザーに直接、または[ポジション](/docs/configure/permissions/positions)を通じて間接的に割り当てられます。割り当ては `valid_from` / `valid_until` の期間を持てます。期限切れの付与は即座に解決されなくなります。 + +## 権限セットが制御するもの [#what-permission-sets-control] + +| 権限の種類 | 例 | +|---|---| +| アプリケーションへのアクセス | ユーザーが CRM や Setup を開ける | +| オブジェクトの権限 | レコードを作成、読み取り、更新、削除する | +| フィールドの権限 | 選んだフィールドを読み取る、または更新する | +| システムの権限 | Setup にアクセスする、レポートを実行する、監査ログを表示する | +| 連携の権限 | API キー、Webhook、管理アクションを使う | + +## オブジェクトの権限 [#object-permissions] + +オブジェクトの権限は次の問いに答えます。 + +```text +Can this user perform this operation on this object at all? +``` + +権限セットの付与は、次のフラグの名前を使います（セキュリティプラグインの権限評価器が強制するとおりです）。 + +| フラグ | 意味 | +|---|---| +| `allowRead` | レコードアクセスのルールが許すレコードを読み取ります | +| `allowCreate` | レコードを作成します | +| `allowEdit` | レコードアクセスのルールが許すレコードを更新します | +| `allowDelete` | レコードアクセスのルールが許すレコードを削除します | +| `allowExport` | オブジェクトのレコードの、機械可読な一括コピーを取ります | +| `viewAllRecords` | レコードアクセスをすり抜けて、そのオブジェクトのすべてのレコードを読み取ります | +| `modifyAllRecords` | レコードアクセスをすり抜けて、そのオブジェクトのすべてのレコードを更新または削除します。読み取りについては `viewAllRecords` を含意します | + +`viewAllRecords` または `modifyAllRecords` が通常の行レベルの境界をすり抜けない限り、[レコードアクセス](/docs/configure/permissions/record-access)は引き続き重要です。これらのフラグは管理用の権限セットのために取っておいてください。事実上、そのオブジェクトについてのテナント全体のスーパーユーザーの付与です。 + +### エクスポートは独立した付与 [#export-is-its-own-grant] + +エクスポートはシステムの権限ではなく**オブジェクトの権限**であり、**オプトイン**です。 + +| `allowExport` | 結果 | +|---|---| +| 未設定 | エクスポートは**拒否** | +| `false` | 拒否 | +| `true` | 許可（引き続き `allowRead` の範囲内） | + +以前は、未設定は「読み取りを継承する」を意味していました。ObjectStack 17.0 以降は拒否を意味し、`viewAllRecords` / `modifyAllRecords` もそれを与えなくなりました。「すべてのデータを見てよい」と「その一括コピーを取ってよい」は、意図的に別の付与になっています。 + +```ts +// Keys of a permission set; its other keys are omitted. +objects: { + deal: { allowRead: true, allowExport: true }, // ← add the grant +} +``` + +計画しておくべき 3 つの結果： + +- **この付与を持つ提供済みのセットはなく、それを取り去るのはアップグレードです。** パッケージで提供されるセットはアップグレード時に再投入され、ObjectStack 17.1 以降、`admin_full_access`、`organization_admin`、そこから派生した `organization_admin_no_bypass` は、ワイルドカード `*` でエクスポートを付与しなくなりました。自動的な代替は意図的に用意されていません。エクスポートは、アプリ自身の権限セットの中で、オブジェクトごとに付与されます。管理者によるエクスポートを意図するところでは、自分で作成するセットで `allowExport` を明示的に付与してください。**環境で作成されたセットも、これを持ったことはありません**。ユーザーがエクスポートするカスタムのセットはすべて編集してください。パースの時点では何も失敗しないので、何も編集しないアップグレードは有効なメタデータのままで、その管理者は、どのアプリのセットも指定していないすべてのオブジェクトで、気づかないうちにエクスポートを失っています。 +- **`member_default` は意図的にこの付与を持ちません**。そのため一般の認証済みユーザーは、管理者が付与するまでエクスポートを失います。それがこの切り替えの目的であって、見落としではありません。 +- **`allowExport` を持つセットは高権限です**。そのため `everyone` や `guest` の対象者のアンカーにバインドすることはできません。そうでなければ、エクスポートできるセットを匿名のアンカーにバインドすることで、オプトインを無効にできてしまいます。 + +マージは CRUD のビットとまったく同じく、最も許容的なものが採用されます。割り当てられたセットのどれかが `true` を付与していればエクスポートが付与され、`false` と未設定は同じ結果になります。レポートも同じ軸で扱われます。 + +## システムの権限 [#system-permissions] + +システムの権限は、次のようなプラットフォームの操作のためのものです。 + +- Setup へのアクセス +- ユーザーの管理 +- ポジションと権限セットの管理 +- レポートの実行 +- 連携の管理 +- 監査ログの表示 + +管理者が簡単に監査できるように、システムの権限は業務オブジェクトの権限と分けておいてください。 + +## 推奨されるセット [#recommended-sets] + +名前付きのいくつかの権限セットから始めます。 + +| 権限セット | 目的 | +|---|---| +| Basic User | ログインし、メインのアプリケーションにアクセスする | +| Setup Administrator | ユーザー、ロール、設定、診断を管理する | +| Report Viewer | レポートとダッシュボードを表示する | +| Integration Operator | Webhook / API キーを管理する | +| Support User | サポートのオブジェクトを読み取る / 更新する | + +その後、顧客のアプリケーションのためのドメイン固有のセットを追加します。 + +セットに `isDefault` を付けると、そのセットを所有するパッケージがインストールされたときに、割り当ての候補として提案されます（13 より前の `isProfile` フラグを置き換えるものです）。 + +## 権限セットを無効にする [#deactivating-a-permission-set] + +権限セットの **Deactivate** アクションは、その付与を即座に止めます（ObjectStack 17.1）。無効化されたセットは、ユーザーに直接届く場合もポジションを通じて届く場合も、オブジェクト、フィールド、システム、タブの権限を何も与えず、本来与えるはずの管理者としての立場も与えません。`active` の値が空のセットは影響を受けません。数えられるのは明示的な無効化だけです。 + +2 つの結果： + +- **これで全員を締め出すことはできません。** 管理者を管理者たらしめているセットを無効にしようとすると、それを削除しようとしたときと同じ「最後の管理者」のガードによって拒否されます。 +- **17.1 を越えるアップグレードは取り消しです。** 17.1 より前はこのスイッチは何もしておらず、無効化されたセットも付与を続けていました。アップグレードの前に、無効化されたセットとポジションを一覧し、まだ付与を続けるべきものを再び有効にしてください。[ポジションを無効にする](/docs/configure/permissions/positions#deactivating-a-position)を参照してください。 + +## 委任された管理 [#delegated-administration] + +権限セットは、その保持者をスコープ付きの管理者にする `adminScope` を持てます。スコープは次のものを宣言します。 + +- 委任者が**どこで**操作できるか：事業単位のサブツリー +- **何を**できるか：`manageAssignments`、`manageBindings`、`authorEnvironmentSets` +- **どの**権限セットを配布できるか（`assignablePermissionSets`） + +委任者は、許可リストにあるセットに対してだけ単一の行を書き込み、すべての付与には監査のために `granted_by` が記録されます。それ自体が `adminScope` を持つセットを付与または作成するには、付与する側が、それを厳密に包含するスコープを持っている必要があります。テナントレベルの管理者は、このゲートを完全にすり抜けます。 + +## フィールドのセキュリティ（付録） [#field-security-appendix] + +権限セットはフィールドレベルの付与も持ちます。ユーザーがレコードを読める場合でも、個々のフィールドを隠したり、読み取り専用にしたりできます。 + +### 2 つのモード [#two-modes] + +| モード | 効果 | +|---|---| +| **非表示** | フィールドは API のレスポンスと生成されたビューから完全に取り除かれます | +| **読み取り専用** | フィールドは返されますが、書き込みは拒否されます | + +3 つ目の状態である**マスク**（`138****5678`）は、権限セットのモードではありません。フィールドに宣言されるもので、権限セットが決めるのは、マスクを外す機能を誰が持つかだけです。[Field-Level Security](/docs/configure/permissions/field-level-security#masked-fields) を参照してください。 + +### どこで強制されるか [#where-its-enforced] + +オブジェクトの権限をチェックするのと同じ評価器が、REST、ObjectQL、生成されたフォーム、エクスポートのすべての経路でフィールドのルールを適用します。下位レベルの API を通る「裏口」はありません。 + +### 典型的なパターン [#typical-patterns] + +| ユースケース | 推奨 | +|---|---| +| `sys_user` の人事データ（給与、社会保障番号） | `HR` 権限セット以外の全員から隠す | +| 外部システムの識別子 | サポートには読み取り専用、連携の運用者には書き込み可能 | +| `product` の社内コストと顧客価格 | `cost` を営業から隠し、財務には表示する | +| 保護対象の医療情報を含むメモのフィールド | 権限セットが該当する臨床上のロールを含まない限り隠す | + +### 作成のガイダンス [#authoring-guidance] + +- フィールドが機密性の高いデータを持つ場合は、読み取り専用ではなく**非表示**をデフォルトにします。読み取り専用でも、値はレスポンスとログに漏れます。 +- フィールドの権限のキーは、常に**オブジェクトで修飾して**書きます（`budget` ではなく `crm_lead.budget`）。ObjectStack 14.4 以降、`security-fls-unqualified-key` の lint はコンパイル時に素のキーを拒否します。それらは黙って何にも一致していなかったからです。 +- フィールドごとに 1 つのセットを作るのではなく、実際の職務（`HR Manager`、`Finance Read-only`）に合った権限セットにフィールドのルールをまとめます。監査が簡単になります。 +- コンプライアンスのユースケースでは、フィールドのセキュリティと監査ログの保持を組み合わせ、後から「誰がこの行を見たか？」に答えられるようにします。 diff --git a/content/docs/configure/permissions/positions.ja.mdx b/content/docs/configure/permissions/positions.ja.mdx new file mode 100644 index 0000000..bc3027a --- /dev/null +++ b/content/docs/configure/permissions/positions.ja.mdx @@ -0,0 +1,124 @@ +--- +title: ポジション +seoTitle: "ポジション：職務と対象者のアンカー" +description: ポジションで職務と対象者のアンカーをモデル化します。 +editions: [community, cloud, enterprise] +translation: + source_sha: 9a6096331cd3521f789262b74df4f6d0c036eb8279faa0759092e883c35b050c + guide_rev: 1 + mode: auto +--- + +ポジションは、ユーザーが担う職務（「Sales Manager」、「Support Agent」、「Auditor」）を記述します。ObjectStack 13（Permission Model v2、ADR-0090）以降、ポジションは人をグループ化する**唯一の**概念です。旧来の Role と Profile の枠組みはポジションに統合され、プロトコルから削除されました。 + +ポジションは意図的に**フラット**です。`parent` フィールドもポジションの階層もありません。報告の構造とサブツリーに基づく表示範囲は、代わりに[事業単位のツリー](/docs/configure/permissions/record-access)にあります。 + +## ポジションの役割 [#position-responsibilities] + +ポジションは次のもののモデル化に使います。 + +- 職務（「Sales Manager」、「Recruiter」、「Auditor」） +- アプリ、タブ、ブックの対象者の指定 +- 承認の責任（種類が `position` の承認者は、現在の保持者に自動的に展開されます） +- 同じ職務を持つ全員への[権限セット](/docs/configure/permissions/permission-sets)の配布 + +組織図（部署、地域、上司 / 部下の構造）のモデル化には**事業単位**を、オブジェクト、フィールド、システムの具体的な機能の付与には**権限セット**を使います。 + +## システムオブジェクト [#system-objects] + +| オブジェクト | 目的 | +|---|---| +| `sys_position` | ポジションの定義（フラット。階層なし） | +| `sys_user_position` | ユーザーのポジションへの割り当て | +| `sys_position_permission_set` | ポジションを通じて配布される権限セット | +| `sys_business_unit` | 階層とサブツリーの共有に使う組織図のツリー | +| `sys_business_unit_member` | 事業単位におけるユーザーのメンバーシップ（`function_in_business_unit`） | + +RBAC のリンクテーブル（`sys_user_position`、`sys_position_permission_set`、`sys_user_permission_set`、`sys_permission_set`）への書き込みには、テナントレベルの管理者権限か[委任された管理のスコープ](/docs/configure/permissions/permission-sets#delegated-administration)が必要です。それらのテーブルに対する単なる CRUD の付与では足りません。 + +## 対象者のアンカー：`everyone` と `guest` [#audience-anchors-everyone-and-guest] + +すべてのデプロイメントには、システム管理の 2 つのポジションが初期投入されています。 + +| アンカー | 保持者 | +|---|---| +| `everyone` | 認証されたすべてのプリンシパル（暗黙的に） | +| `guest` | セッションのない（匿名の）HTTP のプリンシパルだけ | + +サインインしたすべてのユーザーにベースラインを付与するには、権限セットを `everyone` にバインドします。バインディングは加算的で、プラットフォームは高権限のセット（View All / Modify All、delete/purge/transfer、システムの権限、ワイルドカード）をこれらのアンカーにバインドすることを拒否します。 + +**`guest` は何も付与しません。** オブジェクトのデータへの匿名のアクセスは、すべての HTTP の画面で拒否され（ObjectStack 17.0）、`guest` アンカーへのどのバインディングも、匿名の呼び出し元に権限セットを与えません（ObjectStack 17.6）。匿名の訪問者に何かを公開するには、代わりに画面を宣言します。[公開フォーム](/docs/build/interface/views#public-forms)や共有リンクで、それぞれ宣言したものだけを認可します。 + +設定されたベースラインの権限セット（`fallbackPermissionSet`、デフォルトは `member_default`）は、同じ `everyone` のバインディングの経路で適用されます。ObjectStack 14.2 以降、メンバーのベースラインには**削除**が含まれなくなったことに注意してください。レコードの削除は、ポジションで配布される権限セットを通じて、オブジェクトごとに明示的に付与しなければなりません。 + +**権限セットを持たない呼び出し元は拒否のベースラインを得ます**（ObjectStack 17.6）。権限セットをまったく解決しないリクエスト（匿名のリクエスト、または存在しないセットだけを指定するリクエスト）は、すべてのオブジェクトで `403 PERMISSION_DENIED` で拒否されます。`requiredPermissions` でゲートされたフィールドは提供されず（フィールドが `maskingRule` を宣言していればマスクされて提供されます）、そのフィールドでフィルター、並べ替え、グループ化、書き込みをすることもできません。ベースラインのセットが設定されている限り、サインインしたユーザーは影響を受けません。デフォルトの `member_default` は、彼らについて常に解決されます。 + +## ポジションを無効にする [#deactivating-a-position] + +ポジションの **Deactivate** アクションは、それが与えるものすべてを即座に取り除きます（ObjectStack 17.1）。 + +- 権限セットを何も配布しなくなり、その名前は保持者の `current_user.positions` から外れます。 +- そのポジションを受け手とする共有ルールは誰とも共有しなくなり、すでに付与していたレコードの共有は次の再調整で取り消されます。 + +無効化が止めるのはアクセスであって、宛先の指定ではありません。種類が `position` の承認者を持つ承認ステップは、無効化されたポジションの保持者に引き続き回されます。`active` の値が空のポジションは影響を受けません。数えられるのは明示的な無効化だけです。 + +> ObjectStack 17.1 より前は、このスイッチは何もしていませんでした。無効化されたポジションも付与を続けていました。それを越えてアップグレードすると、稼働中のデータでそのアクセスが取り消されるので、まだ付与を続けるべき無効化されたポジションは、アップグレードの前に再び有効にしてください。 + +## 有効期間付きの割り当て [#effective-dated-assignments] + +ポジションと権限セットの割り当ては、省略可能な `valid_from` / `valid_until` の期間（半開区間、UTC。null は無制限）を持ちます。期限切れの付与は即座に解決されなくなります。一時的な代行、契約社員、資格に結び付いたアクセスに便利です。各付与には `reason` を、委任の場合は `delegated_from` も記録できます。 + +`delegatable: true` とマークされたポジションは、その現在の保持者が、期間を区切って（将来の `valid_until` で、上限は 30 日、理由は必須）別のユーザーに自分で委任することを許します。管理のスコープを持つ権限セットを配布するポジションは、決して委任可能にはできません。 + +## 推奨されるパターン [#recommended-pattern] + +職務の形をした、小さく安定したポジションの集合を保ちます。 + +```text +Sales Manager +Sales Representative +Support Manager +Support Agent +``` + +組織図は事業単位としてモデル化します。 + +```text +Sales + ├─ EMEA + └─ AMER +Support +``` + +そして、機能のために権限セットをポジションに付けます。 + +```text +Sales Manager position + -> CRM User + -> Sales Manager Access + -> Report Viewer +``` + +こうすれば、権限が独立して変化していく間も、ポジションは安定したままです。 + +## 避けるべきこと [#avoid] + +- ユーザー 1 人ごとに 1 つのポジションを作ること +- すべての権限をすべてのポジションに重複させること +- ポジションの名前をビジネスロジックのチェックに使うこと +- ポジションで階層を作り直すこと。サブツリーの表示範囲は、事業単位と[レコードの共有](/docs/configure/permissions/record-access)の役割です +- レコードの共有のほうがより正確なのに、マネージャーのポジションを通じて広いアクセスを付与すること + +## ロールからの移行（13 より前） [#migrating-from-roles-pre-13] + +ObjectStack 12 以前に対して作成されたメタデータをアップグレードする場合： + +| 旧来 | 現在 | +|---|---| +| `sys_role` / `sys_user_role` / `sys_role_permission_set` | `sys_position` / `sys_user_position` / `sys_position_permission_set` | +| `defineRole` / `RoleSchema`（`parent` 付き） | `definePosition` / `PositionSchema`（フラット） | +| メタデータの種類 `role` または `profile` | `position` | +| 共有の受け手 `role` / `role_and_subordinates` | `position` / `unit_and_subordinates` | +| `PermissionSetSchema.isProfile` | 削除されました。`isDefault` がインストール時の推奨をマークします | + +ロールの階層は、事業単位のツリーとしてモデル化し直す必要があります。`os lint` は、`security-role-word` ルールで残っているロールの語彙を指摘します。 diff --git a/content/docs/configure/permissions/record-access.ja.mdx b/content/docs/configure/permissions/record-access.ja.mdx new file mode 100644 index 0000000..21a0570 --- /dev/null +++ b/content/docs/configure/permissions/record-access.ja.mdx @@ -0,0 +1,104 @@ +--- +title: レコードアクセス +seoTitle: "レコードアクセス：共有モデル、ルール、共有" +description: オブジェクトの権限が許した後に、ユーザーがどのレコードを見たり変更したりできるかを制御します。共有モデルのデフォルト、テナントの分離、共有ルール、レコードの共有です。 +editions: [community, cloud, enterprise] +translation: + source_sha: 7b46161549b128c59dc28ff67e96983da80e27b14b32166a87dd0fe2b00e1789 + guide_rev: 1 + mode: auto +--- + +レコードアクセスは、オブジェクトの権限が操作を許した後に、ユーザーがどの行を見たり変更したりできるかを制御します。 + +## 仕組み [#mechanisms] + +| 仕組み | 目的 | +|---|---| +| 行レベルセキュリティ | テナントまたは組織の分離を強制します | +| 共有ルール | 宣言的な条件に基づいてアクセスを付与します | +| レコードの共有 | 特定のユーザー、チーム、ポジション、事業単位、または単位とその配下にアクセスを付与します | +| 所有 / 階層 | 所有者と事業単位のツリーを通じてアクセスを付与します | + +## 共有モデルのデフォルト [#sharing-model-defaults] + +すべてのオブジェクトは、組織全体のデフォルトを設定する `sharingModel` を宣言（または継承）します：`private`、`public_read`、`public_read_write`、`controlled_by_parent`。 + +ObjectStack 13 以降、所有者のフィールドを持ち `sharingModel` を宣言していないカスタムオブジェクトのデフォルトは**非公開**です。レコードは、共有ルール、レコードの共有、またはより広いデフォルトが公開するまで、その所有者（と管理者）にだけ見えます。開いた動作に戻すには、モデルを明示的に宣言します。 + +```ts +ObjectSchema.create({ + name: 'crm_lead', + sharingModel: 'public_read_write', + fields: { + company: Field.text({ label: 'Company' }), + // … + }, +}); +``` + +13 より前のエイリアス `read`、`read_write`、`full` は削除されました。`os compile` は、`security-owd-unset` と `security-owd-alias` の lint で、未設定またはエイリアスのモデルを指摘します。 + +## デフォルトのテナント分離 [#default-tenant-isolation] + +セキュリティプラグインは、現在のユーザーのコンテキストを通じてテナントの分離を強制します。標準のプラットフォームのオブジェクトでは、通常の組織フィールドを持たないグローバルなテーブルを、デフォルトのルールが保護します。 + +顧客が実際に期待するのは次のことです。 + +```text +Users only see records that belong to their organization or records +explicitly shared with them. +``` + +## 共有ルール [#sharing-rules] + +共有ルールは、繰り返し適用される業務上のポリシーに使います。 + +- すべての地域マネージャーは、自分の地域の取引先を読める +- サポートマネージャーは、エスカレーションされたケースを見られる +- 財務は、承認済みの請求書を読める +- 監査担当者は、監査レビューのタグが付いたレコードを読める + +ルールはフィールドの値に対する CEL の `condition` で、作成時に行のフィルターにコンパイルされます。一致したレコードは、解決された受け手（ユーザー、チーム、ポジション、事業単位、または単位とその配下）に対する `sys_record_share` の付与を具体化します。作成できる形式は `criteria` ルールだけです。 + +### どちらのスイッチも安全側に倒れる [#both-switches-fail-closed] + +読み手が当然そう思ってよいことで、ObjectStack 17.0 以降にようやく真になった 2 つのことです。 + +- **条件のない共有ルールは何も共有しません。** 条件の述語なしに保存されたルールは、以前は*オブジェクトのすべてのレコード*（空のフィルター）として評価されていたので、検証されない書き込み経路を通った入力ミスが、黙ってテーブル全体を公開していました。すべてに一致する条件を書くことは今は拒否され、評価器は空の条件を**何にも**一致しないものとして扱います。 +- **`enabled: false` の RLS ポリシーは無効です。** 以前は、オフにしたポリシーも OR 分岐の付与を加え続けていたので、ポリシーをオフにしてもアクセスは取り除かれませんでした。今は、無効なポリシーは単に評価されません。 + +以前のリリースでアクセスを監査し、「このルールは何も付与していない」や「このポリシーはオフだ」と結論づけた場合は、[explain エンジン](/docs/configure/permissions#diagnose--audit)を再実行する価値があります。答えは、メタデータが示していたより広かったかもしれません。 + +## 行レベルセキュリティは強制できないものを拒否する [#row-level-security-refuses-what-it-cannot-enforce] + +ObjectStack 17.5 以降、RLS ポリシーは書かれているとおりに正確に絞り込むか、拒否するかのどちらかです。 + +- **`check` のないポリシーは、その `using` で書き込みをゲートします。** `check` のデフォルトは `using` であると常に記載されていましたが、書き込みに適用されていたのは `check` を宣言したポリシーだけだったので、ユーザーは読み戻せない行を書き込めていました。単一行の挿入や ID による更新で、その結果が適用されるすべての書き込みポリシーの `using` の外にある場合、今は `403 PERMISSION_DENIED` で応答します。書き込みを読み取りの範囲の外に置くことを意図したポリシーは、それを認める `check` を宣言しなければなりません。 +- **強制できない述語は拒否します。** フィールドをリストと比較する（`record.status != ['closed', 'archived']`）、`current_user.id` ではなく素の `current_user` と比較する、またはオブジェクトが宣言していないフィールドを指定すると、拒否するために書いたはずの行や書き込みそのものを認めてしまう可能性がありました。そのようなポリシーは今は安全側に倒れて失敗します。読み取りは行を返さず、書き込みは `403` で応答します。 +- **書き込みは保存される行で判定されます。** `check` と組織の壁は、`beforeInsert` / `beforeUpdate` のフックが実行された後の、エンジンが保存するとおりの行を見ます。 + +`os validate` は、出荷する前にこれらの形を報告し（`rls-predicate-unenforceable`、`rls-predicate-unknown-field`）、メタデータの保存の入口は、それを持つ権限セットを拒否します（`422 INVALID_METADATA`）。 + +## レコードの共有 [#record-shares] + +レコードの共有は例外のために使います。 + +- 1 件の商談を専門家と共有する +- エスカレーションの間、一時的なアクセスを付与する +- 外部の連携に特定のレコードへのアクセスを与える + +## 表示範囲のトラブルシューティング [#troubleshooting-visibility] + +ユーザーがレコードを見られないときは、次の順で確認します。 + +1. ユーザーは認証されていて、想定した組織にいるか？ +2. ユーザーはオブジェクトの `read` 権限を持っているか？ +3. オブジェクトの `sharingModel` は何か（ObjectStack 13 以降、カスタムオブジェクトのデフォルトは `private`）？ +4. 行レベルセキュリティはそのレコードを許しているか？ +5. 適用されるべき共有ルールはあるか？ +6. 直接のレコードの共有はあるか？ +7. レコードは、想定した事業単位のサブツリーにいるユーザーが所有しているか？ +8. ユーザーは正しいプロジェクト / ホスト名を見ているか？ + +[explain エンジン](/docs/configure/permissions#diagnose--audit)は、これらすべてに 1 回の呼び出しで答えます。各層の判定と、どの付与（または欠けている付与）が結果を決めたかを報告します。