前回は事前準備ガイドとして、Microsoft Entra 管理センターでのアプリケーション登録と、Laravel プロジェクトの設定を解説しました。
今回は続編として実用編をリクエストクエリの例をいくつか紹介し、解説していきます。
前回のおさらい – 要件
- ユーザーのカレンダー情報をLaravelプロジェクトのDBに保存し同期を行う
- 保存用のDBは設定済み
- 専用のCRUDページは作成済み
- Graph APIへのアクセス許可レベルはアプリケーション委任レベルとする
- LaravelのGraph API用クラスライブラリはKiota(microsoft-graph Packegeに同梱)を利用する
今回のポイント
- 委任レベルによるエンドポイントの指定方法の違いを理解する
- ユーザーの特定方法を理解する
委任レベルによるエンドポイントの制限
Graph API を利用するに当たって『委任レベル』は非常に重要な要素です。
また、『委任レベル』によっては利用できるエンドポイントが限定されます。
「アプリケーション委任」の場合はユーザー不要な認証のため、エンドポイント[/me]の利用は出来ません、[/users/{id | principalName}]に限定されます。
アプリケーション委任 = アプリケーション認証 とは
クライアント シークレットまたはクライアント証明書を発行し認証を行う方法で、アプリケーション間でパスワードレスの認証が出来る認証方法で、ユーザーのプロファイルをクライアントが把握できない通信です。
ユーザー委任 ≒ コード認証 とは
ユーザーがアカウントを利用して認証することで、クライアントはユーザーのプロファイルを常に持った状態で通信を行います。
今回の委任レベル「アプリケーション委任」はセキュリティの観点からは最も低いレベルの委任です。
ユーザーIDさえ判ってしまえば、アプリケーションを利用するプログラムソースにアクセスできるユーザーは簡単に他人に成りすますことが可能となります。もし、プロジェクトのUIからユーザーIDが参照できるようであれば、比較的容易に他人に成りすますことが可能となります。
要件の変更申請が可能な場合は、なるべく「ユーザー委任」を推奨します。但し、ユーザー委任を利用するには、Microsoft Entraに登録したアプリにプラットフォームを追加してリダイレクトURIの設定が必須となりますので、リダイレクトURIとしてCallBack関数を定義してルーティングするなど追加コーディングが必要になります。
アプリケーション委任におけるEntraユーザーの特定方法
Laravel ログインユーザーのEMailがEntraと一致する場合
Emailを指定してユーザー情報を取得することが可能です。
Entra では Email = principalName というルールがありますので、Emailを指定することでユーザー固有の情報を取得できます。
Laravel ログインユーザーのEMailがEntraと不一致な場合
EntraユーザーのEMailが不明な場合
Entraユーザーの特定は非常に困難になります。
Emailは一意であることが保証された値であるため、Emailを検索キーに利用したユーザーの特定は容易ですが、表示名[displayName],名[givenName],姓[surname]などは一意である保証はなく単体での検索には使用できません。また、所属[department]などと組み合わせた検索も同姓同名の人が同じ部署に所属する可能性があるため、複合検索キーとしては不向きです。
組織の従業員属性を精査し、適切な検索条件を設定することが重要になります。
検索条件として指定できる属性を特定するにはユーザープロパティ(公式)を参考にしてください。
検索で得た結果から[id]または[principalName]を取得し、エンドポイントに適用します。
データベース上にEntra ID または userPrincipalNameを保持している場合
保持するデータを利用してユーザー情報を取得することが可能です。
エンドポイントの例
エンドポイントの決定にはいくつかの参考サイトがありますが、Microsoft Graph Explorがおすすめです。
多くのサンプルとコードスニペットの自動生成機能が備わっているため、実装したいリクエストを短時間で生成可能です。
必要なアクセス許可は[Modify permissions]タブで確認できます。
POST methodで必要になるRequestBodyの生成方法などは、Microsoft Graph REST API v1.0 エンドポイント リファレンスを参照すると、解決出来ます。
例1：ユーザーの検索
基本的なユーザープロファイルを取得するためには、アクセス許可として[User.ReadBasic.All]がアプリケーションに対して委任されている必要があります。また、詳細なプロファイルには[Uesr.Raed.All]が必要です。
誤ってユーザープロファイルを書き換えない様に[User.Write]アクセス許可は与えないでください。
<!-- cURL ユーザー検索エンドポイントの例 -->
Get https://graph.microsoft.com/users/?$filter=displayName eq 'displayName'// php ユーザー検索エンドポイントの例
use Microsoft\Graph\Generated\Models\UserCollectionResponse;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$displayName = 'search_displayName';
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = ['ConsistencyLevel' => 'eventual',];
$requestConfiguration->headers = $headers;
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = '"displayName:'.$displayName.'"';
$queryParameters->select = $selectQueryParameters;
$requestConfiguration->queryParameters = ['id','displayName','userPrincipalName'];
$response = $client->users()->get($requestConfiguration )->wait();例2：ユーザープロファイルの取得
<!-- cURL ユーザープロファイル取得エンドポイントの例 -->
Get https://graph.microsoft.com/users/{your_email}/?queryParameters// php ユーザープロファイル取得エンドポイントの例
use Microsoft\Graph\Generated\Models\User;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;
$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ['id','displayName','userPrincipalName'];
$requestConfiguration->queryParameters = $queryParameters;
$response = $client->users()->byUserId('your_userPrincipalName' | 'your_email')
->get($requestConfiguration )->wait();例3：ユーザーのスケジュール取得
ユーザーのスケジュールを取得するためには、アクセス許可として[Calendars.Read]がアプリケーションに対して委任されている必要があります。
<!-- cURL スケジュール取得エンドポイントの例 -->
Get https://graph.microsoft.com/users/{your_email}/events?queryParameters// php スケジュール取得エンドポイントの例
use Microsoft\Graph\Generated\Models\EventCollectionResponse;
use Microsoft\Graph\Generated\Users\Item\Events\EventsRequestBuilderGetRequestConfiguration;
use Microsoft\Graph\Generated\Users\Item\Events\EventsRequestBuilderGetQueryParameters;
$configuration = new EventsRequestBuilderGetRequestConfiguration();
$configuration->queryParameters = new EventsRequestBuilderGetQueryParameters();
/*
ToDo Set QueryParameters
*/
$response = $client->users()->byUserId('your_userPrincipalName' | 'your_email')->events()
->get($configuration)->wait();例に挙げたソースコードを関数化するなどして、コントローラーに追加すれば利用が容易になるはずです。
編集後記
Microsoft EntraとLaravelの連携技術について解説しています。前回の準備編に続き、今回は実用編としてリクエストクエリの例を紹介。特に、委任レベルの違いによるエンドポイントの指定方法やユーザーの特定方法について詳しく説明しています。また、Microsoft Graph Explorerを利用したエンドポイントの決定方法や、ユーザー検索、プロファイル取得、スケジュール取得の具体例も示しています。
今回は3例に留めましたが、もしご自身で実装が難しく「例を挙げてほしい」などありましたら、お気軽にコメント投稿お願いします。
この記事を書いた人
