メインコンテンツへスキップ

APIキー認可フロー

このドキュメントでは、サードパーティ製アプリケーション向けのセルフサービス API キー作成フローについて説明します。

概要​

アプリケーションは、ユーザーを特別な認可ページにリダイレクトすることで Unraid サーバーへの API アクセスを要求できます。ユーザーはそこで要求された権限を確認し、ワンクリックで API キーを作成できます。

フロー​

  1. アプリケーションが要求を開始: アプリはユーザーを次のページにリダイレクトします:

    https://[unraid-server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123

  2. ユーザー認証: まだログインしていない場合、ユーザーはまずログイン画面にリダイレクトされます（標準のUnraid認証）。

  3. 同意画面: ユーザーに表示される内容:

    • アプリケーション名と説明
    • 要求された権限（特定のスコープを承認/拒否するためのチェックボックス付き）
    • API キー名フィールド（事前入力済み）
    • Authorize および Cancel ボタン

  4. API キーの作成: 認可後:

    • APIキーは承認済みのスコープで作成されます。
    • キーはユーザーに表示されます。
    • redirect_uri が指定されている場合、ユーザーはキーとともに元の場所にリダイレクトされます。

  5. コールバック: アプリは API キーを受け取ります:

    https://myapp.com/callback?api_key=xxx&state=abc123

クエリパラメーター​

  • name（必須）: 要求元アプリケーションの名前
  • description（任意）: アプリケーションの説明
  • scopes（必須）: カンマ区切りの要求スコープ一覧
  • redirect_uri（任意）: 認可後にリダイレクトする URL
  • state（任意）: 状態を維持するための不透明な値

スコープ形式​

スコープは resource:action のパターンに従います。例としては、Docker への読み取りアクセスを表す docker:read、VM へのフルアクセスを表す vm:*、システムへの更新アクセスを表す system:update、ビューアー権限を表す role:viewer、管理者権限を表す role:admin があります。

利用可能なリソースには docker、vm、system、share、user、network、disk などがあります。利用可能なアクションは create、read、update、delete、またはすべてを表す * です。

リダイレクトURIは HTTPS を使用する必要があります（開発時の localhost を除く）。ユーザーは各権限を明示的に承認し、このフローは既存の Unraid 認証セッションを使用します。APIキーは一度だけ表示され、安全に保存する必要があります。

統合例​

// JavaScript example
const unraidServer = 'tower.local';
const appName = 'My Docker Manager';
const scopes = 'docker:*,system:read';
const redirectUri = 'https://myapp.com/unraid/callback';
const state = generateRandomState();

// Store state for verification
sessionStorage.setItem('oauth_state', state);

// Redirect user to authorization page
window.location.href =
    `https://${unraidServer}/ApiKeyAuthorize?` +
    `name=${encodeURIComponent(appName)}&` +
    `scopes=${encodeURIComponent(scopes)}&` +
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +
    `state=${encodeURIComponent(state)}`;

// Handle callback
const urlParams = new URLSearchParams(window.location.search);
const apiKey = urlParams.get('api_key');
const returnedState = urlParams.get('state');

if (returnedState === sessionStorage.getItem('oauth_state')) {
    // Save API key securely
    saveApiKey(apiKey);
}