Transcription

spine .6388”Active Directory has been transformed to reflect the cloud revolution, modern protocols, and today’s newest SaaS paradigms. Thisis an authoritative, deep-dive guide to building Active Directoryauth en tication solutions for these new environments. Author VittorioBertocci drove these technologies from initial concept to generalavailability, playing key roles in everything from technical design todocumentation. In this book, he delivers comprehensive guidancefor building complete solutions. For each app type, Bertocci presentshigh-level scenarios and quick implementation steps, illuminateskey concepts in greater depth, and helps you refine your solutionto improve performance and reliability. He helps you make sense ofhighly abstract architectural diagrams and nitty-gritty protocol andimplementation details. This is the book for people motivated tobecome experts.Active Directory Program Manager Vittorio Bertoccishows you how to: Address authentication challenges in the cloud or on-premises Systematically protect apps with Azure AD and AD Federation Services Power sign-in flows with OpenID Connect, Azure AD, and AD libraries Make the most of OpenID Connect’s middleware and supportingclasses Work with the Azure AD representation of apps and theirrelationships Provide fine-grained app access control via roles, groups, andpermissions Consume and expose Web APIs protected by Azure AD Understand new authentication protocols without reading complexAbout This Book For architects, application designers,developer leads, and security consultants involved in authentication, accesscontrol, or personalization For security and protocol experts whowant to understand how Azure AD usesopen protocols to perform its functions For web developers and users of ASP.NETOWIN and the Active Directory Authentication Library (ADAL)About the AuthorVittorio Bertocci is a Microsoft PrincipalProgram Manager responsible for developer experience related to identity services, both on premises and in the cloud.As Architect Evangelist at Microsoft, hespent several years helping major enterprises build advanced identity solutionsbased on new Microsoft technologies.He frequently speaks at internationalevents such as TechEd, PDC, Build, andIgnite, and he blogs on identity topics at www.cloudidentity.com. His booksinclude Programming Windows IdentityFoundation.Get code samples, includingcomplete apps, at:http://aka.ms/modauth/filesBertoccispec documentsMicrosoftPressStore.comISBN 978-0-7356-9694-55 3 9 9 9Modern Authentication with AzureActive Directory for Web ApplicationsBuild advanced authentication solutions for anycloud or web environmentU.S.A. 39.99Canada 49.99ModernAuthentication withAzure Active Directoryfor Web ApplicationsForeword by Mark E. RussinovichChief Technology Officer, Microsoft AzureProfessionalModern Authentication with AzureActive Directory for Web Applications[Recommended]9780735 6969459780735696945 ModernAuth cover.indd 1Web developmentCelebrating over 30 years!Vittorio Bertocci11/30/2015 8:44:34 AM

Modern Authenticationwith Azure ActiveDirectory for WebApplicationsVittorio BertocciModernAuth PrintBook Final.indb i11/28/2015 11:39:41 AM

PUBLISHED BYMicrosoft PressA Division of Microsoft CorporationOne Microsoft WayRedmond, Washington 98052-6399Copyright 2016 by Vittorio Bertocci. All rights reserved.No part of the contents of this book may be reproduced or transmitted in any form or by any means withoutthe written permission of the publisher.Library of Congress Control Number: 2014954517ISBN: 978-0-7356-9694-5Printed and bound in the United States of America.First PrintingMicrosoft Press books are available through booksellers and distributors worldwide. If you need support relatedto this book, email Microsoft Press Support at [email protected] Please tell us what you think of thisbook at http://aka.ms/tellpress.This book is provided “as-is” and expresses the author’s views and opinions. The views, opinions and informationexpressed in this book, including URL and other Internet website references, may change without notice.Some examples depicted herein are provided for illustration only and are fctitious. No real association orconnection is intended or should be inferred.Microsoft and the trademarks listed at www.microsoft.com on the “Trademarks” webpage are trademarks of theMicrosoft group of companies. All other marks are property of their respective owners.Acquisitions and Developmental Editor: Devon MusgraveProject Editor: John PierceEditorial Production: Rob Nance, John Pierce, and Carrie WicksCopyeditor: John PierceIndexer: Christina Yeager, Emerald Editorial ServicesCover: Twist Creative Seattle and Joel PanchotModernAuth PrintBook Final.indb ii11/28/2015 11:40:18 AM

Ai miei carissimi fratelli e sorelle: Mauro, Franco, Marino,Cristina, Ulderico, Maria, Laura, Guido e Mira—per avermifatto vedere il mondo attraverso altre nove paia d’occhi.ModernAuth PrintBook Final.indb iii11/28/2015 11:40:18 AM

ModernAuth PrintBook Final.indb iv11/28/2015 11:40:18 AM

ContentsForeword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiChapter 1Your first Active Directory app1The sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Microsoft Azure subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Visual Studio 2015 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Creating the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Running the application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4ClaimsPrincipal: How .NET represents the caller . . . . . . . . . . . . . . . . . . . . . . . 7Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Chapter 2Identity protocols and application types11Pre-claims authentication techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Passwords, profile stores, and individual applications. . . . . . . . . . . .12Domains, integrated authentication, and applications on anintranet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Claims-based identity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Identity providers: DCs for the Internet . . . . . . . . . . . . . . . . . . . . . . . . 17Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Trust and claims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20Claims-oriented protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20Round-trip web apps, first-generation protocols . . . . . . . . . . . . . . . . . . . . . 23The problem of cross-domain single sign-on . . . . . . . . . . . . . . . . . . . 23SAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25WS-Federation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27Modern apps, modern protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31The rise of the programmable web and the problem of accessdelegation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32vModernAuth PrintBook Final.indb v11/28/2015 11:40:18 AM

OAuth2 and web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Layering web sign-in on OAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37OpenID Connect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39More API consumption scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Single-page applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Leveraging web investments in native clients . . . . . . . . . . . . . . . . . . . 47Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Chapter 3Introducing Azure Active Directory and ActiveDirectory Federation Services51Active Directory Federation Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52ADFS and development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Getting ADFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54Protocols support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Azure Active Directory: Identity as a service . . . . . . . . . . . . . . . . . . . . . . . . .56Azure AD and development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Getting Azure Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Azure AD for developers: Components . . . . . . . . . . . . . . . . . . . . . . . .63Notable nondeveloper features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67Chapter 4Introducing the identity developer libraries69Token requestors and resource protectors . . . . . . . . . . . . . . . . . . . . . . . . . . 69Token requestors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Resource protectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Hybrids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74The Azure AD libraries landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Token requestors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Resource protectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Hybrids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85Visual Studio integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85AD integration features in Visual Studio 2013 . . . . . . . . . . . . . . . . . .86AD integration features in Visual Studio 2015 . . . . . . . . . . . . . . . . . .86Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87viContentsModernAuth PrintBook Final.indb vi11/28/2015 11:40:18 AM

Chapter 5Getting started with web sign-on andActive Directory89The web app you build in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90The starting project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90NuGet packages references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Registering the app in Azure AD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93OpenID Connect initialization code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95Host the OWIN pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95Initialize the cookie and OpenID Connect middlewares . . . . . . . . . .96[Authorize], claims, and first run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Adding a trigger for authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Showing some claims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98Running the app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99Quick recap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99Sign-in and sign-out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99Sign-in logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100Sign-out logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101The sign-in and sign-out UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102Running the app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103Using ADFS as an identity provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105Chapter 6OpenID Connect and Azure AD web sign-on107The protocol and its specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107OpenID Connect Core 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108OpenID Connect Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108OAuth 2.0 Multiple Response Type, OAuth2 Form PostResponse Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109OpenID Connection Session Management . . . . . . . . . . . . . . . . . . . .109Other OpenID Connect specifications . . . . . . . . . . . . . . . . . . . . . . . .109Supporting specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109ContentsModernAuth PrintBook Final.indb viivii11/28/2015 11:40:18 AM

OpenID Connect exchanges signing in with Azure AD . . . . . . . . . . . . . . .110Capturing a trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110Authentication request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123Sign-in sequence diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126The ID token and the JWT format . . . . . . . . . . . . . . . . . . . . . . . . . . . .127OpenID Connect exchanges for signing out from the appand Azure AD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136Chapter 7The OWIN OpenID Connect middleware137OWIN and Katana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137What is OWIN? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137Katana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139OpenID Connect middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155OpenIdConnectAuthenticationOptions . . . . . . . . . . . . . . . . . . . . . . . .155Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159TokenValidationParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167Valid values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168Validation flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170More on sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172Chapter 8Azure Active Directory application model173The building blocks: Application and ServicePrincipal . . . . . . . . . . . . . . . . 174The Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177The ServicePrincipal object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187Consent and delegated permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189Application created by a nonadmin user . . . . . . . . . . . . . . . . . . . . . .189Interlude: Delegated permissions to access the directory . . . . . . .192viiiContentsModernAuth PrintBook Final.indb viii11/28/2015 11:40:18 AM

Application requesting admin-level permissions . . . . . . . . . . . . . . .197Admin consent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200Application created by an admin user . . . . . . . . . . . . . . . . . . . . . . . .204Multitenancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205App user assignment, app permissions, and app roles . . . . . . . . . . . . . . .211App user assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211App roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213Application permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221Chapter 9Consuming and exposing a web API protected byAzure Active Directory223Consuming a web API from a web application . . . . . . . . . . . . . . . . . . . . . .223Redeeming an authorization code in the OpenID Connecthybrid flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224Using the access token for invoking a web API . . . . . . . . . . . . . . . .232Other ways of getting access tokens . . . . . . . . . . . . . . . . . . . . . . . . .251Exposing a protected web API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253Setting up a web API project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253Handling web API calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258Exposing both a web UX and a web API from the sameVisual Studio project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265A web API calling another API: Flowing the identity of thecaller and using “on behalf of” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266Protecting a web API with ADFS “3” . . . . . . . . . . . . . . . . . . . . . . . . . .271Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272Chapter 10 Active Directory Federation Services in WindowsServer 2016 Technical Preview 3273Setup (for developers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273The new management UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274Web sign-on with OpenID Connect and ADFS . . .