Microsoft Microsoft Teamsを使用して SSO タブを作成Graph Toolkit

[アーティクル]
04/06/2022

このトピックでは、Microsoft Graph Toolkitソリューションで使用Microsoft Teamsします。このガイドはシングルサインオン (SSO) を備え、バックエンドが必要なシングルページアプリ用です。対話型サインインを使用して [Teams] タブを実装する場合は、「Build a Microsoft Teams」を参照してください。

SSO タブを作成するには、次の手順を実行します。

Microsoft ファイルを追加Graph Toolkit。
認証ポップアップページを作成します。
アプリ/クライアント ID の作成
バックエンドの作成
MSAL2 プロバイダー Teams初期化します。
コンポーネントを追加します。
アプリをテストします。

Microsoft Graph Toolkit を追加する

アプリケーションで Microsoft Graph Toolkitを使用するには、(unpkg 経由で) ローダーを直接参照するか、npm パッケージをインストールします。このアプリケーションをToolkitするには、SDK のMicrosoft Teamsがあります。

unpkg
npm

ローダーを介して Toolkit SDK と Teams SDK を使用するには、スクリプト内の参照をコードに追加します。

<!-- Microsoft Teams sdk must be referenced before the toolkit -->
<script src="https://unpkg.com/@microsoft/teams-js/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>

ES6 モジュールを介して Toolkit を使用すると、バンドルプロセスを完全に制御でき、アプリケーションに必要なコードのみをバンドルできます。 ES6 モジュールを使用するには、プロジェクトに Toolkit SDK Microsoft Teams npm パッケージを追加します。

npm install @microsoft/teams-js @microsoft/mgt-element @microsoft/mgt-teams-msal2-provider @microsoft/mgt-components

アプリケーションが管理者によって事前に同意されていない限り、ユーザーはアクセス許可に同意する必要があります。これを有効にするには、認証フローに従ってアプリがポップアップTeams開くページを提供する必要があります。ページへのパスは、アプリと同じドメイン内にある限り、何でも指定できます (たとえば https://yourdomain.com/tabauth)、。このページの唯一の要件は TeamsMsal2Provider.handleAuth() 、メソッドを呼び出す必要がありますが、必要なコンテンツや読み込みの進行状況を追加できます。

次に、ポップアップ内の認証フローを処理する基本的なページの例を示します。

unpkg
npm

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@microsoft/teams-js/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
  </head>

  <body>
    <script>
      mgt.TeamsMsal2Provider.handleAuth();
    </script>
  </body>
</html>

import { TeamsMsal2Provider } from '@microsoft/mgt-teams-msal2-provider';

TeamsMsal2Provider.handleAuth();

アプリ/クライアント ID の作成

タブをアプリケーションからアクセストークンを取得するには、Azure ADアプリケーションとして実行する必要Azure AD。テナントにアプリを登録し、Microsoft Teamsアクセストークンを取得するアクセス許可を付与します。

ブラウザーを開き、管理センター Azure Active Directory移動します。個人用アカウント (Microsoft アカウント) または 仕事用アカウントまたは 学校アカウントを使用してサインインします。
左側のウィンドウで、[管理] を選択 Azure Active Directory、[管理] アプリの登録 を選択 します。
[新規登録] を選択します。 [アプリケーションを登録] ページで、次のように値を設定します。
- [ 名前] を Node.js Teams SSO (または選択した名前) に設定します。
- [サポートされているアカウントの種類] を [任意の組織のディレクトリ内のアカウントと個人用の Microsoft アカウント] に設定します。
- [ リダイレクト URI] で、 Single Page Application 最初のドロップダウンをに設定し、前の手順で作成した認証ページの URL に値を設定 https://myapp.ngrok.io/tabauthします。たとえば、。
アプリの概要ページから、アプリケーション (クライアント) ID の値を後で コピーします。新しいプロバイダーとバックエンドを作成するときに、この値が必要になります。
[ 管理] で、[証明書 ] &移動します。 [新しいクライアントシークレット] ボタンを選択します。 [説明] に値を入力して、[有効期限] のオプションのいずれかを選び、[追加] を選択します。
このページを離れる前に、クライアントシークレットの値をコピーします。これはバックエンドサービスに必要です。

重要

このクライアントシークレットは今後表示されないため、この段階で必ずコピーするようにしてください。
[ 管理] で、[ API のアクセス許可] に移動します。 [アクセス許可の追加 > ]Microsoft Graph > Delegated アクセス許可を選択し、次のアクセス許可をprofile``openid``User.Read追加します。 email``offline_access [アクセス許可の追加] を選択します。
(OPTIONAL)他のスコープに事前に同意する場合は、さらにアクセス許可を追加できます。異なるコンポーネントを使用する場合や、他の Microsoft Graph API を使用する場合は、追加のアクセス許可が必要になる場合があります。必要なアクセス許可の詳細については、各コンポーネントのドキュメントを参照してください。
- 管理者として事前に同意するには、[管理者の同意 を許可する] を選択 し、[はい] を 選択します。
[ 管理] で、[ API の公開] に移動します。ページの上部にある [設定] の横にある Application ID URI[設定] を 選択します。これにより、次の形式の API が生成されます。 api://{AppID} サブドメインを追加するために更新します。たとえば、 api://myapp.ngrok.io/{appID}.
同じページで、[スコープの追加 ] を選択します。次のようにフィールドに入力し、[スコープの追加] を選択します。
- スコープ名: access_as_user
- Who同意できますか:管理者とユーザー
- 管理者の同意表示名: Teams can access the user’s profile
- 管理者の同意の説明: Allows Teams to call the app’s web APIs as the current user
- ユーザーの同意表示名: Teams can access the user profile and make requests on the user's behalf
- ユーザーの同意の説明: Enable Teams to call this app’s APIs with the same rights as the user.
- 状態: 有効
API URL は次のように表示されます。 api://myapp.ngrok.io/{appID}/access_as_user
次に、2 つのクライアントアプリケーションを追加します。これは、デスクトップ/モバイル Teams Web クライアントのユーザー向けです。 [承認済 みクライアントアプリケーション] セクションで、[ クライアントアプリケーション の追加] を選択します。 [クライアント ID] に入力し、作成したスコープを選択します。次に、[アプリケーション の追加] を選択します。次の ID に対してこれを行います。
- 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
- 1fec8e78-bce4-4aaf-ab1b-5451cc387264

バックエンドの作成

バックエンドには、Microsoft Teams 認証トークンとトークンを交換できる任意のバックエンドを指定できます。このトークンを使用して、Graph を代理フロー経由で Microsoft Graph に呼び出す際に使用できます。

詳細については、「SSO ノードのサンプルTeamsを参照してください。

ノード Express サーバーの参照実装を次に示します。

import dotenv from 'dotenv';
import express from 'express';
import path from 'path';
import * as msal from '@azure/msal-node';
import { NextFunction, Request, Response } from 'express';
import jwt, { JwtHeader, SigningKeyCallback } from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';
import jwt_decode from 'jwt-decode';

// Load .env file
dotenv.config();

/**
 * Validates a JWT
 * @param {Request} req - The incoming request
 * @param {Response} res - The outgoing response
 * @returns {Promise<string | null>} - Returns the token if valid, returns null if invalid
 */
function validateJwt(req: Request, res: Response, next: NextFunction): void {
  const authHeader = req.headers.authorization!;
  const ssoToken = authHeader.split(' ')[1];
  if (ssoToken) {
    const validationOptions = {
      audience: process.env.CLIENT_ID,
    };
    jwt.verify(ssoToken, getSigningKey, validationOptions, (err, payload) => {
      if (err) {
        return res.sendStatus(403);
      }
      next();
    });
  } else {
    res.sendStatus(401);
  }
}

/**
 * Parses the JWT header and retrieves the appropriate public key
 * @param {JwtHeader} header - The JWT header
 * @param {SigningKeyCallback} callback - Callback function
 */
function getSigningKey(header: JwtHeader, callback: SigningKeyCallback): void {
  const client = jwksClient({
    jwksUri: 'https://login.microsoftonline.com/common/discovery/keys'
  });
  client.getSigningKey(header.kid!, (err, key) => {
    if (err) {
      callback(err, undefined);
    } else {
      callback(null, key.getPublicKey());
    }
  });
}

/**
 * Gets an access token for the user using the on-behalf-of flow
 * @param authHeader - The Authorization header value containing a JWT bearer token
 * @returns {Promise<string | null>} - Returns the access token if successful, null if not
 */
async function getAccessTokenOnBehalfOf(req: Request, res: Response): Promise<void> {
  // The token has already been validated, just grab it
  const authHeader = req.headers.authorization!;
  const ssoToken = authHeader.split(' ')[1];

  // Create an MSAL client
  const msalClient = new msal.ConfidentialClientApplication({
    auth: {
      clientId: req.body.clientid,
      clientSecret: process.env.APP_SECRET
    }
  });

  try {
    const result = await msalClient.acquireTokenOnBehalfOf({
      authority: `https://login.microsoftonline.com/${jwt_decode<any>(ssoToken).tid}`,
      oboAssertion: ssoToken,
      scopes: req.body.scopes,
      skipCache: true
    });
    res.json({ access_token: result?.accessToken });
  } catch (error) {
    if (error.errorCode === 'invalid_grant' || error.errorCode === 'interaction_required') {
      // This is expected if it's the user's first time running the app ( user must consent ) or the admin requires MFA
      res.status(403).json({ error: 'consent_required' }); // This error triggers the consent flow in the client.
    } else {
      // Unknown error
      res.status(500).json({ error: error.message });
    }
  }
}

////////////////////////
// create and run server
////////////////////////

const app = express();
const PORT = process.env.port || process.env.PORT || 8000;

// Support JSON payloads
app.use(express.json());
app.use(express.static(path.join(__dirname, 'client')));

// An example for using POST and with token validation using middleware
app.post('/api/token', validateJwt, async (req, res) => {
  await getAccessTokenOnBehalfOf(req, res);
});

app.listen(PORT, () => {
  console.log(`⚡️[server]: Server is running at http://localhost:${PORT}`);
});

MSAL2 プロバイダー Teams初期化する

Microsoft Graph Toolkitプロバイダーは、認証を有効にし、Microsoft サーバーにアクセスGraph。詳細については、「プロバイダーを使用する」を参照してください。 MSAL2 プロバイダー Teamsは、ユーザーを認証するために、TEAMS SDK で実装する必要があるすべてのロジックと操作を処理します。

SSO モードの場合は、必ず sso-url / ssoUrl バックエンド API を指定してポイントしてください。

HTML
JavaScript

HTML に mgt-teams-msal2-provider 追加します。

<mgt-teams-msal2-provider 
  client-id="<YOUR_CLIENT_ID>"
  auth-popup-url="/tabauth"
  scopes="User.Read,Mail.ReadBasic"
  sso-url="http://localhost:8000/api/token"
  http-method="POST"
  ></mgt-teams-msal2-provider>

アプリケーション<YOUR_CLIENT_ID>のクライアント ID にauth-popup-url``sso-url置き換え、認証ページへの完全パスまたは相対パスに置き換え、バックエンドサービスへの完全パスまたは相対パスに置き換える。

JavaScript コードでプロバイダーを初期化するには、をインポート TeamsMsal2Provider して設定します globalProvider。

import {Providers} from '@microsoft/mgt-element';
import {TeamsMsal2Provider, HttpMethod} from '@microsoft/mgt-teams-msal2-provider';
import * as MicrosoftTeams from "@microsoft/teams-js";

TeamsMsal2Provider.microsoftTeamsLib = MicrosoftTeams;

Providers.globalProvider = new TeamsMsal2Provider({
  clientId: `<YOUR_CLIENT_ID>`,
  authPopupUrl: '/tabauth',
  scopes: ['User.Read','Mail.ReadBasic'],
  ssoUrl: 'http://localhost:8000/api/token',
  httpMethod: HttpMethod.POST
});

アプリケーション<YOUR_CLIENT_ID>のクライアント ID にauthPopupUrl``ssoUrl置き換え、認証ページへの完全パスまたは相対パスに置き換え、バックエンドサービスへの完全パスまたは相対パスに置き換える。

コンポーネントの追加

これで、Microsoft の任意のコンポーネントを追加するGraph Toolkit完了です。

通常と同じ方法で HTML にコンポーネントを追加できます。たとえば、コンポーネントを追加するには Person 、HTML に次のコードを追加します。

<mgt-person person-query="me"></mgt-person>

ライブラリを使用している場合React代わりに、Reactコンポーネントを使用することをお勧mgt-reactめします。詳細については、「Using Microsoft Graph Toolkit with React」を参照してください。

サンプルをテストする

完全な実装については、「SSO ノードのサンプルTeamsを参照してください。

すべてが正しく構成されている場合は、 Person ログインする必要なしにコンポーネントが表示されます。

重要

事前に同意していない場合は、プロンプトで同意する必要があります。

次の手順

プレイグラウンドでさまざまなコンポーネントを試してみてください。
Microsoft Q&A に質問します。
バグを報告するか、GitHub に機能リクエストを残してください。

Microsoft Microsoft Teamsを使用して SSO タブを作成Graph Toolkit

Microsoft Graph Toolkit を追加する

アプリ/クライアント ID の作成

バックエンドの作成

MSAL2 プロバイダー Teams初期化する

コンポーネントの追加

サンプルをテストする

次の手順

フィードバック

その他のリソース

その他のリソース

Microsoft Microsoft Teamsを使用して SSO タブを作成Graph Toolkit

Microsoft Graph Toolkit を追加する

認証ポップアップ ページを作成する

アプリ/クライアント ID の作成

バックエンドの作成

MSAL2 プロバイダー Teams初期化する

コンポーネントの追加

サンプルをテストする

次の手順

フィードバック

その他のリソース

その他のリソース

認証ポップアップページを作成する