✨

Company Communicator v5.1 デプロイメモ

Kazuki Ota

2022/08/01に公開

Azure

Teams

tech

これは Microsoft がアプリテンプレートとして GitHub 上で OSS として公開している Company Communicator v5.1 のデプロイのメモです。

Company Communicator は GitHub 上で活発に開発が行われているため、あくまで 2022/08/01 時点のバージョン 5.1 に対するメモになります。今後のバージョンアップにより変わる可能性があるため、参考にする場合には自分がデプロイしようとしている Company Communicator のバージョンを確認してください。

また、Company Communicator のデプロイは PowerShell と手動の 2 通りが用意されていますが、この記事では Microsoft 365 のテナントと Azure サブスクリプションのテナントが違う場合でもデプロイが出来る手動デプロイの方法でやります。

準備する必要があるもの

以下のものが必要になります。

Azure AD のテナント
Azure サブスクリプション
Microsoft 365 のテナント

Azure AD のテナントと Microsoft 365 のテナントは同じである必要があります。Azure サブスクリプションに関しては別のテナントでも問題ありません。

また、上記のテナントに対して以下の操作が出来る必要があります。

Azure AD のグローバル管理者
- グローバル管理者の権限がない場合は、後でグローバル管理者に操作を依頼する必要があります。
Azure サブスクリプションに対して以下のサービスがデプロイ出来る
- App Service
- App Service Plan
- Azure Bot
- Azure Function
- Azure Storage Account
- Service Bus
- Application Insights
- Azure Key vault
- Azure Front Door
Microsoft 365 の Teams 管理センターでアプリケーションのアップロードが出来る

デプロイの流れ

デプロイの流れは以下のようになります。

Azure AD へのアプリケーション登録
Azure へのリソースのデプロイ (1時間以上の待ち時間が発生します。)
Azure AD へ登録したアプリケーションの権限設定とシングルサインオンの構成
Teams アプリのパッケージの作成
Teams へのインストール

デプロイ

ではデプロイをしていきます。

Azure AD へのアプリケーション登録

Azure AD に Company Communicator で使用するアプリケーションの登録を行います。
Company Communicator では 3 つのアプリケーション登録を作成します。それぞれ「ユーザー向けボットアプリ」「メッセージ作成者向けボットアプリ」「Teams のタブアプリ」用の定義になります。

デプロイ手順書では以下の名前をお勧めされています。

Company Communicator User
- ユーザー向けボットアプリ
Company Communicator Author
- メッセージ作成者向けのボットアプリ
Company Communicator App
- Teams のタブアプリ

Azure AD の画面を開きます。色々な開き方があると思いますが、私は https://portal.azure.com を開いてサインインを行った後、画面左上のハンバーガーメニューのアイコンをクリックして Azure Active Directory のメニューを選択して開いています。

Azure AD の画面を開いたら、左側のメニューから「アプリの登録」を選択します。

そして「新規登録」を選択してアプリを登録します。

登録する際に「サポートされるアカウントの種類」という項目を選択するのですが、ここがはまりポイントの 1 つになります。
具体的には以下のように選択する必要があります。

Company Communicator User
- 任意の組織ディレクトリ内のアカウント (任意の Azure AD ディレクトリ - マルチテナント) を選択
Company Communicator Authoer
- 任意の組織ディレクトリ内のアカウント (任意の Azure AD ディレクトリ - マルチテナント) を選択
Company Communicator App
- この組織ディレクトリのみに含まれるアカウント (Contoso のみ - シングルテナント) を選択

User と Authoer がマルチテナントで、App がシングルテナントになります。ここで間違えると、デプロイ完了後にアプリケーションが動かない原因になるため注意してください。

Company Communicator User アプリの登録

では、アプリケーションを登録していきます。Company Communicator User は以下のように入力して登録を行います。名前とサポートされているアカウントの種類を設定すれば良いです。

アプリケーションを作成したら「アプリケーション (クライアント) ID」をコピーしてメモをしてください。デプロイ時に使用します。

続けて「証明書とシークレット」から「新しいクライアントシークレット」を選択して新しいシークレットを 1 つ追加してください。

作成されたシークレットは画面遷移をすると確認できなくなってしまうので、以下の部分の値をコピーしてメモをしておいてください。

もし、コピーをする前に画面遷移をしてしまった場合は、もう 1 つシークレットを作成して値をコピーしてください。古いシークレットについてはあっても害はありませんが消しておいた方が安全です。

Company Communicator Author アプリの登録

名前以外は Company Communicator User と同じです。このアプリのアプリケーション ID とシークレットの値もメモしておいてください。

Company Communicator App アプリの登録

このアプリだけシングルテナントを選択する必要があるので注意してください。
アプリケーションの登録を作成する画面で以下のようにシングルテナントを選択してください。デフォルト値がシングルテナントなので、変更しなければシングルテナントになります。

このアプリのアプリケーション ID とシークレットの値もメモしておいてください。

テナント ID の確認

もし、デプロイする Azure AD のテナントと、Microsoft 365 のテナントが異なる Azure AD のテナントの場合には、Azure AD の概要ページからテナント ID をコピーしてメモしてください。

Azure へのデプロイ

次に Azure にリソースをデプロイします。デプロイするにあたって、これまでの手順でメモした以下の 7 つの情報が必要になります。

Company Communicator User のアプリケーション ID
Company Communicator User のシークレット
Company Communicator Author のアプリケーション ID
Company Communicator Author のシークレット
Company Communicator App のアプリケーション ID
Company Communicator App のシークレット
Azure AD のテナント ID (デプロイするテナントが Azure と M365 で異なる場合のみ必要)

オリジナルの手順書にある Deploy to Azure のボタンをクリックします。もしくは以下のリンクをクリックします。

クリックすると、以下のような画面が表示されるので空欄を埋めていきます。基本的には英語圏のユーザーを想定されたデフォルト値が入っているため en-us の部分を ja-jp にするといった変更も必要になります。

一般的な日本向けの環境の場合には基本的には以下の項目を変更する必要があります。

サブスクリプション
- デプロイするサブスクリプションを選択してください
リソースグループ
- デプロイする先のリソースグループを作成してください。
リージョン
- お好みのリージョンを作成してください。
Base Resource Name
- 任意の半角アルファベットと数字を入力してください。あまり長いと、この文字列を使って作られるリソース名の長さの制限にひっかかるため、短めにしてください。

以下の項目には、登録したアプリの ID とシークレットを入力してください。
User が Company Communicator User で Authoer が Company Communicator Author で Graph App が Company Communicator App です。

User Client Id
User Client Secret
Author Client id
Author Client Secret
Graph App Id
Graph App Secret

続けて以下の項目も変更します。

Sender UPN List
- Company Communicator でメッセージを送信する操作をすることが出来るユーザーの UPN (メールアドレス) をセミコロン区切りで入力してください。後でも変更は出来るので、とりあえずテストで送信できれば良いユーザーを指定するだけで大丈夫です。
Proactive Install User App
- デフォルト値の true の場合 Company Communicator のメッセージ送信時にユーザーに対して Company Communicator のアプリのインストールを試みます。Teams 管理センターなどでアプリ配信を管理する場合は false にしてください。
User App External Id
- もし Company Communicator を複数個同じテナントに展開する場合は独自の GUID を設定してください。
Default Culture
- ja-JP にします。
App Display Name
- アプリケーションの表示名を変えたい場合は変更してください。
Tenant Id
- Azure サブスクリプションのテナントと Microsoft 365 のテナントが同じ場合はデフォルト値の [subscription().tenantId] のままにしてください。異なる場合は Microsoft 365 のテナント ID を入力してください。

以下の項目は複数個の Company Communicator を同じテナントに展開する場合に変更が必要になります。1 つしかない場合はデフォルト値で問題ありません。

Service Bus Web App Role Name Guid
Service Bus Prep Func Role Name Guid
Service Bus Func Role Name Guid
Service Bus Data Func Role Name Guid
Storage Account Web App Role Name Guid
Storage Account Prep Func Role Name Guid
Storage Account Data Func Role Name Guid

GUID の生成方法

GUID の生成方法には色々な方法があると思いますが個人的に Windows を使っている場合は PowerShell で New-Guid のコマンドレットを叩いて作ることが多いです。追加で何かを入れることなく使えるので地味に便利です。以下のような感じになります。

> New-Guid

Guid
----
abbf4c4c-2c4e-4d37-a6d1-972b3581f637

私の場合は Azure サブスクリプションのテナントと Microsoft 365 のテナントが異なって、AdeleV というアカウントにメッセージを送信させたかったので以下のようになりました。

入力が完了したら「確認と作成」を選択してエラーがないことを確認して「作成」をクリックしてデプロイを実行してください。

デプロイ失敗への対応

デプロイには 1 時間以上かかるケースもあります。そしてほぼ 100% エラーで失敗します。エラーの内容にもよりますが、入力項目を間違えていない限りリトライを繰り返すことで解消することが出来ます。エラーが出てもデプロイが進行中の間落ち着いて待ちましょう。

以下のようになっても慌てなくて大丈夫です。

エラーの内容と再デプロイ実行

失敗している行の操作の詳細のリンクをクリックするとエラーメッセージが確認できます。リソース名がルールにあってないといったようなリトライによって解消しようがないエラー以外の場合は再デプロイによって解消することがほとんどです。画面上部の「再デプロイ」を選択して再デプロイを実施してください。

再デプロイでもデプロイ時と同じ入力画面が出てきます。ここには最初にデプロイしたときと同じサブスクリプション、同じリソースグループを選択してください。各アプリのシークレットは保存されていないので、再入力が必要です。その他の値も最初にデプロイしたときと同じ値を入れてください。個人的に罠だと思うのが Default Culuture の値が en-US に戻っているところです。忘れずに ja-JP にしましょう。

デプロイに成功すると以下のような画面が表示されます。

デプロイ完了画面の左側にある出力から appDomain という項目があるので、これをメモしておいてください。

Azure AD へ登録したアプリケーションの権限設定とシングルサインオン (SSO) の構成

デプロイが完了したので、実際にデプロイされたリソースの情報を使って Azure AD へ登録したアプリケーションに対して設定をしていきます。（厳密にはデプロイ待ちの時間にやることもできます）
オリジナルのデプロイ手順の「3. Set-up Authentication」の部分に対応します。

Company Communicator App の SSO の設定

Azure AD の「アプリの登録」から Company Communicator App という名前で登録したアプリケーションを開きます。

「認証」を選択して「プラットフォームを追加」を選択してください。

プラットフォームの構成を選択する画面が表示されるので「Web」を選択して以下のようにリダイレクト URI に https://デプロイ後にメモしたappDomain/signin-simple-end を入力してください。そして暗黙的な認可およびハイブリッドフローの「アクセストークン」および「ID トークン」にチェックをして「構成」を選択してください。

次に「API の公開」を選択して、アプリケーション ID の URI の横にある設定を選択してください。

デフォルト値の api://ランダムな GUID の形式の URI ではなく api://デプロイ後にメモしたappDomain の形式の URI を入力してください。今回作っているアプリのドメインは kazukicc.azurefd.net なので api://kazukicc.azurefd.net になります。`

アプリケーション ID の URI を設定が完了したら、その下にある「Scope の追加」を選択してください。スコープには以下の値を設定してください。

スコープ名: access_as_user
同意できるのはだれですか？: 管理者とユーザー
管理者の同意の表示名: Access the API as the current logged-in user
管理者の同意の説明: Access the API as the current logged-in user

値を入力したら「スコープの追加」を選択してスコープを追加します。

次に、その下にある「承認済みのクライアントアプリケーション」の項目に設定を追加します。「クライアントアプリケーションの追加」を選択して表示された画面に以下の項目を設定します。

クライアントID: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
承認済みスコープ: 上の手順で追加した access_as_user スコープにチェックを入れる。

もう一度「クライアントアプリケーションの追加」を選択して表示された画面に以下の項目を設定します。

クライアントID: 1fec8e78-bce4-4aaf-ab1b-5451cc387264
承認済みスコープ: 上の手順で追加した access_as_user スコープにチェックを入れる。

ここまでの手順を行うと API の公開ページは以下のようになります。

次に「マニフェスト」を選択します。そして表示された JSON のなかから optionalClaims の行を探します。

この "optionalClaims: null, の行を以下の内容で置き換えます。

    "optionalClaims": {
        "idToken": [],
        "accessToken": [
            {
                "name": "upn",
                "source": null,
                "essential": false,
                "additionalProperties": []
            }
        ],
        "saml2Token": []
    },

置き換えたら画面上部の「保存」を選択して変更内容を保存してください。

Company Communicator App の権限の設定

引き続き Company Communicator App の権限を設定していきます。「API のアクセス許可」を選択して「アクセス許可の追加」を選択します。

API アクセス許可の要求の画面が表示されるので Microsoft Graph を選択します。

そして「委任されたアクセス許可」を選択して表示されたアクセス許可のリストから以下の 2 つの権限にチェックを入れてください。画面にある検索ボックスで絞り込みを行いながらチェックをしていくとスムーズです。

GroupMember.Read.All
AppCatalog.Read.All

次に「アプリケーションの許可」に移動して、同様の手順で以下の 3 つの権限にチェックを入れてください。

GroupMember.Read.All
User.Read.All
TeamsAppInstallation.ReadWriteForUser.All

チェックを付け終わったら「アクセス許可の追加」を選択して変更内容を反映します。変更内容を反映すると以下のような画面になります。

追加した権限に対して管理者の同意を与えます。ここは Azure AD のグローバル管理者の権限が必要になります。「構成されたアクセス許可」にある「テナント名に管理者の同意を与えます」を選択して、出てきた画面んで「はい」を選択して管理者の同意を与えてください。

同意を与えるとアクセス許可のリストの状態が緑のチェックマークに変わります。

Teams のアプリパッケージの作成

Company Communicator の GitHub のリポジトリにあるマニフェストファイルのひな形を使って、アプリケーションのパッケージを作成します。git を使える人はクローンして、git を普段使っていない人は https://github.com/OfficeDev/microsoft-teams-apps-company-communicator から以下の画面を参考に zip ファイルとしてダウンロードして解凍してください。

解凍したフォルダーの中にある Manifest フォルダーのなかにある 2 つの JSON ファイルを編集してアプリパッケージにします。

Author 用のアプリパッケージの作成

まず、メッセージを送る人が使うアプリのパッケージを作成します。Manifest フォルダーにある manifest_authors.json ファイルを任意のテキストエディターで開きます。可能であれば Visual Studio Code などの JSON のシンタックスハイライトをしてくれるようなエディターで開くとミスを防ぐことが出来ます。

まずは 7 行目から 12 行目の developer の項目にある name, websiteUrl, privacyUrl, termOfUseUrl を入力します。

変更前

  "developer": {
    "name": "<<companyName>>",
    "websiteUrl": "<<websiteUrl>>",
    "privacyUrl": "<<privacyUrl>>",
    "termsOfUseUrl": "<<termsOfUseUrl>>"
  },

ここは name は 32 文字以内の任意の文字列です。会社名や管理を行う部署名などでよいと思います。そのほかの 3 項目は URL です。それぞれウェブサイト、プライバシーポリシー、利用規約などのページの URL です。Company Communicator は社内で利用するケースがほとんどだと思うので、その場合であれば社内のイントラに任意のページを準備するだけで大丈夫だと思います。試験的に使うのであれば https://example.com/privacy のような URL でも大丈夫です。

変更後

  "developer": {
    "name": "Contoso 広報部",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com",
    "termsOfUseUrl": "https://example.com"
  },

17 行目から始まる name の項目は単なる表示名なので必要におうじて変更してください。21 行目からの description も概要を入力する項目なので必要に応じて変更してください。

ファイル内に 3 箇所 <<appDomain>> という文字列があるので、これをデプロイ後にメモをしたアプリケーションのドメインに置き換えてください。私の場合は kazukicc.azurefd.net に置き換えています。

そしてファイル内に 2 箇所 <<botId>> という文字列があるので、これを Company Communicator Author のアプリケーション ID で置き換えてください。

以上で manifest_author.json ファイルの編集は完了です。

次に manifest_author.json のコピーを作成して manifest.json に名前を変更します。manifest.json と color.png と outline.png の 3 つのファイルを選択して右クリックメニューから zip ファイルに圧縮します。圧縮した zip ファイルは company-communicator-authors.zip という名前に変更してください。

作成した zip ファイルを開いて以下のようにかならず zip ファイルの直下に manifest.json と color.png と outline.png の 3 つのファイルがあることを確認してください。

圧縮前の manifest.json は不要なので削除してください。

User 用のアプリパッケージの作成

次に User 用のアプリパッケージを作成します。Manifest フォルダーにある manifest_users.json ファイルを任意のテキストエディターで開きます。繰り返しになりますが、可能であれば Visual Studio Code などの JSON のシンタックスハイライトをしてくれるようなエディターで開くとミスを防ぐことが出来ます。

manifest_users.json も基本的には manifest_authors.json と同じように編集していきます。こちらはメッセージを受信する一般ユーザーに対してインストールされるものになるので、name や description は一般ユーザーが混乱しない内容にするのが良いと思います。

7 行目から 12 行目の developer の項目にある name, websiteUrl, privacyUrl, termOfUseUrl や 17 行目から始まる name や 21 行目から始まる description を変更した後に <<botId>> と <<appDomain>> の置き換えも行ってください。こちらのファイルには <<botId>> と <<appDomain>> は 1 箇所ずつしかありません。

こちらの <<botId>> には Company Communicator User のアプリケーション ID を指定します。

manifest_users.json の編集が終わったら manifest_user.json をコピーして manifest.json に名前を変更して color.png と outline.png とともに zip ファイルに圧縮します。そして company-communicator-users.zip という名前に変更してください。

Teams へのアプリケーションのインストール

以上でデプロイは終了です。後は Microsoft Teams へ先ほど作成した 2 つのパッケージをインストールするだけになります。この記事はデプロイが主目的なので、インストールに関してはポイントだけ解説します。

User 向けアプリのインストール

インストール方法は色々ありますが、Teams 管理センターからインストールさせたいユーザーに対してインストールをするように構成するのが一番確実です。その他にもメッセージ送信対象ユーザーに Company Communicator からインストールさせるプロアクティブインストールもあります。こちらはデプロイを行うところの手順で設定項目について触れているので確認してください。

Author 向けアプリのインストール

メッセージ送信者向けのアプリのインストールはチームにインストールを行います。メッセージ送信者向けのチームを作成して、そのチームの管理画面からアプリのインストールを行います。
zip を直接アップロードしても良いですし、Teams 管理センターに zip をアップロードしておいて、その他のアプリボタンからインストールでも良いです。

送信者の追加

注意点として、チームに参加しているメンバーでもデプロイ時に Sender UPN List の項目に指定していないユーザーはメッセージ送信のための画面が開けない点です。送信可能ユーザーを追加したい場合は、以下の手順でユーザーを追加してください。

この設定変更を行うとサーバーの再起動が行われるため、可能であればメッセージの配信が行われていない時間帯で実施してください。

Azure ポータルを開き Company Communicator をデプロイしたリソースグループを開く
種類が App Service のリソースを開く
構成の中のアプリケーション設定にある AuthorizedCreatorUpns を選択する
セミコロン区切りで送信者に追加したユーザーの UPN を設定して OK を選択する
保存を押して設定変更を反映する

保存時に再起動が行われるというメッセージが表示されますが、続行して設定変更を反映させてください。

まとめ

以上で Company Communicator のデプロイ手順のデプロイの一連の流れが完了です。Company Communicator は最初に書いた通り OSS で結構活発に更新が行われているため最新情報については以下の GitHub を参照してください。

Microsoft (有志)Publication

Microsoft Azureをはじめとする最新技術情報をお届けします。 ※このPublicationは日本マイクロソフトまたは米Microsoft所属社員による個人の見解であり、所属する組織の公式見解ではありません。 ※Publicationに参加希望の社員は @07JP27までご連絡ください。