Microsoft Viva API のアプリ専用認証を使いこなす

By Mirko Peters · 2026-08-28

「Unauthorized」や「Forbidden」というエラーに悩まされながら、Microsoft Viva 向けの自動メンテナンススクリプトを作ろうとして何時間も費やした経験があるなら、あなただけではありません…

Automatically translated with AI from the original post. Read the English original

「Unauthorized」や「Forbidden」というエラーに悩まされながら、Microsoft Viva 向けの自動メンテナンススクリプトを作ろうとして何時間も費やした経験があるなら、あなただけではありません。最近の Microsoft 365 環境の多くは、「とりあえず有効にして、あとはユーザーが使い方を覚えてくれるのを待つ」という導入段階で足踏みしています。真の運用規模を実現するには、プラットフォームの所有者や管理者は管理用のユーザーインターフェイスから離れ、API に本格的に取り組む必要があります。ただし、無人での自動化を実現するには、堅牢なアプリケーション専用認証、正確なリクエスト処理、そして確実なデータペイロードの構造化が欠かせません。本ガイドでは、Azure Key Vault に安全に保管した証明書資格情報を使ってセキュアなサービスプリンシパルを構成する方法、環境に必要なリソース固有のスコープを正確に要求する方法、そしてベテラン開発者のようにトークンのクレームを扱う方法を順を追って解説します。

これらのアーキテクチャ戦略をさらに深く理解し、実際の導入事例を知りたい場合は、関連するポッドキャストのエピソード Automate Viva Connections, Topics, Learning, and News もぜひお聴きください。では、Viva 自動化の壁を乗り越えるための具体的な手順を見ていきましょう。

認証の壁を乗り越える

自動化スクリプトを作成する際に最もつまずきやすいのは、公式ドキュメントに従ったはずなのに「Unauthorized」の応答が返ってくることです。実際のところ、Microsoft Viva のエコシステムは Microsoft Graph と製品固有のエンドポイントの組み合わせで構成されており、それぞれのアクセス許可スコープも大きく異なる場合があります。

最小限で安全、かつ完全にアプリ専用のセットアップを構築するには、厳格な ID 管理の原則に従う必要があります。

• サービスプリンシパルとして機能する専用の Entra ID アプリケーションを登録します。
• 脆弱な静的クライアントシークレットよりも、Azure Key Vault に保存された証明書資格情報を常に優先してください。
• 必要なアプリケーションのアクセス許可のみを付与します。たとえば、Viva Topics では通常 Topics.ReadWrite.All が必要です。Viva Learning には LearningContent.ReadWrite.All と LearningProvider.ReadWrite.All が必要です。Connections や SharePoint ニュースは、対象サイトのアクセス許可と合わせて Sites.ReadWrite.All に大きく依存します。
• 要求したスコープに対して、管理者の同意を明示的に与えてください。
• 条件付きアクセスポリシーには、サービスプリンシパルを除外するか、信頼できる自動化ネットワークからの非対話型サービスプリンシパルを安全に許可する専用ポリシーを作成して対応します。
• トークンを要求する際は、呼び出し先のリソースに対して /.default スコープを明示的に指定します。汎用の Graph トークンを製品固有のリソースエンドポイントに再利用しないでください。

問題が発生した場合は、簡単な認証のトラブルシューティングチェックリストを確認してください。トークンのオーディエンス（aud）クレームが対象エンドポイントと一致しているかを確認し、委任されたアクセス許可ではなくアプリケーションのアクセス許可を使用しているかを確認し、同意が実際に適用されているかを確認し、証明書が有効であり、更新アラートが設定されているかを確認してください。さらに、実行のたびにトークンのクレームをログに記録してください。

カスタムナレッジ：Viva Topics の自動化

Viva Topics を扱う際によくある障害パターンは、API から 201 Created の成功応答が返ってくるのに、トピックがユーザーインターフェイスに一切表示されないというものです。これはほぼ常に、必須フィールドの欠落、下書きモードのまま残った不適切な公開状態、またはメタデータが単に不十分であることが原因です。

ペイロードには、明確なタイトル、十分な概要または説明、代替名や頭字語、ファイル・ページ・人物を指す信頼できる参照、「公開済み」という状態の指定、そしてトピックの組織的な信頼性を高めるための所有者やエキスパートの割り当てなど、重要な要素を必ず含めてください。

これを効率よく拡張するには、エンタープライズ Wiki、SharePoint リスト、プロジェクトレジストリなど、外部の信頼できる情報源を確認し、そのデータを構造化された JSON に変換してください。並列処理の度合いを制御したバッチ処理の戦略を実装し、HTTP 429 のレート制限応答には、必ず Retry-After ヘッダーに従って対応してください。外部キーに基づいてレコードをアップサートし、重複を防ぐ冪等性を実装してください。そのうえで、トピックが公開パイプラインを確実に通過したことを確認するため、必ず公開後の検証クエリを実行してください。

ナレッジ管理の運用ベストプラクティス

自動公開ジョブを実行する際は、ログ記録が非常に重要です。受信したリクエストと、対応するレスポンスの相関 ID を必ず記録してください。4xx ステータスコードはデータまたはアクセス許可の検証に関する問題として扱い、5xx エラーと 429 のレート制限は、専用の指数バックオフおよび再試行キューに振り分けてください。

LMS のサイロから Viva Learning へ

組織では、学習コンテンツが複数の異なるシステムに分散してしまうことがよくあります。Viva Learning の自動化における主な目的は、外部のコースを一括で公開し、従業員が Viva の中の一か所だけで検索できるようにすることです。

スムーズに取り込むには、learningContent のペイロードに、安定した externalId、わかりやすいタイトル、内容の説明となる概要、有効な webUrl、有効な thumbnailUrl、ISO 8601 形式の所要時間、関連するスキルまたはタグ、そして正しいロケールを含める必要があります。従来の学習管理システム (LMS) の CSV エクスポートを、厳密に検証された JSON にマッピングすることは必須です。

バッチ処理のパイプラインは、PowerShell で作成する場合でも、Azure Functions としてデプロイする場合でも、ソースデータの取り込み、必須列の検証、空の値に対する組み込みのガードレールを備えた JSON ペイロードの作成、適切なトークンを使用した POST リクエストの実行、そして計算された待機間隔またはバックオフの手順を組み込む必要があります。成功しなかった HTTP ステータスコードは、必ず行番号と理由とともに記録し、自動修復用の再試行リストを作成してください。

Viva Connections ニュースの自動化

手動によるコミュニケーション投稿は、重要な公開時間帯を逃したり、適切な対象者セグメントに届かなかったり、不正な JSON ペイロードによって完全に失敗したりすることがよくあります。プログラムによるカード生成に切り替えることで、対象を絞ったニュースを確実に配信できるようになります。

信頼性の高いニュース投稿の構成要素として、タイトルと概要の整合性、明示的に定義された作成者、Microsoft Entra ID のグループ ID の配列として渡される対象者、検証済みの画像 URL、Teams アプリケーション内で直接開くディープリンク、そして設定された優先度と有効期限が必要です。すべてのプロパティ名は正しい camelCase で記述し、送信前に検証されていることを確認してください。

投稿を現地の地域のタイムゾーンに合わせてスケジュールし、対象者ごとにバッチをグループ化することで、これらのアセットを大規模に配信できます。400 Bad Request の例外が発生した場合はエラー応答の本文を解析し、すぐに修正して再送信できるようにしてください。投稿 ID、対象者の規模、配信ステータスを詳細に記録したテレメトリを維持してください。

本番環境レベルのパターン

堅牢な自動化を構築するには、エンタープライズ級のエンジニアリングパターンを採用する必要があります。ローカルマシン上での手動によるスクリプト実行には頼らないでください。代わりに、GitHub Actions または Azure DevOps を使用して自動化パイプラインを構築、テスト、デプロイしてください。運用上のシークレットはスクリプトにハードコードせず、Azure Key Vault の参照として安全に保存してください。

オブザーバビリティは極めて重要です。自動化ジョブを Application Insights または Log Analytics と統合し、実行の成功、レイテンシの急上昇、レート制限によるスロットリングのイベントを追跡してください。ランダムなジッターを伴う指数バックオフのアルゴリズムを実装し、Retry-After ヘッダーには必ず従い、冪等性キーを利用して、失敗したジョブの再試行によってコンテンツが重複して生成されることがないようにしてください。

よくある落とし穴と迅速な解決策

経験豊富なエンジニアであっても、API の微妙な要件でつまずくことがあります。ここでは、自動化でよくある罠を素早く解決する方法を紹介します。

• コードに問題がないのに 401 または 403 エラーが発生する場合、通常はトークンの対象 (audience) が対象の API リソースと一致していないことを意味します。呼び出すエンドポイントに合わせて、必ず新しいトークンを取得してください。
• トピックの作成には成功したのにユーザー インターフェイスに表示されない場合は、state プロパティが下書きのまま残っておらず、公開済みとしてマークされているかを確認してください。また、メタデータが少なすぎないかも確認してください。
• 手動でアップロードしたラーニング コンテンツが消えてしまう場合、多くはデータ型の不一致か、スキーマのペイロードで必須フィールドが欠けていることが原因です。
• Viva Connections のニュース投稿が表示されない場合は、audience プロパティが配列ではなく文字列として誤った形式で指定されているか、画像リンクが無効であったり、概要が長すぎたりすることが多くあります。
• ジョブが大量にランダムで失敗する場合は、レート制限に抵触していることがはっきりと示されています。バッチ サイズを小さくし、適切なバックオフ処理を組み込んでください。

効果を証明するための KPI

Microsoft Viva プラットフォームの自動化に投じたエンジニアリング作業を正当化するには、明確な重要業績評価指標（KPI）を追跡する必要があります。CSV の生成から公開までの時間（公開所要時間）を測定します。機能ごとに 100 回の API 呼び出しあたりの成功率を監視し、バックオフ処理の導入前後で 429 および 5xx のスロットリング エラー率を確認します。会社のプロジェクトや頭字語のうち、有効なライブ トピックがあるものの割合を算出して、トピックのカバー率を評価します。ラーニング カタログの完全性は LMS のマスター データと比較し、Viva Connections の配信指標として、期限内公開率と総閲覧対象者数（リーチ）を測定します。

クイック スタート（今週中に実施）

今週から実際に取り組む場合は、次の簡単な展開計画に従ってください。

1. 証明書をベースとするサービス プリンシパルを作成し、必要最小限のアプリケーション アクセス許可のみを付与したうえで、管理者による明示的な同意を取得します。
2. Azure Key Vault からシークレットを安全に取得するように構成した、軽量の Azure Functions または PowerShell の自動化スクリプトを用意します。
3. 1 つのワークフローを端から端まで自動化します。たとえば、25 件の Viva トピックをまとめて公開し、エラー処理と再試行、公開後の検証チェックを含めます。
4. ログ記録を組み込み、Application Insights を使用して基本的な監視ダッシュボードを作成します。
5. 運用手順書を文書化し、サポート窓口を定義したうえで、自動化ジョブが無人で実行されるようにスケジュールを設定します。

手作業による入力から離れ、証明書によるアプリ専用認証に裏付けられた堅牢な API 自動化を採用することで、Microsoft Viva の環境を生きた企業プラットフォームへと発展させられます。さらに詳しい解説、専門的なヒント、アーキテクチャの解説については、ポッドキャスト エピソード全編 Automate Viva Connections, Topics, Learning, and News をご覧ください。