MicrosoftのOAuth2.0連携機能の開発を振り返る

こんにちは、株式会社ACESでソフトウェアエンジニアをしている村上 (@d_murakami_0816) です。

ACES は、オンライン会議を録画し、独自 AI による話者ごとの自動文字起こしや重要なシーンの可視化を行うことで、オンライン商談における成約率の向上と現場の工数削減に寄与する商談解析 AI ツール「ACES Meet」を提供しています。今回はACES Meetで提供しているMicrosoft IDプラットフォームとの連携機能 (以下Microsoft連携) について、実装に至った背景と実装の際に苦労した部分についてこの場を借りて振り返りたいと思います。今後同様に連携機能を開発する方の助けになれば幸いです。

Microsoft連携の前提知識
Microsoft連携をなぜ実装したか
Microsoft連携を実装するにあたって苦労した部分
まとめ
参考サイト

Microsoft連携の前提知識

Microsoft連携はOAuth 2.0の認証フローを用いて実現しています。OAuth 2.0の認証フローについてはRFC 6749のドキュメントをご参照ください。 (内容はこちらで翻訳されているのでこちらもご参照ください)

OAuth認証にはその認証方法で大きく分けて以下の4つのフローが存在しています。

Authorization Code Grant
Client Credentials Grant
Implicit Grant
Resource Owner Password Credentials Grant

今回のMicrosoft連携ではこのうち、Authorization Code Grant, Client Credentials Grantを扱っています。

Microsoft連携をなぜ実装したか

ACES Meetはオンラインで行った会議の情報を取得して、解析を行いその結果を提供するサービスになっています。したがってまず機能を利用するためにオンラインで行った会議の情報を取得する必要があります。

ACES Meetは初期リリース時、ZoomのAPIを用いてZoomで行った会議に対して上記のような解析機能を提供していました。しかし、その中で2つの課題がありました。

ACES Meetで作成した会議をMicrosoft Outlookに反映させてスケジュール管理できるようにしたい
Microsoft Teamsで行なった会議を録画できるようにしたい

Microsoft Teams (以下Teams) やMicrosoft Outlook (以下Outlook) は日本国内で見ても利用率が高く、ACES MeetとしてもTeamsを利用するユーザーもACES Meetの機能を利用できるようになることや、Outlookを利用しているユーザーがよりACES Meetを使いやすくなることは今後サービスを多くの方にご利用いただくには必要不可欠となっていました。

そういった背景から今回Microsoft連携を実装することを決定しました。

Microsoft連携を実装するにあたって苦労した部分

Microsoft連携を実装することが決まったものの、弊社では普段社内会議・商談ともにZoomの利用が主となっており、Microsoft環境についての知見はほとんどない状態でした。そんな状態から公式のドキュメントを参考に実装を進めていくわけですが、当然多くの壁にぶつかることとなりました。今回はその中でも特に大変だったものについていくつかピックアップしてみました。これからMicrosoft連携を実装する方の参考になれば幸いです。

①ドキュメントが膨大かつ用語が複雑

Microsoftのドキュメントは非常に内容が多く、かつ複雑です。Microsoftの歴史を考えれば当然のことだと思います。知りたい情報だけを得ようとしてもその説明を理解するために別のページを開くみたいなことが繰り返され、気がつくとタブがMicrosoftのドキュメントだらけになります。

一方で体系的に情報を取得しようとしてもどこを見れば知りたい情報に繋がっているのか最初はなかなかわからないです。

Microsoftのドキュメントトップページ

Microsoftのドキュメントを開くとこのようなトップページが出てきます。これだけでもサービスの多さを感じます。Microsoft連携はAzure ADを通して行われるのでAzureを選択します。

Azureのドキュメントトップページ

大分数が絞れてきたので探しやすくなると思ったのですが、この中にAzure ADがありません。ここに出ているのは「基本」の製品のみなのでAzure ADは出てきていないようです。なのでここからAzure ADを探すことになります。連携機能に関係するので「開発者ツール」、ユーザーに連携機能の許可を出したりするので「管理とガバナンス」、サービス間の通信やMicrosoft内のリソースを扱うので「ネットワーク」や「セキュリティ」など思いつく項目から探していくと、

AzureのドキュメントでIDを選択した場合

「ID」の中で見つかります。連携機能を実現する際にAzure ADから操作することが多いのですが、Azure ADそのものは「Azure Active Directory (Azure AD) は、クラウドベースの ID およびアクセス管理サービスです。」とAzure ADの説明にある通り、ID管理の製品になります。このAzure ADのドキュメントからMicrosoft IDプラットフォームのドキュメントに遷移することでやっと連携機能の実装に必要な情報に辿り着くことができます。

このようにドキュメントが膨大なので必要な情報に辿り着くのに非常に苦労しました。自分の主観になりますが、今後Microsoft連携を実装する方に向けて特に読んでおくべき記事をいくつかピックアップしたので参考にしていただければと思います。

Azure Active Directory のアプリケーションオブジェクトとサービスプリンシパルオブジェクト

Azure ADに関連する説明で多く出てくる「アプリケーション」や「サービスプリンシパル」といった単語についてその意味を説明しています

Microsoft ID プラットフォームと OAuth 2.0 認証コードフロー

Authorization Code Grantについて一通りの流れが記載されています

Microsoft ID プラットフォームと OAuth 2.0 クライアント資格情報フロー

同様にClient Credentials Grantについて一通りの流れが記載されています

②アクセス許可の種類による連携フローの違い

Microsoft連携を実現するにあたってAzure AD上でアクセス許可を設定するのですが、このときにアクセス許可の種類に「委任されたアクセス許可」と「アプリケーションの許可」の2つが存在します。

Azure ADのアクセス許可の画面

説明だけではあまりイメージが掴めなかったので「委任されたアクセス許可」と「アプリケーションの許可」についてドキュメントを探してみたのですが、こちらもなかなか見つかりません。

サポートの方などに問い合わせをする過程でわかったのですが、「委任されたアクセス許可」がAuthorization Code Grantと、「アプリケーションの許可」がClient Credentials Grantとそれぞれ対応づけされているようでした。

その情報を元にドキュメントを確認すると、Client Credentials Grantの説明の方に「アプリケーションの許可」に関する記載がありました。

ここに関してはドキュメントからなかなか辿れなかったのもあり、情報が結びつかずかなり苦戦した箇所になりました。

③Authorization Code Grantの管理者による同意

Authorization Code Grantは基本的にユーザーによってリソースへのアクセスに同意する形になっていますが、Azure ADではユーザーから同意する代わりに管理者が一括で同意するということが可能になっています。加えてユーザーからの同意を禁止して管理者しかリソースへのアクセスに同意できないようにする設定も存在しています。

この設定自体は問題ないように思えるのですが、OIDCの仕様と合わせたときに直感的ではない挙動がありそこでハマることになりました。

OIDCでは最初にユーザーに同意を要求する際にpromptという値を設定することができます。これは一度同意を行なったユーザーであっても連携時に再度同意を要求するという設定になります。一方でAzure ADではユーザーからの同意を禁止できるので両方の設定が有効になっていると「ユーザーから同意はできないのに毎回ユーザーの同意が要求される」という状態が発生し連携できなくなってしまうという問題がありました。

管理者の同意がうまくいかないように映るのでなかなか連携時の設定の方に思考がいかず、こちらもかなりハマることになりました。

(サポートの方に問い合わせたときに紹介していただいたのですが、サポートブログというものがあるらしく、そこにこの件についての記載がありました。当時はサポートブログの存在を知らなかったのでなかなか見つけるのは難しかったのですが、上手く検索できていれば辿り着けたのかなと思っています。)

また、この設定自体もClient Credentials Grantと混同しやすいので注意が必要になります。

どちらも管理者から同意を行うという点は同じなのですが、以下のように違いがあるので注意した上で必要なフローを選択していただくのが良いと思います。