SSO を有効にするコードを追加する

[アーティクル]
11/14/2023

SSO を有効にするコードを追加する前に、アプリを Microsoft Entra ID に登録してください。

Microsoft Entra ID からアクセストークンを取得するには、タブアプリのクライアント側コードを構成する必要があります。アクセストークンは、タブアプリの代わりに発行されます。タブアプリで追加の Microsoft Graph アクセス許可が必要な場合は、サーバー側にアクセストークンを渡し、Microsoft Graph トークンと交換する必要があります。

アクセストークンを処理するためのコードを構成する

このセクションでは、次の手順について説明します。

クライアント側のコードを追加する
アクセストークンをサーバー側のコードに渡す
アクセストークンを検証する

クライアント側のコードを追加する

現在のアプリユーザーのアプリアクセスを取得するには、クライアント側のコードがアクセストークンを取得するために Teams を呼び出す必要があります。 getAuthToken() を使用して検証プロセスを開始するために、クライアント側のコードを更新する必要があります。

getAuthToken() の詳細

getAuthToken() は、JavaScript ライブラリMicrosoft Teamsメソッドです。アプリの代わりに Microsoft Entra アクセストークンを発行するよう要求します。トークンの有効期限が切れていない場合、トークンはキャッシュから取得されます。有効期限が切れた場合、新しいアクセストークンを取得するための要求が Microsoft Entra ID に送信されます。

詳細については、getAuthToken を参照してください。

getAccessToken を呼び出す場合

現在のアプリユーザーにアクセストークンが必要な場合に getAuthToken() を使用します。

アクセストークンが必要な場合...	getAuthToken() を呼び出します...
アプリユーザーがアプリにアクセスする場合	`microsoftTeams.app.initialize()`後。
アプリの特定の機能を使用するには	アプリユーザーがサインインを必要とするアクションを実行した場合。

getAuthToken のコードを追加する

JavaScript コードスニペットをタブアプリに追加するには、次の手順を実行します。

getAuthToken() を呼び出します。
アクセストークンを解析するか、それをサーバー側コードに渡します。

次のコードスニペットに、getAuthToken() の呼び出しの例を示します。

microsoftTeams.app.initialize().then(() => {
    getClientSideToken()
        .then((clientSideToken) => {
            return getServerSideToken(clientSideToken);
        })
        .then((profile) => {
            return useServerSideToken(profile);
        })
        .catch((error) => {
            ...
        })
}

    function getClientSideToken() {

        return new Promise((resolve, reject) => {
            display("1. Get auth token from Microsoft Teams");
            
            microsoftTeams.authentication.getAuthToken().then((result) => {
                display(result);

                resolve(result);
            }).catch((error) => {
                reject("Error getting token: " + error);
            });
        });
    }

getAuthToken() の呼び出しを、このトークンが必要とされる場所でアクションを開始するすべての関数とハンドラーに追加できます。

クライアント側コードの例を次に示します。

Teams は、アクセストークンを受け取るとキャッシュされ、必要に応じて再利用されます。このトークンは、 getAuthToken() が呼び出されるたびに、有効期限が切れるまで、Microsoft Entra ID を別の呼び出しを行わずに使用できます。

重要

アクセストークンのセキュリティのベストプラクティスは以下のとおりです。

アクセストークンが必要な場合は、常に getAuthToken() を呼び出します。
Teams はアクセストークンを自動的にキャッシュするため、アプリのコード内にキャッシュまたは格納する必要はありません。

getAuthToken()を呼び出し、ユーザーレベルのアクセス許可にアプリユーザーの同意が必要な場合は、サインインしているアプリユーザーに Microsoft Entra ダイアログが表示されます。

タブシングルサインオンダイアログプロンプト

表示される同意ダイアログは、Microsoft Entra ID で定義されている open-id スコープ用です。アプリユーザーは同意を 1 回だけ行う必要があります。アプリユーザーは、同意した後、付与されたアクセス許可とスコープに対してタブアプリにアクセスして使用できます。

重要

同意ダイアログが不要なシナリオ:

テナント管理者がテナントに代わって同意した場合、アプリユーザーに同意を求めるメッセージを表示する必要はありません。つまり、アプリユーザーは同意ダイアログを表示することなく、アプリにシームレスにアクセスできます。
Microsoft Entra アプリが Teams で認証を要求しているのと同じテナントに登録されている場合、アプリユーザーは同意を求められず、すぐにアクセストークンが付与されます。アプリユーザーは、Microsoft Entra アプリが別のテナントに登録されている場合にのみ、これらのアクセス許可に同意します。

エラーが発生した場合は、「Teams での SSO 認証のトラブルシューティング」を参照してください。

アクセストークンを ID トークンとして使用する

タブアプリに返されるトークンは、アクセストークンと ID トークンの両方です。タブアプリは、トークンをアクセストークンとして使用して、サーバー側の API に対して認証された HTTPS 要求を行うことができます。

getAuthToken() から返されたアクセストークンは、トークンの次の要求を使用してアプリユーザーの ID を確立するために使用できます。

name: ユーザーの表示名。
preferred_username: アプリユーザーの電子メールアドレス。
oid - アプリユーザーの ID を表す GUID。
tid - アプリユーザーがサインインしているテナントを表す GUID。

Teams は、ユーザーの設定など、アプリユーザーの ID に関連付けられたこの情報をキャッシュできます。

注:

システム内のユーザーを表す一意の ID を作成する必要がある場合は、「クレームを使用してユーザーを確実に識別する」を参照してください。

アクセストークンをサーバー側のコードに渡す

サーバー上の Web API にアクセスする必要がある場合は、アクセストークンをサーバー側のコードに渡す必要があります。 Web API では、アクセストークンをデコードして、そのトークンの要求を表示する必要があります。

注:

返されたアクセストークンでユーザープリンシパル名 (UPN) を受け取らない場合は、Microsoft Entra ID でオプションの要求として追加します。詳細については、「アクセストークン」を参照してください。

getAuthToken() のコールバックに成功して受け取ったアクセストークンは、(認証されたアプリユーザー用の) Web API へのアクセスを提供します。サーバー側のコードは、必要に応じてトークンを解析して ID 情報を取得することもできます。

Microsoft Graph データを取得するためにアクセストークンを渡す必要がある場合は、「Microsoft Graph のアクセス許可を持つタブアプリを拡張する」を参照してください。

アクセストークンをサーバー側に渡すためのコード

次のコードは、アクセストークンをサーバー側に渡す例を示しています。トークンは、サーバー側の Web API に要求を送信するときに Authorization ヘッダーに渡されます。この例では JSON データを送信し、POST メソッドを使用します。サーバーに書き込まない場合は、GET はアクセストークンを送信するのに十分です。

function getServerSideToken(clientSideToken) {
        return new Promise((resolve, reject) => {
            microsoftTeams.app.getContext().then((context) => {
                fetch('/getProfileOnBehalfOf', {
                    method: 'post',
                    headers: {
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({
                        'tid': context.user.tenant.id,
                        'token': clientSideToken
                    }),
                    mode: 'cors',
                    cache: 'default'
                })
                .then((response) => {
                    if (response.ok) {
                        return response.json();
                    } else {
                        reject(response.error);
                    }
                })
                .then((responseJson) => {
                    if (responseJson.error) {
                        reject(responseJson.error);
                    } else {
                        const profile = responseJson;

                        resolve(profile);
                    }
                });
            });
        });
    }

アクセストークンを検証する

アクセストークンの検証の詳細については、「トークンの検証」を参照してください。

アクセストークンの例

次のコードは、アクセストークンの一般的なデコードされたペイロードです。

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

コードサンプル

サンプルの名前	説明	.NET	Node.js	マニフェスト
タブ SSO	タブのサンプルアプリMicrosoft Teams Microsoft Entra SSO	表示	表示、 Teams Toolkit	該当なし
タブ、ボット、メッセージ拡張機能 (ME) SSO	このサンプルでは、タブ、ボット、ME の SSO (検索、アクション、リンクの展開) を示します。	表示	表示	表示

次の手順

Teams アプリマニフェストを更新し、アプリをプレビューする

次の方法で共有

SSO を有効にするコードを追加する

クライアント側のコードを追加する

getAccessToken を呼び出す場合

getAuthToken のコードを追加する

アクセストークンを ID トークンとして使用する

アクセストークンをサーバー側のコードに渡す

アクセストークンをサーバー側に渡すためのコード

アクセストークンを検証する

アクセストークンの例

コードサンプル

次の手順

関連項目

その他のリソース

次の方法で共有

SSO を有効にするコードを追加する

クライアント側のコードを追加する

getAccessToken を呼び出す場合

getAuthToken のコードを追加する

アクセス トークンを取得するための同意ダイアログ

アクセス トークンを ID トークンとして使用する

アクセス トークンをサーバー側のコードに渡す

アクセス トークンをサーバー側に渡すためのコード

アクセス トークンを検証する

アクセス トークンの例

コード サンプル

次の手順

関連項目

その他のリソース

アクセストークンを取得するための同意ダイアログ

アクセストークンを ID トークンとして使用する

アクセストークンをサーバー側のコードに渡す

アクセストークンをサーバー側に渡すためのコード

アクセストークンを検証する

アクセストークンの例

コードサンプル