Microsoft と Google を接続する

接続の仕組み

• プロバイダーとモード。 provider は microsoft または google です。mode は、独自の Microsoft Entra アプリまたは Google サービスアカウントを使う own_app、あるいは screenRIG のアプリを使う screenrig_app で、後者は Microsoft 365 の管理者または Google アカウントの所有者が承認します。
• ステータス。 接続は、誰かが screenRIG のアプリを承認するまで pending_consent で待機します。直近の試行で拒否されなかった認証情報を保持している間は ready、Microsoft や Google に拒否されたときは error になります。理由は last_error に示され、その後に成功すると ready に戻ります。スロットリングや障害では何も変わりません。
• シークレットは封印されたままです。 シークレット、キー、更新トークンは二度と表示されません。読み取りでは、保存されているかどうかと、ヒントとして Microsoft のクライアントシークレットの末尾 4 文字、または Google サービスアカウントのアドレスが示されます。
• テストする。 テストはサインインして結果を保存します。Microsoft では、取得したトークンが持つ Graph のアプリケーション権限も一覧表示します。
• 変更する。 独自のアプリの認証情報を変更すると、接続は ready に戻り、直近のエラーが消えます。screenRIG のアプリモードの接続は名前の変更しかできません。承認した人を変えるには、新しい同意リンクを依頼してください。
• 削除する。 ソース、Power BI 接続、メディア同期アカウントがその接続を通じて読み取っている間は、削除できません (resource_conflict)。削除してもベンダー側のアクセスは終わりません。テナントは管理者が削除するまで screenRIG のアプリを保持し、Google アカウントは所有者が取り消すまで許可を保持します。
• 上限。 組織は、すべてのプロジェクトを合わせて最大 50 件の接続を持てます。

独自のアプリか screenRIG のアプリか

Microsoft

独自のアプリ

Microsoft Entra 管理センターでアプリを登録し、クライアントシークレットを追加して (ID ではなく値をコピーします)、アプリに下記のアプリケーション権限を付与し、管理者の同意を与えます。接続は、ディレクトリ ID またはプライマリドメインを config.tenant_id に (common、organizations、consumers は拒否されます)、アプリケーション ID を config.client_id に、クライアントシークレットの値を secret に指定して作成します。

screenRIG のアプリ (管理者の同意あり)

設定もシークレットも指定せず、モード screenrig_app で接続を作成します。応答には、24 時間有効な 1 回限りのリンク consent_url が含まれます。これを Microsoft 365 の管理者だけに送ってください。このリンクは、その 1 回の同意の認証情報だからです。

1. 管理者がリンクを開き、テナントに対して screenRIG のアプリを承認します。
2. Microsoft が screenRIG に戻り、screenRIG は管理者にそのテナントへのサインインを求めます。接続には、サインインしたテナントが記録され、リクエストが主張するだけのテナントは記録されません。
3. screenRIG は、付与された権限でテナントに 1 回サインインします。接続は ready になります。

リンクは 1 回しか使えません。新しいリンクの発行、同意の完了、削除のいずれかで、古いリンクは無効になります。新しいリンクはいつでも依頼でき、error になった接続の更新や、別のテナントへの付け替えに使えます。管理者が拒否した場合やサインインが完了しなかった場合、接続は consent_denied または consent_failed (Microsoft の AADSTS コード付き) を記録し、保留中の同意を保つので、同じリンクをもう一度開けます。すでに動いている接続が、2 回目の同意の拒否で劣化することはありません。テナントが screenRIG のアプリを削除すると、接続は consent_revoked になります。管理者に再度承認を依頼してください。

承認はテナント単位です。管理者が screenRIG のアプリを一度承認すると、そのテナントにサインインできる人なら誰でも、自分のプロジェクトにそのテナントを接続できます。そのため、下記のようにアプリが読み取れる範囲を絞ってください。Microsoft Entra でエンタープライズアプリケーションを削除すると、すべてのプロジェクトのアクセスが終了します。

アプリが読み取れる範囲

接続テストは、サインインで得たトークンがこれらのうちどの権限を持つかを一覧表示します。Sites.Selected だけを持つ場合は、各サイトに許可が別途必要なため警告し、どれも持たない場合は失敗します。

Google

独自のアプリ

Google Cloud でサービスアカウントを作成し、Google Calendar API を有効にして、その JSON キー (16 KiB まで) をダウンロードします。ファイル全体を secret として接続に渡してください。screenRIG は保存時に検証します。そのうえで、各会議室のカレンダーをサービスアカウントのアドレスと共有するか、管理コンソールでそのアカウントにスコープ https://www.googleapis.com/auth/calendar.events.readonly のドメイン全体の委任を有効にし、ソースに subject を指定します。

screenRIG のアプリ

同意リンクは Google の同意画面を開きます。アカウントの所有者は、カレンダーイベントへの読み取り専用アクセス (スコープ calendar.events.readonly。screenRIG が承認したアカウントを知るために openid と email も) を許可します。カレンダーの権限のチェックを外すと、同意は失敗します。ソースはそのアカウントが見られるカレンダーを読み取るため、アカウントはソースに挙げたすべての会議室カレンダーを見られる必要があり、こうした接続のソースでは subject を指定できません。Google が許可を受け付けなくなると、接続は reconnect_required になります。新しいリンクを依頼してください。

接続を使う

• 会議室ソース。 microsoft365 または google_calendar のソースで、tenant、client_id、client_secret (または service_account_key) の代わりに connection_id を設定します。どちらのモードも使えます。インラインの認証情報も引き続き使えますが、connection_id と併用はできません。
• SharePoint と OneDrive のメディア同期。 Microsoft 365 の同期アカウントは、tenant_id、client_id、secret の代わりに connection_id を受け付けます。
• Power BI。 Power BI 接続は、独自のテナント、クライアント ID、シークレットの代わりに、モード own_app の Microsoft 接続の connection_id を受け付けます。Microsoft は、別のテナントのアプリが顧客のテナントで埋め込みトークンを生成することを説明していないため、Power BI では screenRIG のアプリは使えません。Power BI の管理者は、引き続きサービスプリンシパルの設定を有効にし、各ワークスペースにアプリを追加する必要があります。

接続が見つからない、承認待ち、または別のプロバイダーのものであるソースは config_invalid を返します。Microsoft や Google がサインインを拒否すると、ソースは auth_failed を返し、接続は error になります。

作成する

接続は、ダッシュボードか POST /api/connections で作成します。独自の Microsoft アプリの場合:

{
  "provider": "microsoft",
  "mode": "own_app",
  "name": "Contoso rooms",
  "config": {"tenant_id": "contoso.com", "client_id": "CLIENT_ID"},
  "secret": "CLIENT_SECRET_VALUE"
}

screenRIG のアプリの場合 (設定もシークレットもなし):

{"provider": "google", "mode": "screenrig_app", "name": "Campus rooms"}

2 つ目への応答には consent_url と consent_expires_at が含まれます。リンクは承認する人に送ってください。POST /api/connections/ID/connect は新しいリンクを作成し、POST /api/connections/ID/test はサインインして結果を保存します。シークレットはコマンドラインではなく、リクエストファイルに入れてください。

connection_app_not_configured は、そのプロバイダー用の screenRIG のアプリがサーバーにないことを意味します。独自のアプリで接続を作成してください。connection_limit_reached は、組織がすでに 50 件持っていることを意味します。どこからも読み取られていないものを削除するか、既存の接続を再利用してください。

関連

• データソース: 接続を使う会議室ソース。
• API リファレンス: 接続のすべてのルート。
• シングルサインオン: 人がサインインする方法。接続は、誰もサインインしていなくても動く作業のためのものです。