Deep Dive on Azure Active Directory for Developers Jelle Druyts | Premier Field Engineer | Microsoft Services Agenda Azure Active Directory for developers Developing for Azure Active Directory Azure Active Directory for Developers Today’s Applications Browser Web Web API JavaScript application Native app Web API Web API Server app Clients using wide variety of Server applications using wide devices/languages/platforms variety of platforms/languages Authentication Protocols WS-Federation SAML 2.0 OpenID Connect OAuth 2.0 Browser Web Web API JavaScript application OAuth 2.0 Native app OAuth 2.0 OAuth 2.0 Web API Web API Server app OAuth 2.0 Standard-based, HTTP-based protocols for maximum platform reach What Is Azure Active Directory? Azure Active Directory for Developers Azure Active Directory • Cloud-scale identity service • Supports modern authorization & authentication scenarios • REST-based Graph API Reduces or removes custom security implementation • Authenticating users • Detecting suspicious activity • Authorizing users via Groups or Roles (RBAC) • B2C will allow social and “application local” accounts Tokens in Azure AD OAuth 2.0 Access and Refresh Tokens Access tokens have a lifetime of 1 hour • Allows quick revocation of access Refresh tokens allow silent renewal of the access token • User does not have to sign in again (as long as access wasn’t revoked) Refresh token lifetime • Azure AD accounts: 14 days, sliding up to maximum 90 days • External accounts (e.g. Microsoft Account): 12 hours • Can be invalidated, e.g. when user’s password changes Multi-Resource Refresh Token • Can be used to get access token to a different service if delegation exists JSON Web Token (JWT) Base64 URL encoded JSON with optional signature eyJ0eXAiOiJKV1QiLCJhbGciO.eyJpc3MiOiJodHRwOi8vc3RzbnRc28uY29tI.ZT8zzX6vg9I5HvTm4f8f Header <dot> Claims <dot> Signature { { "typ": "JWT", "iss": "http://sts.contoso.com/", "alg": "RS256" "aud": "http://api.contoso.com/", "x5t": "7dD-gec…" "client": "http://www.contoso.com/", } "iat": "1432235632", "exp": "1432239532", "name": "John Doe" "scope": ["read", "write"] } Token Signing Key Ensuring the tokens really come from Azure Active Directory Tokens for all tenants are signed by same key • Keys published via metadata • https://login.microsoftonline.com/common/.well-known/openid-configuration • Keys roll on periodic basis Applications must handle • Periodically refreshing keys from metadata • Handling multiple keys • Microsoft samples and libraries do this automatically Registering Applications Azure AD must know about your app before it will issue tokens Register your application via • Azure Management Portal • Visual Studio • Azure AD REST API’s Non-admins may register applications by default • Can be disabled The management portal only shows a subset of functionality • Advanced features available via application manifest • OAuth 2.0 permissions, application roles, group claims, certificates, … Application Configuration What Azure AD needs to know about your app All applications • Name: shown when authenticating/authorizing • Client ID: GUID of the application in Azure AD Native client applications (public clients) • Redirect URI’s: signaling the end of the flow Web applications and/or Web API’s (confidential clients) • Sign-On URL: where to send users from the application access portal • Single- or Multi-Tenant • Keys • App ID URI: unique identifier that clients request access to • Reply URL’s: where to allow tokens to be sent Permissions To Other Applications Declaring access to other applications Application Permissions • Access another application as the calling application Delegated Permissions • Access another application on behalf of the user Consent Granting permissions to an application Consent can be granted by user or by organization admin • Stored in Azure AD for web applications • Stored in the Refresh Token for native applications Multi-Tenant Applications Targeting other organizations Single tenant application • App for users in a single organization • Admin or user registers app in directory tenant • Sign in at https://login.microsoftonline.com/contoso.com/<protocol> Multi-tenant application • App for users in multiple organizations • Admin or user registers app in developer’s directory tenant • Admin configures application to be multi-tenant • Sign in at https://login.microsoftonline.com/common/<protocol> • User prompted to consent based on permissions required by application • Consent registers application in user’s tenant Groups & Roles Authorization features for applications Groups (defined in Azure or synchronized from on-premise AD) • Token contains “groups” claims (must opt-in) • When there are too many groups, “overage” claim points towards Graph API • Not all flows support group claims (e.g. not over URL query parameters) Application Roles • Application can declare application-specific roles • Administrator can assign users or groups to roles • Token then contains “roles” claims Developing for Azure Active Directory Developing For Azure AD And mostly equivalent when using Windows Server 2016 on-premise Register your application in Azure AD • Retrieve Client ID & (optional) Keys • Configure Redirect URL • Configure API permissions Add code to your application for sign in • Web: WS-Federation, SAML 2.0, OpenID Connect • Other (native, desktop, server): OAuth 2.0 Add code to your Web API for OAuth 2.0 Bearer Token authorization Microsoft Security Libraries WS-Federation SAML 2.0 OpenID Connect OAuth 2.0 Browser OIC-MW: OIC-MW Web BT-MW ADAL Web API OpenID Connect JavaScript application Middleware ADAL.JS OAuth 2.0 BT-MW: Native app ADAL ADAL Bearer Token Middleware OAuth 2.0 OAuth 2.0 BT-MW BT-MW ADAL: Web API ADAL Web API Active Directory Authentication Server app ADAL Library OAuth 2.0 Active Directory Authentication Library Acquiring, refreshing & caching tokens ADAL • Consistent API across platforms for acquiring tokens • Pluggable cache for token persistence • Automatic refresh of Access Tokens using Refresh Tokens • Works against Azure AD as well as Windows Server ADAL.JS • Sign in and bearer token support for JavaScript • Provides current user info • Secure Web API invocation via JavaScript/CORS Adding Sign-In To ASP.NET WS-Federation SAML 2.0 OpenID Connect OAuth 2.0 Browser OIC-MW: OIC-MW Web BT-MW ADAL Web API OpenID Connect JavaScript application Middleware ADAL.JS OAuth 2.0 BT-MW: Native app ADAL ADAL Bearer Token Middleware OAuth 2.0 OAuth 2.0 BT-MW BT-MW ADAL: Web API ADAL Web API Active Directory Authentication Server app ADAL Library OAuth 2.0 Adding Sign-In To ASP.NET OpenID Connect Use OpenID Connect OWIN Middleware • “Microsoft.Owin.Security.OpenIdConnect” NuGet package app.UseOpenIdConnectAuthentication( new OpenIdConnectAuthenticationOptions { ClientId = "187ff6ec-eae0-4376-807d-5ffa3d28645b", Authority = "https://login.microsoftonline.com/contoso.com", } ); [Authorize] public class HomeController : Controller { ... } Protecting Web API’s WS-Federation SAML 2.0 OpenID Connect OAuth 2.0 Browser OIC-MW: OIC-MW Web BT-MW ADAL Web API OpenID Connect JavaScript application Middleware ADAL.JS OAuth 2.0 BT-MW: Native app ADAL ADAL Bearer Token Middleware OAuth 2.0 OAuth 2.0 BT-MW BT-MW ADAL: Web API ADAL Web API Active Directory Authentication Server app ADAL Library OAuth 2.0 Protecting Web API’s OAuth 2.0 Bearer Token Authorization Use Bearer Token OWIN Middleware • “Microsoft.Owin.Security.ActiveDirectory” NuGet Package • Automatically acquires signing keys and issuer values app.UseCors( ... ); // For SPA clients app.UseWindowsAzureActiveDirectoryBearerAuthentication new WindowsAzureActiveDirectoryBearerAuthenticationOptions { TokenValidationParameters = new TokenValidationParameters { ValidAudience = "http://example.org/mywebapi" }, Tenant = "contoso.com" } ); [Authorize] public class ProductController : ApiController { ... } Calling Web API’s General pattern Use Active Directory Authentication Library (ADAL) • “Microsoft.IdentityModel.Clients.ActiveDirectory” NuGet Package Retrieve an access token and send it on the “Authorization” HTTP header var context = new AuthenticationContext( "https://login.microsoftonline.com/contoso.com"); var result = context.AcquireToken( ... ); var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken); Calling Web API’s – Web App WS-Federation SAML 2.0 OpenID Connect OAuth 2.0 Browser OIC-MW: OIC-MW Web BT-MW ADAL Web API OpenID Connect JavaScript application Middleware ADAL.JS OAuth 2.0 BT-MW: Native app ADAL ADAL Bearer Token Middleware OAuth 2.0 OAuth 2.0 BT-MW BT-MW ADAL: Web API ADAL Web API Active Directory Authentication Server app ADAL Library OAuth 2.0 Calling Web API’s – Web App OpenID Connect (user identity) At OpenID Connect sign-in • Receive an ID Token + Authorization Code • Use ADAL to redeem the Authorization Code for an Access + Refresh Token • Save the tokens in a persistent per-user cache When you need to access a resource • Initialize ADAL with the same cache you used earlier • Ask for the token you need via AcquireTokenSilent • Upon failure, trigger re-authentication new OpenIdConnectAuthenticationOptions { Notifications = new OpenIdConnectAuthenticationNotifications() { AuthorizationCodeReceived = async (context) => { var userTokenCache = GetTokenCacheForUser(context.AuthenticationTicket.Identity); var context = new AuthenticationContext(authority, userTokenCache); var result = await context.AcquireTokenByAuthorizationCodeAsync(