テーマ
認可の仕組みとAPI上の挙動
acomo APIで権限がどのように評価され、業務ユーザー向けAPIと管理者向けAPIで応答がどう変わるかを説明します。
対象読者
カスタムアプリや外部システムからacomo APIを呼び出す開発者
3つの認可
| 認可 | 決めること | 主な設定場所 |
|---|---|---|
| システム実行ポリシー | APIの対象に対して参照、書き込み、管理、削除、実行ができるか | ユーザーに付与されたロール |
| アクションポリシー | モデルを開始できるか、現在のノードで提出・承認・却下などを実行できるか | モデルの開始ノード、各タスク |
| データアクセスポリシー | 現在のノードで各データ項目を読み込み・書き込みできるか | モデルのノードとデータ項目の組み合わせ |
Engine APIでは、エンドポイントに設定された認可をすべて満たす必要があります。たとえば提出には、Engine:execute、現在のノードでの提出権限、変更する項目への書き込み権限が必要です。いずれか1つでも満たさなければ403になります。
Client Credentialsを使う場合、システム実行ポリシーはアクセストークンのスコープと、そのユーザーに付与されたロールの両方で評価されます。
Engine APIでデータを更新する
開始、保存、提出、承認、却下で送るデータは、データスキーマのキーをリクエストボディのトップレベルに置きます。
json
{
"amount": 12800,
"approverComment": "内容を確認しました"
}書き込み権限は、送信したキーの有無だけではなく、現在値との差分に対して評価されます。
- 書き込み可能な項目を変更すると更新できます。
- 読み込みのみの項目を別の値へ変更すると、リクエスト全体が403になり、データは更新されません。
- 読み込みのみの項目を現在と同じ値で送っても、実質的な変更ではないため拒否されません。
- 送信値が正規化後の現在値と同じになる場合も、差分がなければ書き込みとは扱われません。
同値送信が許可されても、その項目を書き込めるようになったわけではありません。クライアントは原則として、利用者が変更した項目だけを送ってください。
読み取りは項目をフィルタする
業務ユーザー向けのMyProcess APIは、現在のノードのデータアクセスポリシーを使ってdataを絞り込みます。
readまたはwriteの項目は応答に含まれます。- 権限なしの項目は
dataから除外されます。 - 読み取り権限のない項目があることだけを理由に、レスポンス全体が403になるわけではありません。
- 並列処理で現在ノードが複数ある場合、いずれかの現在ノードで読み込める項目が応答に含まれます。
プロセス自体の表示対象も絞り込まれます。GET /my/processesは、利用者が過去に操作したか、現在操作できるプロセスを返します。actioned=trueとpermitted=trueを同時に指定した場合は、両方の条件を満たすプロセスだけが返ります。
業務ユーザー向けAPIと管理者向けAPI
| API | 用途 | システム実行ポリシー | モデルポリシーによる絞り込み |
|---|---|---|---|
MyProcess API /my/processes | 自分が関与・操作できるプロセスの取得 | ログイン済みユーザーが利用可能 | プロセスとdataを利用者向けに絞り込む |
Engine API /engine | 開始、保存、提出、承認、却下、取り戻し | Engine:execute | アクションポリシーと、更新時のデータアクセスポリシーを適用 |
Process API /processes | 管理者による全体の参照・管理 | 参照はProcess:read、更新・削除はProcess:write | MyProcess APIの利用者向けフィルタは適用しない |
業務アプリではMyProcess APIとEngine APIを使用します。管理者向けのProcess APIへ切り替えて権限エラーを回避しないでください。Process APIは、テナント全体のプロセス情報を扱う権限を持つ管理機能向けです。
操作ボタンを表示する前に、getProcessWithNodeActionsなどMyProcess APIが返すnodeActionsを確認します。フロントエンドで条件式を独自に再評価せず、サーバーの判定結果を使用してください。
401と403を切り分ける
| ステータス | 意味 | 主な確認点 |
|---|---|---|
| 401 Unauthorized | 認証を完了できない | Bearerトークンの未設定・期限切れ・失効、x-tenant-idとの不一致 |
| 403 Forbidden | 認証済みだが、必要な認可を満たさない | システム実行ポリシー、アクセストークンのスコープ、アクションポリシー、データアクセスポリシー |
403のときは、製品の「API」でOperation IDを検索し、「システム実行ポリシー」を確認します。Engine APIでは、続けて現在ノードのアクションポリシーと、変更した各項目のデータアクセスポリシーを確認してください。