Teams アプリのシングルサインオンを有効にする

[アーティクル]
12/17/2024

Microsoft Teamsは、アプリがサインインしている Teams ユーザートークンを取得して Microsoft Graph やその他の API にアクセスするためのシングルサインオン (SSO) 機能を提供します。 Microsoft Teams ツールキットは、特定のMicrosoft Entraワークフローと統合を簡単で高レベルの API に組み込むことで、プロセスを合理化します。その結果、SSO 機能を Teams アプリに簡単に組み込むことができます。詳細については、「Microsoft Teamsでのユーザーの認証」を参照してください。

キーの構成

SSO を有効にするには、次のように Teams アプリを構成します。

Microsoft Entraアプリマニフェスト: Microsoft Entra認証アプリを識別する URI やトークンを返すリダイレクト URI など、URI を定義してください。
Teams アプリマニフェスト: 正しい構成を組み込んで、SSO アプリを Teams アプリに接続します。
Teams Toolkit の構成と infra ファイル: Teams アプリの SSO を有効にするために必要な構成が整っていることを確認します。
Teams Toolkit 構成ファイルの SSO アプリ情報: 認証アプリがバックエンドサービスに登録されていることを確認し、Teams Toolkit が Teams アプリのデバッグまたはプレビュー中に開始します。

タブアプリ
ボット/メッセージ拡張機能アプリ

アプリマニフェストMicrosoft Entra作成する

Microsoft Entra アプリマニフェストテンプレートをダウンロードします。
ダウンロードしたアプリマニフェストテンプレートコードを ./aad.manifest.json ファイルに追加します。これにより、アプリの登録のさまざまな側面をカスタマイズし、必要に応じてマニフェストを更新できます。詳細については、「アプリマニフェスト」を参照してください。

Teams アプリマニフェストを更新する

./appPackages/manifest.json ファイルに、次のコードを追加します。

"webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
}

webApplicationInfoでは、ユーザーがアプリにサインインするのに役立つMicrosoft Entraアプリ ID と Microsoft Graph 情報が提供されます。

注:

{{ENV_NAME}}を使用して、env/.env.{TEAMSFX_ENV} ファイル内の変数を参照できます。

Teams Toolkit 構成ファイルを更新する

./teamsapp.ymlや./teamsapp.local.ymlなど、Teams Toolkit 構成ファイルを見つけます。これらのファイル内のMicrosoft Entraに関連する必要な構成を更新します。

./teamsapp.yml の [provision] にaadApp/create アクションを追加し、./teamsapp.local.ymlして SSO に使用する新しいMicrosoft Entra アプリを作成します。

- uses: aadApp/create
  with:
    name: "YOUR_AAD_APP_NAME"
    generateClientSecret: true
    signInAudience: "AzureADMyOrg"
  writeToEnvironmentFile:
      clientId: AAD_APP_CLIENT_ID
      clientSecret: SECRET_AAD_APP_CLIENT_SECRET
      objectId: AAD_APP_OBJECT_ID
      tenantId: AAD_APP_TENANT_ID
      authority: AAD_APP_OAUTH_AUTHORITY

注:

name値を Teams アプリの目的の名前に置き換えます。

詳細については、「aadApp/create」を参照してください。

./teamsapp.ymlと./teamsapp.local.ymlのprovisionの下にaadApp/updateアクションを追加して、Microsoft Entra アプリを更新します。
```
- uses: aadApp/update
  with:
    manifestPath: "./aad.manifest.json"
    outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"
```
注:
- ファイルのパスを変更した場合は、Microsoft Entra アプリマニフェストテンプレート aad.manifest.jsonの相対パスにmanifestPath値を更新します。
- ローカルセットアップで、file/createOrUpdateEnvironmentFileアクションの後にaad/updateを配置します。これは、 aad/update が file/createOrUpdateEnvironmentFileからの出力を使用するためです。
詳細については、aadApp/update を参照してください
React プロジェクトの場合は、[deploy] の下のcli/runNpmCommandを更新します。
CLI で React フレームワークを使用してタブアプリをビルドする場合は、teamsapp.yml ファイルで build app を使用したcli/runNpmCommand アクションを見つけて、次の環境変数を追加します。
```
env:
  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html
```
React フレームワークを使用してタブアプリをビルドする場合は、teamsapp.local.yml ファイルでデプロイのfile/createOrUpdateEnvironmentFileアクションを見つけて、次の環境変数を追加します。
```
envs:
  ...
  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html
```

ソースコードを更新する

上記の変更を実装すると、環境が準備されます。コードを更新して、Teams アプリに SSO を組み込むことができます。

Vanilla JavaScript

Reactを使用しないタブアプリの場合、SSO トークンを取得する基本的な例として次のコードを使用します。

function getSSOToken() {
  return new Promise((resolve, reject) => {
    microsoftTeams.authentication.getAuthToken()
      .then((token) => resolve(token))
      .catch((error) => reject("Error getting token: " + error));
  });
}

function getBasicUserInfo() {
  getSSOToken().then((ssoToken) => {
    const tokenObj = JSON.parse(window.atob(ssoToken.split(".")[1]));
    console.log(`username: ${tokenObj.name}`);
    console.log(`user email: ${tokenObj.preferred_username}`);
  });
}

React

React プロジェクトの場合は、デプロイプロセスで次の環境変数が設定されていることを確認します。

JavaScript プロジェクトについては、「タブ JavaScript サンプル」を参照してください。
TypeScript プロジェクトについては、「Tab TypeScript サンプル」を参照してください。

ソースコードを更新するには、次の手順に従います。

auth-start.htmlファイルとauth-end.html ファイルを auth/public フォルダーから public/ フォルダーに移動します。これらの HTML ファイルは、認証リダイレクトを処理する目的で機能します。
auth/の下ssoフォルダーをsrc/sso/に移動します。
1. InitTeamsFx: このファイルは、TeamsFx SDK を初期化する関数を実行します。 SDK の初期化後、 GetUserProfile コンポーネントが開きます。
2. GetUserProfile: このファイルは、Microsoft Graph APIを呼び出してユーザー情報を取得する関数を実行します。
Welcome.*でInitTeamsFxをインポートして追加します。

詳細については、「SSO が有効なタブアプリ」を参照してください。

アプリマニフェストMicrosoft Entra作成する

Microsoft Entra アプリマニフェストテンプレートをダウンロードします。
ダウンロードしたアプリマニフェストテンプレートコードを ./aad.manifest.json ファイルに追加します。これにより、アプリの登録のさまざまな側面をカスタマイズし、必要に応じてマニフェストを更新できます。詳細については、「アプリマニフェスト」を参照してください。

Teams アプリマニフェストを更新する

./appPackages/manifest.json ファイルに、次のコードを追加します。
```
"webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
}
```
webApplicationInfoでは、ユーザーがアプリにサインインするのに役立つMicrosoft Entraアプリ ID と Microsoft Graph 情報が提供されます。

注:

{{ENV_NAME}}を使用して、env/.env.{TEAMSFX_ENV} ファイル内の変数を参照できます。
commandListsに 1 つ以上のコマンドを登録します。

commandListsには、ボットがユーザーに提案できるコマンドが含まれています。 teamsFx ボットテンプレートを使用している場合は、次の値を設定します。
```
{
  "title": "profile",
  "description": "Show user profile using Single Sign On feature"
}
```
[ validDomains ] フィールドには、アプリが Teams クライアント内で読み込む Web サイトのドメインが含まれます。次の値を更新します。
```
"validDomains": [
"${{BOT_DOMAIN}}"
]
```

Teams Toolkit 構成ファイルを更新する

./teamsapp.ymlや./teamsapp.local.ymlなど、Teams Toolkit 構成ファイルを見つけます。これらのファイル内のMicrosoft Entraに関連する必要な構成を更新します。

./teamsapp.yml のprovisionの下に次のコード aadApp/createを追加し、して SSO に使用される新しいMicrosoft Entra アプリを作成します。

- uses: aadApp/create
  with:
    name: "YOUR_AAD_APP_NAME"
    generateClientSecret: true
    signInAudience: "AzureADMyOrg"
  writeToEnvironmentFile:
      clientId: AAD_APP_CLIENT_ID
      clientSecret: SECRET_AAD_APP_CLIENT_SECRET
      objectId: AAD_APP_OBJECT_ID
      tenantId: AAD_APP_TENANT_ID
      authority: AAD_APP_OAUTH_AUTHORITY
      authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST

注:

name値を、Microsoft Teams アプリの目的の名前に置き換えます。

詳細については、「aadApp/create」を参照してください。

./teamsapp.yml のprovisionの下に次のコード aadApp/updateを追加し、Microsoft Entra アプリを更新する./teamsapp.local.ymlします。
```
- uses: aadApp/update
  with:
    manifestPath: "./aad.manifest.json"
    outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"
```
注:

ファイルのパスを変更した場合は、Microsoft Entra アプリマニフェストテンプレート aad.manifest.jsonの相対パスにmanifestPath値を更新します。

詳細については、aadApp/update を参照してください

teamsapp.local.yml ファイルでcreateOrUpdateEnvironmentFileアクションを見つけて、次の環境変数を追加します。

envs:
  ...
  M365_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  M365_CLIENT_SECRET: ${{SECRET_AAD_APP_CLIENT_SECRET}}
  M365_TENANT_ID: ${{AAD_APP_TENANT_ID}}
  INITIATE_LOGIN_ENDPOINT: ${{BOT_ENDPOINT}}/auth-start.html
  M365_AUTHORITY_HOST: ${{AAD_APP_OAUTH_AUTHORITY_HOST}}
  M365_APPLICATION_ID_URI: api://botid-${{BOT_ID}}

Infra の更新

リモートサービスMicrosoft Entra関連する構成を更新します。次の例は、Azure Web アプリの構成設定を示しています。

M365_CLIENT_ID: アプリクライアント ID Microsoft Entra
M365_CLIENT_SECRET: アプリクライアントシークレットMicrosoft Entra
M365_TENANT_ID: アプリのテナント ID Microsoft Entra
INITIATE_LOGIN_ENDPOINT: 認証用のログイン開始ページ
M365_AUTHORITY_HOST: Microsoft Entra アプリ OAuth 機関ホスト
M365_APPLICATION_ID_URI: Microsoft Entra アプリの識別子 URI

[ teamsFx ] タブまたはボットテンプレートを使用するには、次の手順に従います。

infra/azure.parameters.json ファイルを開き、次のコードを追加します。

"m365ClientId": {
  "value": "${{AAD_APP_CLIENT_ID}}"
},
"m365ClientSecret": {
  "value": "${{SECRET_AAD_APP_CLIENT_SECRET}}"
},
"m365TenantId": {
  "value": "${{AAD_APP_TENANT_ID}}"
},
"m365OauthAuthorityHost": {
  "value": "${{AAD_APP_OAUTH_AUTHORITY_HOST}}"
}

infra/azure.bicep ファイルを開き、param location string = resourceGroup().location後に次のコードを追加します。

param m365ClientId string
param m365TenantId string
param m365OauthAuthorityHost string
param m365ApplicationIdUri string = 'api://botid-${botAadAppClientId}'
@secure()
param m365ClientSecret string

infra/azure.bicep ファイルにoutputする前に、次のコードを追加します。
```
resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = {
  name: '${webAppName}/appsettings'
  properties: {
    M365_CLIENT_ID: m365ClientId
    M365_CLIENT_SECRET: m365ClientSecret
    INITIATE_LOGIN_ENDPOINT: uri('https://${webApp.properties.defaultHostName}', 'auth-start.html')
    M365_AUTHORITY_HOST: m365OauthAuthorityHost
    M365_TENANT_ID: m365TenantId
    M365_APPLICATION_ID_URI: m365ApplicationIdUri
    BOT_ID: botAadAppClientId
    BOT_PASSWORD: botAadAppClientSecret
    RUNNING_ON_AZURE: '1'
  }
}
```
注:
- Azure Web App に追加の構成を追加するには、 webAppSettingsに構成を追加します。
- また、次の構成を追加して、既定のノードバージョンを定義する必要がある場合もあります。 bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0'
ソースコードの更新
- ボット
- メッセージ拡張機能
1. auth/sso フォルダーにあるファイルをsrcに移動します。 ProfileSsoCommandHandler クラスは、SSO トークンを使用してユーザー情報を取得するように設計された SSO コマンドハンドラーとして機能します。この方法を採用して、独自の SSO コマンドハンドラーを開発できます。
2. auth/public フォルダーを src/public に移動します。このフォルダーには、ボットアプリの HTML ページが含まれています。 Microsoft Entraを使用して SSO フローを開始すると、ユーザーはこれらのページにリダイレクトされます。
3. ./ フォルダーで次のコマンドを実行します。
```
npm install copyfiles --save-dev
```
4. package.json ファイルで次のコマンドを更新します。
```
"build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/",
```
  認証リダイレクトに使用される HTML ページは、このボットプロジェクトをビルドするときにコピーされます。
5. src/index ファイルで、次のコマンドを追加してisomorphic-fetchをインポートします。
```
 require("isomorphic-fetch");
```
6. 認証ページにリダイレクトするには、次のコマンドを追加します。
```
server.get(
    "/auth-:name(start|end).html",
    restify.plugins.serveStatic({
      directory: path.join(__dirname, "public"),
    })
);
```
7. commandApp.requestHandlerを更新して、認証が次のコードで動作することを確認します。
```
await commandApp.requestHandler(req, res).catch((err) => {
    // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, sholdn't throw this error.
    if (!err.message.includes("412")) {
    throw err;
    }
});
```
8. src/internal/initializeの ConversationBot にssoConfigとssoCommandsを追加します。
```
import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler";

export const commandBot = new ConversationBot({
    ...
    // To learn more about ssoConfig, please refer teamsfx sdk document: https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk
    ssoConfig: {
    aad :{
      scopes:["User.Read"],
    },
    },
    command: {
    enabled: true,
    commands: [new HelloWorldCommandHandler() ],
    ssoCommands: [new ProfileSsoCommandHandler()],
    },
});
```
1. TeamsActivityHandler.handleTeamsMessagingExtensionQueryに API キー handleMessageExtensionQueryWithSSOを実装します。詳細については、メッセージ拡張機能の SSO に関するページを参照してください。
2. auth/public フォルダーを src/public に移動します。このフォルダーには、ボットアプリの HTML ページが含まれています。 Microsoft Entraを使用して SSO フローを開始すると、ユーザーはこれらのページにリダイレクトされます。
3. src/index ファイルを更新して、適切なrestifyを追加します。
```
const path = require("path");

// Listen for incoming requests.
server.post("/api/messages", async (req, res) => {
    await adapter.process(req, res, async (context) => {
    await bot.run(context);
    }).catch((err) => {
    // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, sholdn't throw this error.
    if(!err.message.includes("412")) {
          throw err;
      }
    })
});

server.get(
    "/auth-:name(start|end).html",
    restify.plugins.serveStatic({
    directory: path.join(__dirname, "public"),
    })
);
```
4. ./ フォルダーで次のコマンドを実行します。
```
npm install @microsoft/teamsfx
```
```
npm install isomorphic-fetch
```
5. TeamsActivityHandler.handleTeamsMessagingExtensionQueryに API キー handleMessageExtensionQueryWithSSOを実装します。
6. copyfiles npm パッケージを TypeScript ボットプロジェクトにインストールし、src/package.json ファイル内のbuild スクリプトを次のように更新します。
```
"build": "tsc --build && copyfiles ./public/*.html lib/",
```
  認証リダイレクトに使用される HTML ページは、このボットプロジェクトをビルドするときにコピーされます。
7. handleMessageExtensionQueryWithSSO関数で使用するスコープを使用して、templates/appPackage/aad.template.json ファイルを更新します。
```
"requiredResourceAccess": [
      {
      "resourceAppId": "Microsoft Graph",
      "resourceAccess": [
              {
                  "id": "User.Read",
                  "type": "Scope"
              }
      ]
      }
  ]
```

アプリのデバッグ

アプリをデバッグするには、 F5 キーを選択します。 Teams Toolkit では、Microsoft Entra マニフェストを使用して SSO 対応アプリを登録します。詳細については、「Teams アプリをローカルでデバッグする」を参照してください。

Microsoft Entra アプリをカスタマイズする

Teams アプリマニフェストを使用すると、アプリの登録のさまざまな側面をカスタマイズできます。マニフェストは必要に応じて更新できます。

目的の API にアクセスするための追加の API アクセス許可を含める場合は、「マニフェストMicrosoft Entra編集する」を参照してください。

Azure portalでMicrosoft Entra アプリを表示するには、「Microsoft Entra マニフェストの編集」を参照してください。

次の手順

Teams アプリにシングルサインオンを追加する

次の方法で共有

Teams アプリのシングルサインオンを有効にする

キーの構成

アプリマニフェストMicrosoft Entra作成する

Teams アプリマニフェストを更新する

Teams Toolkit 構成ファイルを更新する

ソースコードを更新する

Vanilla JavaScript

React

アプリマニフェストMicrosoft Entra作成する

Teams アプリマニフェストを更新する

Teams Toolkit 構成ファイルを更新する

Infra の更新

ソースコードの更新

アプリのデバッグ

Microsoft Entra アプリをカスタマイズする

次の手順

その他のリソース

次の方法で共有

Teams アプリのシングル サインオンを有効にする

キーの構成

アプリ マニフェストMicrosoft Entra作成する

Teams アプリ マニフェストを更新する

Teams Toolkit 構成ファイルを更新する

ソース コードを更新する

Vanilla JavaScript

React

アプリのデバッグ

Microsoft Entra アプリをカスタマイズする

次の手順

その他のリソース

Teams アプリのシングルサインオンを有効にする

アプリマニフェストMicrosoft Entra作成する

Teams アプリマニフェストを更新する

ソースコードを更新する