TeamsBotでユーザコンテキストを取得する

背景

Bot Frameworkを利用したチャットボットやアプリケーションで、ユーザごとのコンテキスト情報（氏名、メールアドレス、所属など）を取得したいケースは多くあります。
本記事では、Bot FrameworkのTurnContextから取得できるaadObjectIdをキーとして、Microsoft Graph APIを用いてユーザごとのコンテキスト情報を取得する方法をまとめます。

環境

項目	バージョン
OS	Windows11 Pro
ランタイム	Node.js v22.14.0
主要ライブラリ	"@azure/identity"=="4.8.0", "@microsoft/microsoft-graph-client"==3.0.7", "@microsoft/agents-hosting"=="^0.2.14",

事前準備

1. Entra IDにアプリの登録

ユーザコンテキストを取得するにあたり、User.Read.Allのアクセス許可を持ったアプリが必要になります。
確認方法としては、Microsoft Entra ID -> 管理タブからアプリの登録 -> { 使用するアプリ } -> 管理タブからAPIのアクセス許可を開けば割り当てられてるアクセス許可を見ることができます。

ここにアクセス許可を割り当てるには、＋アクセス許可の追加 -> Microsoft Graph -> アプリケーションの許可 -> User -> User.Read.Allを選択し、アクセス許可の追加をクリック。

アクセス許可が追加できていれば状態カラムにチェックマークが付くが、黄色い警告マークが付く場合はEntraIDの管理者の許可設定が必要になります。

2. テナントID、クライアントID、クライアントシークレットの取得

テナントIDとクライアントIDは、先ほどのアプリページの概要から確認することができます。

クライアントシークレットは、管理タブから証明書とシークレットを開くとシークレット一覧がでるので、＋新しいクライアントシークレットをクリックし説明と有効期限を入力して作成します。

3. 必要なパッケージの追加

npm i @microsoft/microsoft-graph-client @azure/identity

方法

1. メッセージからAadObjectIdを取得

TurnContextクラス^[1]からactivity.from.aadObjectIdプロパティを参照することで送信者のEntra IDでのユーザのObjectIDを取得できます。

const userAadId: string = context.activity.from.aadObjectId;

2. GraphAPIを用いてユーザコンテキストを取得

先ほど取得したAadObjectIdを用いて、Microsoft Graphからユーザのプロファイルを取得します。

Graph APIで特定ユーザのコンテキストを取得したい場合、/user/{id}に認証情報を含めてGETリクエストを送ることで取得できます^[2]。

以下は、取得したAadObjectIdを用いてユーザのメールアドレスを取得する例です。
.selectメソッドを用いることで特定のプロパティのみを取得することができます。メールアドレスの他にも表示名や所属名なども取得できるみたいです。

import { Client } from '@microsoft/microsoft-graph-client';
import { TokenCredentialAuthenticationProvider } from '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials';
import { ClientSecretCredential } from '@azure/identity';

const credential = new ClientSecretCredential(
	process.env.AZURE_TENANT_ID,
	process.env.AZURE_CLIENT_ID,
	process.env.AZURE_CLIENT_SECRET
);

function createGraphClient(): Client {
  const client = Client.initWithMiddleware({
    authProvider: new TokenCredentialAuthenticationProvider(credential, {
      scopes: ['https://graph.microsoft.com/.default'],
    }),
  });
  return client;
}

export async function getUserEmailFromAadId(aadObjectId: string): Promise<string | null> {
  if (!aadObjectId) return null;
  const client = createGraphClient();
  try {
    const user = await client.api(`/users/${aadObjectId}`).select('mail').get();
    return user?.mail || null;
  } catch (err) {
    console.warn(err);
    return null;
  }
}

const userEmail: string | null = await getUserEmailFromAadId(userAadId);

まとめ

Bot Frameworkで取得したaadObjectIdを用いてMicrosoft Graph APIからユーザ情報を取得する方法をまとめました。

• Entra IDでのアプリ登録と権限設定
  ユーザ情報を取得するには、User.Read.Allなどの適切なアクセス許可を持つアプリが必要です。

• Graph APIでユーザ情報を取得
  aadObjectIdをキーに/users/{id}エンドポイントを呼び出すことで、メールアドレスや表示名などのプロパティを取得できます。

参考リンク

脚注

1. Turn Context(https://learn.microsoft.com/en-us/javascript/api/botbuilder-core/turncontext?view=botbuilder-ts-latest)

2. Get a User(https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=javascript)