コンテンツにスキップ
Authrim

アクセストレース

概要

アクセストレースAPIは、アプリケーション内で行われた権限チェックの監査ログと統計情報を提供します。どのユーザーがどのリソースにアクセスしようとしたか、その結果が許可/拒否されたかを追跡できます。

エンドポイント一覧

メソッドエンドポイント説明
GET/api/admin/access-traceアクセストレース一覧取得
GET/api/admin/access-trace/:idアクセストレース詳細取得
GET/api/admin/access-trace/statsアクセストレース統計取得
GET/api/admin/access-trace/timelineタイムラインデータ取得

アクセストレース一覧取得

権限チェックの履歴を取得します。

エンドポイント

GET /api/admin/access-trace

クエリパラメータ

パラメータ型必須説明
limitinteger-取得件数（デフォルト: 50、最大: 100）
cursorstring-ページネーションカーソル
user_idstring-ユーザーIDでフィルタ
resourcestring-リソースでフィルタ
actionstring-アクションでフィルタ
decisionstring-結果でフィルタ（allow, deny）
start_datestring-開始日時（ISO 8601形式）
end_datestring-終了日時（ISO 8601形式）

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/access-trace?decision=deny&limit=20" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "items": [
    {
      "id": "trace_abc123",
      "timestamp": "2024-01-22T10:30:00Z",
      "user_id": "usr_xyz789",
      "user_email": "[email protected]",
      "resource": "documents:report_2024",
      "action": "write",
      "decision": "deny",
      "reason": "Insufficient permissions",
      "client_id": "client_app001",
      "ip_address": "203.0.113.1",
      "duration_ms": 5
    },
    {
      "id": "trace_def456",
      "timestamp": "2024-01-22T10:25:00Z",
      "user_id": "usr_abc123",
      "user_email": "[email protected]",
      "resource": "settings:security",
      "action": "read",
      "decision": "allow",
      "client_id": "client_app001",
      "ip_address": "203.0.113.2",
      "duration_ms": 3
    }
  ],
  "total": 1500,
  "cursor": "eyJpZCI6InRyYWNlX2RlZjQ1NiJ9"
}

アクセストレース詳細取得

指定されたアクセストレースの詳細情報を取得します。

エンドポイント

GET /api/admin/access-trace/:id

パスパラメータ

パラメータ型必須説明
idstring○アクセストレースID

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/access-trace/trace_abc123" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "id": "trace_abc123",
  "timestamp": "2024-01-22T10:30:00Z",
  "user": {
    "id": "usr_xyz789",
    "email": "[email protected]",
    "name": "山田 太郎",
    "roles": ["viewer"]
  },
  "resource": "documents:report_2024",
  "action": "write",
  "decision": "deny",
  "reason": "Insufficient permissions",
  "evaluation": {
    "type": "rbac",
    "checked_permissions": ["documents:write"],
    "user_permissions": ["documents:read"],
    "missing_permissions": ["documents:write"]
  },
  "policies_evaluated": [
    {
      "id": "policy_default",
      "name": "default-viewer-policy",
      "effect": "allow",
      "matched": false,
      "reason": "Action 'write' not in allowed actions"
    }
  ],
  "context": {
    "client_id": "client_app001",
    "client_name": "My App",
    "ip_address": "203.0.113.1",
    "user_agent": "Mozilla/5.0...",
    "session_id": "sess_xyz789",
    "request_id": "req_abc123"
  },
  "duration_ms": 5
}

アクセストレース統計取得

アクセスチェックの統計情報を取得します。

エンドポイント

GET /api/admin/access-trace/stats

クエリパラメータ

パラメータ型必須説明
start_datestring-開始日時（ISO 8601形式）
end_datestring-終了日時（ISO 8601形式）
group_bystring-グルーピング（user, resource, action, decision）

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/access-trace/stats?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "summary": {
    "total_checks": 125000,
    "allowed": 120000,
    "denied": 5000,
    "allow_rate": 96.0,
    "avg_duration_ms": 4.5
  },
  "by_decision": {
    "allow": 120000,
    "deny": 5000
  },
  "by_resource": [
    {
      "resource": "documents:*",
      "total": 50000,
      "allowed": 48000,
      "denied": 2000
    },
    {
      "resource": "settings:*",
      "total": 30000,
      "allowed": 29500,
      "denied": 500
    }
  ],
  "by_action": [
    {
      "action": "read",
      "total": 80000,
      "allowed": 79000,
      "denied": 1000
    },
    {
      "action": "write",
      "total": 35000,
      "allowed": 32000,
      "denied": 3000
    }
  ],
  "top_denied_users": [
    {
      "user_id": "usr_xyz789",
      "user_email": "[email protected]",
      "denied_count": 500
    }
  ],
  "top_denied_resources": [
    {
      "resource": "admin:settings",
      "denied_count": 1500
    }
  ]
}

タイムラインデータ取得

時系列のアクセスチェックデータを取得します（チャート表示用）。

エンドポイント

GET /api/admin/access-trace/timeline

クエリパラメータ

パラメータ型必須説明
start_datestring○開始日時（ISO 8601形式）
end_datestring○終了日時（ISO 8601形式）
intervalstring-間隔（hour, day, week、デフォルト: day）
decisionstring-結果でフィルタ

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/access-trace/timeline?start_date=2024-01-15&end_date=2024-01-22&interval=day" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "interval": "day",
  "data": [
    {
      "timestamp": "2024-01-15T00:00:00Z",
      "total": 18000,
      "allowed": 17500,
      "denied": 500,
      "avg_duration_ms": 4.2
    },
    {
      "timestamp": "2024-01-16T00:00:00Z",
      "total": 19500,
      "allowed": 19000,
      "denied": 500,
      "avg_duration_ms": 4.5
    },
    {
      "timestamp": "2024-01-17T00:00:00Z",
      "total": 17000,
      "allowed": 16200,
      "denied": 800,
      "avg_duration_ms": 4.8
    },
    {
      "timestamp": "2024-01-18T00:00:00Z",
      "total": 20000,
      "allowed": 19500,
      "denied": 500,
      "avg_duration_ms": 4.3
    },
    {
      "timestamp": "2024-01-19T00:00:00Z",
      "total": 12000,
      "allowed": 11800,
      "denied": 200,
      "avg_duration_ms": 3.9
    },
    {
      "timestamp": "2024-01-20T00:00:00Z",
      "total": 8000,
      "allowed": 7900,
      "denied": 100,
      "avg_duration_ms": 3.5
    },
    {
      "timestamp": "2024-01-21T00:00:00Z",
      "total": 10000,
      "allowed": 9800,
      "denied": 200,
      "avg_duration_ms": 3.7
    },
    {
      "timestamp": "2024-01-22T00:00:00Z",
      "total": 21000,
      "allowed": 20300,
      "denied": 700,
      "avg_duration_ms": 4.6
    }
  ]
}

アクセストレースの活用例

セキュリティ監視

拒否されたアクセスを監視して、不正なアクセス試行を検出します。

Terminal window
# 過去1時間の拒否されたアクセスを取得
curl -X GET "https://{tenant-domain}/api/admin/access-trace?decision=deny&start_date=$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Authorization: Bearer {token}"

権限の最適化

頻繁に拒否されているリソースを特定し、必要に応じて権限を見直します。

Terminal window
# 統計から最も拒否が多いリソースを確認
curl -X GET "https://{tenant-domain}/api/admin/access-trace/stats?group_by=resource" \
  -H "Authorization: Bearer {token}"

パフォーマンス分析

権限チェックの応答時間を監視し、ボトルネックを特定します。

Terminal window
# タイムラインで応答時間の推移を確認
curl -X GET "https://{tenant-domain}/api/admin/access-trace/timeline?start_date=2024-01-01&end_date=2024-01-31&interval=day" \
  -H "Authorization: Bearer {token}"

データ保持

アクセストレースのデータは、テナントのデータ保持ポリシーに従って保持されます。デフォルトの保持期間は30日です。コンプライアンスAPIで保持期間を変更できます。