Uncategorized

Azure AD (Entra ID) の Common Consent Framework – Client 側

By on • ( 13 Comments )

※ Azure AD v1 endpoint に関する内容です (v2 endpoint の場合は、こちら を参照してください)

開発者にとっての Azure Active Directory (Microsoft Entra ID)

こんにちは。

今回は、新機能「Common Consent Framework」と Multi-tenant 対応について紹介したいと思います。(実は、昨日、同僚から質問を受けましたので。。。)
この Common Consent Framework は、先日の SharePoint Conference における Office 365 API の発表と共に Microsoft Azure Active Directory (Azure AD) に実装されました。現在は、まだ Preview 版です。

これまで管理者があらかじめ Microsoft Azure Management Portal や Windows PowerShell を使って Application を登録していましたが、Common Consent Framework を使うと、Application 使用時に Consent UI を表示して権限設定を委譲 (Delegate) できます。Consent UI とは、Microsoft Account、Facebook、Twitter、Google など、昨今のインターネット アプリではお馴染みのアレですね。
例えば、下図は、Facebook の場合の Consent UI の例です。この例では、「Bing」という Facebook Application が、Facebook 上のユーザー (この場合、私) の公開プロフィールや友達リストの読み込み権限をユーザー (私) に要求しています。下図で [OK] を押すと、以降、この「Bing」という名前の Application は私の情報にアクセスできるようになります。

 

動作の概要

Azure AD の Common Consent Framework を構成する主な要素は、Application のマニフェスト (Manifest) と、各 Tenant における Application 権限 (Permission) です。

Application の提供者 (ISV など) は Application と共に Manifest を登録し、User Consent や Admin Consent などの Policy を設定します。

Application を使用する各 Tenant では、権限がない場合、この設定にしたがって Consent UI が表示され、利用者により権限の付与が可能になります。そして、権限付与されると、Microsoft Azure Active Directory Graph などにこの権限 (Permission) 情報が記録されます。(以降、権限が付与されている間は、Consent UI は表示されません。)

今回は、Common Consent Framework を使って Exchange Online の Mail の Read 権限を付与するサンプル アプリケーション (Client 側) を構築しますが、 Exchange Online のような Common Consent Framework に対応した Web API など (Service 側) も構築できます。(Service 側の構築方法については次回解説します。)

 

Permission の設定

補足 : 以降のサンプルでは Outlook REST API (https://outlook.office.com または https://outlook.office365.com) を使用しますが、Outlook REST API は 2022/11/30 に終了予定です。今後は Microsoft Graph (統一エンドポイント) を使用してください。

まずは、これまで通り、Microsoft Azure Portal で Active Directory の管理画面を開き、Tenant  に Application を追加します。(以降、この Tenant を「Tenant A」とします。)

作成した Application の管理画面を開き、[Required permissions] で [Office 365 Exchange Online] を追加し、下図の通り [Read user mail] にチェックを付けます。これにより、Permission が設定され、別テナントの利用者がこのアプリを使用する最に、上述のような Consent が表示されるようになります。(このため、この Permission をむやみにつけてしまうと、利用者に膨大な数の権限要求が Consent 上に表示されるので注意してください。)

こうした Application の設定を、マニフェスト (Manifest) と呼ばれるものを使用してカスタムに設定することもできます。

作成された Application の管理画面にある [Manifest] をクリックします。

表示されるテキストの下記の requiredResourceAccess の箇所に、下記の 2 番目の要素を追記します。以下では、上図同様に、Exchange Online の Mail の Read 権限を追加しています。(00000002-0000-0ff1-ce00-000000000000 が Exchange Online の resource id で、185758ba-798d-4b72-9e54-429a413a2510 が Mail.Read の permission id です。)
なお、あらかじめ設定されている下記の 1 つ目の権限 (resource id が 00000002-0000-0000-c000-000000000000 の権限) は、Azure Active Directory Graph (Graph API) の UserProfile.Read 権限です。

{
  "appId": "75b238e9-b26a-41a6-9b20-18237ac7e715",
  "appMetadata": {
    "version": 0,
    "data": []
  },
  "appPermissions": [],
  "availableToOtherTenants": false,
  "displayName": "SampleApp01",
  "errorUrl": null,
  "homepage": "http://localhost:9949/",
  "identifierUris": [
    "https://o365demo01.onmicrosoft.com/SampleApp01"
  ],
  "keyCredentials": [],
  "knownClientApplications": [],
  "logoutUrl": null,
  "passwordCredentials": [],
  "publicClient": null,
  "replyUrls": [
    "http://localhost:9949/"
  ],
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "requiredAppPermissions": [
        {
          "permissionId": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "directAccessGrant": false,
          "impersonationAccessGrants": [
            "User"
          ]
        }
      ]
    },
    {
      "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
      "requiredAppPermissions": [
        {
          "permissionId": "185758ba-798d-4b72-9e54-429a413a2510",
          "directAccessGrant": false,
          "impersonationAccessGrants": [
            "User"
          ]
        }
      ]
    }
  ],
  "resourceApplicationSet": null,
  "samlMetadataUrl": null,
  "webApi": null,
  "webApp": null,
  "notifications": [],
  "serviceEndpoints": [],
  "objectType": "Application",
  "objectId": "845cf0e4-8f97-42a6-a7ec-ecbbadc1dac4",
  "softDeletionTimestamp": null,
  "createdOnBehalfOf": null,
  "createdObjects": [],
  "manager": null,
  "directReports": [],
  "members": [],
  "memberOf": [],
  "owners": [],
  "ownedObjects": []
}

 

Multi-tenancy (マルチテナント) への対応

上記で準備が整いましたが、上記の設定だけではこのテナント内でしか使用できません。(別のテナントのユーザーがこのアプリケーションにアクセスしても Consent UI は表示されません。)
そこで、この Application を Multi-tenant 対応にするため、Microsoft Azure Portal で Application の [Properties] (プロパティ) をクリックして、[Multi-tenanted] を [Yes] に設定して保存しましょう。

補足 : multi-tenant の Application は、いったん Portal 上で single-tenant に変更した後でないと削除できないので注意してください。

 

User Consent

以上で準備完了です。

Consent UI を確認するために「Azure AD を使った API (Service) 連携の Client 開発」で紹介したようなアプリケーションをプログラミングしますが、今回はブラウザーを使って簡単に確認してみましょう。
なお、以下では Web Application の場合を例に解説します。

補足 : Azure AD に登録している Application が Web Application ではなく Native Application の場合、Permission の情報は Graph に登録されるのではなく、refresh token に登録されます。このため、Application がその refresh token を使用している間は Consent UI は表示されませんが、refresh token を取り直すと、再度、Consent UI が表示されます。
2016/03 追記 : Native Application も、一度、意思確認 (Consent UI の表示) がおこなわれると、以降は Azure AD Graph に Consent 情報が記録されるように仕様が変更されました。この仕様変更については「Azure AD Graph team blog : Azure AD will now record consent for mobile client apps」を参照してください。

ブラウザーで以下の URL に接続してみてください。Microsoft Azure Active Directory の Login 画面が表示されるので、上記とは異なる別の Tenant の ID でログインします。(以降、この Tenant を「Tenant B」とします。)
なお、下記で client_id には上記の Application の Client ID を設定します。今回は、resource id として「https://outlook.office365.com/」 (Exchange Online の REST API)、redirect_uri として「http://localhost:9949/callback」を設定しています。

https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=75b238e9-b26a-41a6-9b20-18237ac7e715&resource=https%3a%2f%2foutlook.office365.com%2f&redirect_uri=http%3a%2f%2flocalhost%3a9949%2fcallback

認証に成功すると、通常は、http://localhost:9949/callback?code=… の形式で authorization code が返されますが、今回は、ログインをおこなうと、まず、以下の User Consent の UI が表示されるはずです。
そして、下図で [OK] ボタンを押すと、http://localhost:9949/callback?code=… のフォーマットで code が返されます。

以降は、「Azure AD を使った API (Service) 連携の Client 開発」と同様の OAuth のフローで Access Token を取得し、Office 365 API を使って Exchange Online の Mail の読み込み (Read) ができます。今回は、この手順の解説は省略します。

ユーザーは下記にアクセスすることで、Facebook, Twitter, Microsoft Account などと同様、Permission 許可された App をあとから削除できます。

https://myapplications.microsoft.com/

 

Administrator Consent

Consumer アプリの場合は上述のような User Consent のシナリオが向いていますが、Enterprise アプリの場合には、一般に組織の管理者がこの権限設定を代行するのが自然でしょう。Common Consent Framework では、こうした Admin Consent にも対応しています。

今度は、いったんブラウザーをすべて閉じてから、再度 ブラウザーを開きなおし、下記の URL に接続してみてください。
上述の URL に「prompt=admin_consent」を追加しただけです。

https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&prompt=admin_consent&client_id=75b238e9-b26a-41a6-9b20-18237ac7e715&resource=https%3a%2f%2foutlook.office365.com%2f&redirect_uri=http%3a%2f%2flocalhost%3a9949%2fcallback

ログインの際は、Global Administrator のユーザーでログインしてください。(上記同様、Tenant B にログインします。)
ログインをおこなうと、今度は、以下の Consent UI が表示されます。ここには、「この設定は、組織のすべてのユーザーに適用されます」と書かれているのがお分かり頂けるでしょう。

つまり、この Tenant B のすべての User にアクセス権が付与されます。

なお、管理者が、Tenant (Directory) 内の一般ユーザーによる Consent の抑制 (禁止) をおこなうには、Windows PowerShell (「Azure Active Directory とは (事前準備)」を参照) を使って以下の通り入力するか、[User settings] メニューを選択して表示される画面で [Users can consent to apps accessing company data on their behalf] を No に設定します。

Set-MsolCompanySettings -UsersPermissionToUserConsentToAppEnabled:$false

補足 : Application 側でも User Consent を抑制できます。この方法は「Azure Active Directory の Common Consent Framework (Service 側)」に記載しましたので参照してください。
また、各アプリケーションごとの [User assignment required] をオンして、(管理者が) 特定の利用者のみアプリケーションを使えるように設定できます。

補足 : 上図の [Users can register applications] では、組織内の一般ユーザーがこの Azure Portal (Azure Active Directory の管理画面) を使って開発中のアプリを登録できるか否かを制御できます。

なお、Admin Consent で追加されたアプリケーションの権限をテナントから剥奪 (削除) するには、単に Azure Portal にログインしてアプリケーションを削除すれば OK です。

 

※ 変更履歴 :

2017/05/26  画面を新ポータル (https://portal.azure.com) に変更

 

Categories: Uncategorized

Tagged as: , ,

13 replies »

  1. I’m now not sure where you’re getting your information,
    however great topic. I must spend some time learning much more or understanding more.
    Thank you for great information I used to be in search
    of this information for my mission.

    Like

    Reply

  2. Great post, I conceive blog owners should acquire
    a lot from this web site its very user friendly. So much wonderful information on here
    :D.

    Like

    Reply
  3. Pingback: Office 365 API 入門 – tsmatz
  4. Pingback: Office 365 API : JavaScript Library for Cordova – tsmatz
  5. Pingback: Outlook REST API 開発 (Outlook.com 対応も) – tsmatz
  6. Pingback: yammer App の Programming – tsmatz
  7. Pingback: Power BI REST API を使ったデータ連携 – tsmatz
  8. Pingback: [Skype] UCWA (Unified Communications Web API) 開発入門 – tsmatz
  9. Pingback: Skype Web SDK 紹介 – tsmatz
  10. Pingback: Azure AD で Custom Branding の Login UI を初期表示する (Home Realm Discovery, Domain Hint の使用) – tsmatz
  11. Pingback: Azure Active Directory の SSO 開発 (Node.js 編) – tsmatz
  12. Pingback: Azure Active Directory の SSO 開発 (PHP 編) – tsmatz
  13. Pingback: Office 365 File Handler (カスタム ファイルのプラグイン) – tsmatz

Leave a Reply