こんにちは。

今回は Tips 的な話題ですが、多くのお客さまから ご質問いただくので解説しておきます。

Custom Branding (Custom SignIn UI) とその動き

有償版の Azure Active Directory (Azure AD) Basic または Premium では、SignIn UI をカスタマイズできる Custom Branding が使えます。
Azure AD が既定で提供する UI ではなく、企業や学校のロゴなどを入れた独自の UI を表示することで、統一感のある Experience の元で Application を使えます。

補足 : この Custom Branding は、もちろん、Office 365 でも可能です。(Paul Andrew が書いた Office Blog「Sign in page branding and cloud user self-service password reset for Office 365」を参照してください)

この Custom Branding は、Multi Tenant 対応の Application の SignIn の際は、通常、下記の通り動作します。

まず、最初に WS-Fed, SAML, OpenID Connect (または OAuth 2) のエンドポイントにアクセスした際、ログインするユーザーがどの組織 (Directory) に属するか不明であるため、特定 Directory に対する Custom Branding は表示されず、Azure AD の既定の SignIn UI が表示されます。

そして、上図で、Custom Branding の設定された Directory (テナント) の Account 名を入力した際に、はじめて、Custom Branding の SignIn UI が下図の通り表示されます。

つまり、事業者 (企業など) が利用者にサービスを提供している場合にも、いったん上図のように、サービス事業者とは無関係な Microsoft (Azure AD) が提供する SignIn UI (画面) が表示されます。
このため、最初から Custom Branding の UI を表示したいという要望をよく聞きます。

結論から書くと、この方法については、Active Directory Team Blog「Using Azure AD to land users on their custom login page from within your app」に紹介されています。
本投稿では、この投稿を参考に、以下に、注意点や実際の手順 (コード) などをメモしておきます。(日本語抄訳ではありません。)

その前に ～ その Branding、本当に必要ですか ?

まず要望にお答えする前に、Azure AD が想定している利用方法などを理解し、本当にこうした Branding が必要か再検討してみてください。(過度に、この Branding に期待しすぎないようにしてください。)

Azure Active Directory (Azure AD) は、Google アカウントや Facebook アカウントのような特定アプリ (Google アプリや Facebook そのもの) の利用を前提としたアイデンティティ基盤ではなく、皆さんの組織 (企業、学校など) のユーザーを管理するために、皆さんの組織自身で管理 (運用) することを想定して設計されています。(アプリとして何を使うかは、皆さんの組織に任されます。)
そして、Office 365 などの爆発的普及で、事実として、既に膨大な数の Azure AD の組織 (Directory) と Account が使われていることを理解しておいてください。(Business Insider「Everyone is talking about how Microsoft Office 365 is suddenly beating Google Apps」を参照)
さらに、今後は、Windows とも連携することで、ますますその傾向は強くなるでしょう。(富士榮さんのブログ「IdM 実験室」 を参照。今後、MS からも積極的に情報発信されると思います。)

例えば、あるアプリが Facebook アカウントを使う場合 (例えば、Facebook アカウントで SlideShare やニュース キュレーションなどのアプリを使う場合)、わざわざアプリにログインするための専用の Facebook アカウントを登録させるのではなく、既に利用者が持っている Facebook アカウントを使うよう促すでしょう。そこには、「多くの人が既に Facebook アカウントを使っているであろう」という前提があります。Azure AD についても同様です。
Azure AD を使用する際に、事業者が提供する Directory で Account を自前で管理し、その延長として「自分達の Branding に統一したい」という要望を受けることがありますが、こうした現実を踏まえ、特に企業向けのアプリケーションの提供者は、アカウント管理を自前でおこなうべきか、もう一度検討してみてください。

本来、アプリを提供する ISV 側はアプリの Branding のみをおこない、上述の Custom Branding は、組織側 (アプリを使う企業側や学校側) で使用することを想定しています。
アカウント自体の管理 (アカウント作成など) は所属組織 (企業、学校など) に任せるか、アプリの作り方によっては、組織ごとで管理しているアカウント (Azure AD の組織アカウント) とアプリ固有のアイデンティティ管理の双方を組み合わせるハイブリッドなアプローチ (下図のような UI) も考慮してみてください。(例えば、ASP.NET Identity の既定のテンプレートが このアプローチを採用しています)

(SignUp Button や SignIn Button の Branding Guideline については「Branding Guidelines for Applications」を参照)

例えば、ベンダー中立なある派遣会社では、全国の派遣職員向けのサービス（3rd party の Multi-tenant アプリを含む）を提供する際に、自分達の企業 (会社) の Branding で統一するケースが考えられます。
今回紹介する方法は、このような場合に使用することを想定しています。

Single Tenant (Directory) の Application

単一 Directory (Single Tenant) のみを対象にした Application の場合には、通常、下記の通り URI の一部として Home Realm を使用します。(下記は WS-Fed の例です。)

https://login.microsoftonline.com/sampledir.onmicrosoft.com/wsfed?wa=wsignin1.0&...

この Directory (上記の sampledir.onmicrosoft.com) に対し Custom Branding を設定した場合は、最初から Custom Branding が適用された SignIn UI が表示されるので何もおこなう必要はありません。

例えば、「Azure Active Directory の SSO 開発 (Visual Studio 2013 編)」で紹介した WIF を使った構築で、下図の通り [クラウド – 単一の組織] (Cloud – Single Organization) を選択した場合は、上記のような URI が使用されます。(最初から Custom Branding が有効になった SignIn UI が表示されます。)

一方、Multi-tenant (Multiple Directory) 対応の Application の場合には、下記の通り「common」が使用されるため、後述の通り、Realm Discovery や Domain Hint を使う必要があります。

https://login.microsoftonline.com/common/wsfed?wa=wsignin1.0&...

以降では、こうした Multi-tenant アプリについて解説したいと思います。

WS-Fed (in Multi Tenant App)

まず、WS-Fed (WS-Federation) の Multi Tenant Application の場合は、下記の通り whr (WS-Fed Home Realm Discovery) を付与することで、Custom Branding による SignIn UI を初期表示できます。

https://login.microsoftonline.com/common/wsfed?wa=wsignin1.0&whr=sampledir.onmicrosoft.com&...

実際の設定方法は使用するライブラリーなどに依存します。
例えば、「Azure Active Directory の SSO 開発 (Visual Studio 2013 編)」で紹介した WIF を使った構築で [クラウド – 複数の組織] (Cloud – Multiple Organizations) を指定した場合は、[SignIn] ボタンを押した際の処理 (AccountController の SignIn メソッド) に下記の通り追加の Parameter を設定することで、Home Realm Discovery が有効になり、Custom SignIn UI が表示されます。

. . .public class AccountController : Controller{  public ActionResult SignIn()  {    if (Request.IsAuthenticated)    {      return RedirectToAction("Index", "Home");    }    WsFederationConfiguration config =      FederatedAuthentication.FederationConfiguration.WsFederationConfiguration;    string callbackUrl = Url.Action("Index", "Home", routeValues: null, protocol: Request.Url.Scheme);    SignInRequestMessage signInRequest = FederatedAuthentication.WSFederationAuthenticationModule.CreateSignInRequest(      uniqueId: String.Empty,      returnUrl: callbackUrl,      rememberMeSet: false);    signInRequest.SetParameter("wtrealm", IdentityConfig.Realm ?? config.Realm);    signInRequest.SetParameter("whr", "sampledir.onmicrosoft.com");    return new RedirectResult(signInRequest.RequestUrl.ToString());  }  . . .

SAML (in Multi Tenant App)

SAML の場合、Request は Deflate + Base64 Encoding + URL Encoding の文字列として、下記太字の通り渡されます。

https://login.microsoftonline.com/common/saml2?SAMLRequest=fZJPi9swEMW%2FitFdsa...

この文字列を Decode すると、下記のような SAML Assertion が入っています。

<samlp:AuthnRequest ...>  <saml:Issuer>spn:ca8f44d4-2784-43e5-b7da-32f90eb4aaaf</saml:Issuer>  <samlp:NameIDPolicy    Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"    AllowCreate="true"/></samlp:AuthnRequest>

この Request (SAML Assertion) に、下記太字のような IDPList の Scoping を設定することで、Custom Branding が有効になった SignIn UI が初期表示されます。

<samlp:AuthnRequest ...>  <saml:Issuer>spn:ca8f44d4-2784-43e5-b7da-32f90eb4aaaf</saml:Issuer>  <samlp:Scoping>    <samlp:IDPList>      <samlp:IDPEntry        ProviderID="https://sampledir.onmicrosoft.com"        Name="sampledir.onmicrosoft.com"/>    </samlp:IDPList>  </samlp:Scoping>  <samlp:NameIDPolicy    Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"    AllowCreate="true"/></samlp:AuthnRequest>

この指定方法も使用する Library に依存しますので、Library のリファレンスを参照してください。

補足 :「Azure Active Directory の SSO 開発 (PHP 編)」で解説した simpleSAMLphp でも IDPList (Scoping) の指定は可能ですが、上記の Name 属性 (Optional) に対応していないため、残念ながら不可能です。。。

OAuth 2, OpenID Connect (in Multi Tenant App)

OpenID Connect (および、そのベースとなる OAuth 2) では、下記太字の通り domain_hint を付与します。

https://login.microsoftonline.com/common/oauth2/authorize?client_id=920f104d-f199-4dc7-a66a-1b492ae57876&domain_hint=sampledir.onmicrosoft.com&...

この場合も、設定方法はライブラリーに依存します。
例えば、Active Directory Authentication Library (ADAL) を使用する場合、下記の通り Extra Query Parameter に追記します。(下記では ADAL 2.0 を使用しています。)

注意 (追記) : 今後は ADAL ではなく MSAL (Microsoft Authentication Library) を使用してください。(ADAL は 2020 年 6 月にサポート終了予定です。)

. . .AuthenticationContext context =  new AuthenticationContext("https://login.microsoftonline.com/common");AuthenticationResult assertion = context.AcquireToken(  "https://localhost/myservice",  // resource  "32f3e42d-ab1e-4043-b23d-...",  // client id  new Uri("https://localhost/"), // redirect uri  PromptBehavior.Always,  // prompt behavior  UserIdentifier.AnyUser, // user identifier  "domain_hint=mydomain.com"); // Extra Query Parameters. . .

なお、いずれまた紹介しますが、Visual Studio 2015 (現在 Preview) では、[認証の変更] (Change Authentication) ボタンで組織アカウント (Azure AD) の設定をおこなうと、OWIN を使用した OpenID Connect の設定がおこなわれます。(Visual Studio 2013 では、上述の通り WIF を使用した WS-Fed でした。)
この場合は、App_Start/Startup.Auth.cs に下記太字の通り Domain Hint を設定 (追加) します。

. . .app.UseOpenIdConnectAuthentication(  new OpenIdConnectAuthenticationOptions  {    ClientId = ClientId,    Authority = Authority,    TokenValidationParameters = new System.IdentityModel.Tokens.TokenValidationParameters    {      ValidateIssuer = false,    },    Notifications = new OpenIdConnectAuthenticationNotifications()    {      RedirectToIdentityProvider = (context) =>      {        context.ProtocolMessage.DomainHint = "sampledir.onmicrosoft.com";        return Task.FromResult(0);      },      SecurityTokenValidated = (context) =>      {        return Task.FromResult(0);      } ,                AuthenticationFailed = (context) =>      {        context.OwinContext.Response.Redirect("/Home/Error");        context.HandleResponse();        return Task.FromResult(0);      }    }  });. . .

About Bookmark / Redirect (in Multi Tenant App)

アプリケーション提供者 (ISV) がこうした Multi-Tenant (複数組織) 対応のカスタム アプリケーションを構築する際は、Domain ごとに URL を分けておくことで、利用者 (ユーザー) が Browser の Bookmark などに URI を設定した場合でも、Domain Hint (または Home Realm Discovery) を維持できます。
例えば、https://sampleapp.com/sampledir.onmicrosoft.com にアクセスした場合には Domain Hint として「sampledir.onmicrosoft.com」を付与してログインさせるといった具合です。

なお、Office 365 (Exchange, SharePoint など) では、OWA (Outlook Web App) がこのアプローチをとっています。(一方、残念ながら、SharePoint Online は対応していません。)
OWA では、https://outlook.office365.com にアクセスした場合には whr は付与されませんが、https://outlook.office365.com/sampledir.onmicrosoft.com や https://outlook.office365.com/owa/?realm=sampledir.onmicrosoft.com にアクセスした場合は whr (Home Realm Discovery) が付与されます。

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

なお、普段、特定の組織 (Directory, Tenant) で使用しながら、別の組織 (Directory, Tenant) のユーザーを招待するようなケース (シナリオ) でも上記の手法は使えますので安心してください。(SignIn UI で別のドメインの Account 名を入力すると、再度、Branding は解除されます。)
せっかくある Custom Branding の仕組みですので、是非有効活用してみてください。