Merge branch 'master' of https://github.com/Microsoft/azure-docs-pr into jun19-sec-dev

Author: TerryLanfear

articles/active-directory-b2c/active-directory-b2c-faqs.md

@@ -23,7 +23,7 @@ There are two common reasons for why the Azure AD extension is not working for y
 Azure AD and Azure AD B2C are separate product offerings and cannot coexist in the same tenant.  An Azure AD tenant represents an organization.  An Azure AD B2C tenant represents a collection of identities to be used with relying party applications.  With custom policies (in public preview), Azure AD B2C can federate to Azure AD allowing authentication of employees in an organization.
 
 ### Can I use Azure AD B2C to provide social login (Facebook and Google+) into Office 365?
-Azure AD B2C can't be used to authenticate users for Microsoft Office 365.  Azure AD is Microsoft's solution for managing employee access to SaaS apps and it has features designed for this purpose such as licensing and conditional access.  Azure AD B2C provides an identity and access management platform for building web and mobile applications.  When Azure AD B2C is configured to federate to an Azure AD tenant, the Azure AD tenant manages employee access to applications that rely on Azure AD B2C.
+Azure AD B2C can't be used to authenticate users for Microsoft Office 365.  Azure AD is Microsoft's solution for managing employee access to SaaS apps and it has features designed for this purpose such as licensing and Conditional Access.  Azure AD B2C provides an identity and access management platform for building web and mobile applications.  When Azure AD B2C is configured to federate to an Azure AD tenant, the Azure AD tenant manages employee access to applications that rely on Azure AD B2C.
 
 ### What are local accounts in Azure AD B2C? How are they different from work or school accounts in Azure AD?
 In an Azure AD tenant, users that belong to the tenant sign-in with an email address of the form `<xyz>@<tenant domain>`.  The `<tenant domain>` is one of the verified domains in the tenant or the initial `<...>.onmicrosoft.com` domain. This type of account is a work or school account.

articles/active-directory/authentication/concept-sspr-writeback.md

@@ -148,7 +148,6 @@ Passwords are written back in all the following situations:
    * Any administrator self-service force change password operation, for example, password expiration
    * Any administrator self-service password reset that originates from the [password reset portal](https://passwordreset.microsoftonline.com)
    * Any administrator-initiated end-user password reset from the [Azure portal](https://portal.azure.com)
-   * Any administrator-initiated end-user password reset from the [Microsoft 365 admin center](https://admin.microsoft.com)
 
 ## Unsupported writeback operations
 
@@ -158,6 +157,7 @@ Passwords are *not* written back in any of the following situations:
    * Any end user resetting their own password by using PowerShell version 1, version 2, or the Azure AD Graph API
 * **Unsupported administrator operations**
    * Any administrator-initiated end-user password reset from PowerShell version 1, version 2, or the Azure AD Graph API
+   * Any administrator-initiated end-user password reset from the [Microsoft 365 admin center](https://admin.microsoft.com)
 
 > [!WARNING]
 > Use of the checkbox "User must change password at next logon" in on-premises Active Directory administrative tools like Active Directory Users and Computers or the Active Directory Administrative Center is not supported. When changing a password on-premises do not check this option.

articles/active-directory/conditional-access/controls.md

@@ -15,7 +15,7 @@ ms.devlang: na
 ms.topic: article
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 03/23/2019
+ms.date: 06/15/2019
 ms.author: joflore
 ms.reviewer: calebb
 
@@ -124,11 +124,13 @@ Providers currently offering a compatible service include:
 
 - [Duo Security](https://duo.com/docs/azure-ca)
 - [Entrust Datacard](https://www.entrustdatacard.com/products/authentication/intellitrust)
+- [GSMA](https://mobileconnect.io/azure/)
 - [Ping Identity](https://documentation.pingidentity.com/pingid/pingidAdminGuide/index.shtml#pid_c_AzureADIntegration.html)
 - RSA
 - [SecureAuth](https://docs.secureauth.com/pages/viewpage.action?pageId=47238992#)
 - [Silverfort](https://www.silverfort.io/company/using-silverfort-mfa-with-azure-active-directory/)
 - [Symantec VIP](https://help.symantec.com/home/VIP_Integrate_with_Azure_AD)
+- [Thales (Gemalto)](https://resources.eu.safenetid.com/help/AzureMFA/Azure_Help/Index.htm)
 - [Trusona](https://www.trusona.com/docs/azure-ad-integration-guide)
 
 For more information on those services, contact the providers directly.

articles/active-directory/develop/TOC.yml

@@ -139,6 +139,8 @@
           href: scenario-protected-web-api-app-registration.md
         - name: Code configuration
           href: scenario-protected-web-api-app-configuration.md
+        - name: Verification of scopes or app roles
+          href: scenario-protected-web-api-verification-scope-app-roles.md
         - name: Move to production
           href: scenario-protected-web-api-production.md
       - name: Web API that calls web APIs

articles/active-directory/develop/scenario-protected-web-api-app-configuration.md

@@ -156,4 +156,4 @@ The validators are all associated with properties of the `TokenValidationParamet
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Move to production](scenario-protected-web-api-production.md)
+> [Verify scopes and app roles in your code](scenario-protected-web-api-verification-scope-app-roles.md)

articles/active-directory/develop/scenario-protected-web-api-app-registration.md

@@ -56,19 +56,20 @@ Scopes are usually of the form `resourceURI/scopeName`. For Microsoft Graph, the
 
 During app registration, you'll need to define the following parameters:
 
-- One resource URI - By default the application registration portal recommends that you to use `api://{clientId}`. This resource URI is unique, but it's not human readable. You can change it, but make sure that it's unique.
-- One or several scopes
+- The resource URI - By default the application registration portal recommends that you to use `api://{clientId}`. This resource URI is unique, but it's not human readable. You can change it, but make sure that it's unique.
+- One or more **scopes** (to client applications, they will show up as **delegated permissions** for your Web API)
+- One or more **app roles** (to client applications, they will show up as **application permissions** for your Web API)
 
-The scopes are also displayed on the consent screen that's presented to end-users who use your application. Therefore, you'll need to provide the corresponding strings that describe the scope:
+The scopes are also displayed on the consent screen that's presented to end users who use your application. Therefore, you'll need to provide the corresponding strings that describe the scope:
 
 - As seen by the end user
 - As seen by the tenant admin, who can grant admin consent
 
-### How to expose the API
+### How to expose delegated permissions (scopes)
 
 1. Select the **Expose an API** section in the application registration, and:
    1. Select **Add a scope**.
-   1. Accept the proposed Application ID URI (api://{clientId}) by selecting **Save and Continue**.
+   1. If requested, accept the proposed Application ID URI (api://{clientId}) by selecting **Save and Continue**.
    1. Enter the following parameters:
       - For **Scope name**, use `access_as_user`.
       - For **Who can consent**, make sure the **Admins and users** option is selected.
@@ -79,6 +80,59 @@ The scopes are also displayed on the consent screen that's presented to end-user
       - Keep **State** set to **Enabled**.
       - Select **Add scope**.
 
+### Case where your Web API is called by daemon application
+
+In this paragraph, you'll learn how to register your protected Web API so that it can be called securely by daemon applications:
+
+- you'll need to expose **application permissions**. You will only declare application permissions as daemon applications do not interact with users and therefore delegated permissions would not make sense.
+- tenant admins may require Azure AD to issue tokens for your Web App to only applications that have registered that they want to access one of the Web API apps permissions.
+
+#### How to expose application permissions (app roles)
+
+To Expose application permissions, you'll need to edit the manifest.
+
+1. In the application registration for your application, click **Manifest**.
+1. Edit the manifest by locating the `appRoles` setting and adding one or several application roles. The role definition is provided in the sample JSON block below.  Leave the `allowedMemberTypes` to "Application" only. Please make sure that the **id** is a unique guid and **displayName** and **Value** don't contain any spaces.
+1. Save the manifest.
+
+The content of `appRoles` should be the following (the `id` can be any unique GUID)
+
+```JSon
+"appRoles": [
+	{
+	"allowedMemberTypes": [ "Application" ],
+	"description": "Accesses the TodoListService-Cert as an application.",
+	"displayName": "access_as_application",
+	"id": "ccf784a6-fd0c-45f2-9c08-2f9d162a0628",
+	"isEnabled": true,
+	"lang": null,
+	"origin": "Application",
+	"value": "access_as_application"
+	}
+],
+```
+
+#### How to ensure that Azure AD issues tokens for your Web API only to allowed clients
+
+The Web API checks for the app role (that's the developer way of doing it). But you can even configure Azure Active Directory to issue a token for your Web API only to applications that were approved by the tenant admin to access your API. To add this additional security:
+
+1. On the app **Overview** page for your app registration, select the hyperlink with the name of your application in **Managed application in local directory**. The title for this field can be truncated. You could, for instance, read: `Managed application in ...`
+
+   > [!NOTE]
+   >
+   > When you select this link you will navigate to the **Enterprise Application Overview** page associated with the service principal for your application in the tenant where you created it. You can navigate back to the app registration page by using the back button of your browser.
+
+1. Select the **Properties** page in the **Manage** section of the Enterprise application pages
+1. If you want AAD to enforce access to your Web API from only certain clients, set **User assignment required?** to **Yes**.
+
+   > [!IMPORTANT]
+   >
+   > By setting **User assignment required?** to **Yes**, AAD will check the app role assignments of the clients when they request an access token for the Web API. If the client was not be assigned to any AppRoles, AAD would just return the following error: `invalid_client: AADSTS501051: Application xxxx is not assigned to a role for the xxxx`
+   >
+   > If you keep **User assignment required?** to **No**, <span style='background-color:yellow; display:inline'>Azure AD  won’t check the app role assignments when a client requests an access token for your Web API</span>. Therefore, any daemon client (that is any client using client credentials flow) would still be able to obtain an access token for the API just by specifying its audience. Any application, would be able to access the API without having to request permissions for it. Now, this is not then end of it, as your Web API can always, as explained in the next section, verify that the application has the right role (which was authorized by the tenant admin), by validating that the access token has a `roles` claim, and the right value for this claim (in our case `access_as_application`).
+
+1. Select **Save**
+
 ## Next steps
 
 > [!div class="nextstepaction"]

articles/active-directory/develop/scenario-protected-web-api-verification-scope-app-roles.md

@@ -0,0 +1,166 @@
+---
+title: Protected web API - app code configuration | Azure Active Directory
+description: Learn how to build a protected Web API and configure your application's code.
+services: active-directory
+documentationcenter: dev-center-name
+author: jmprieur
+manager: CelesteDG
+editor: ''
+
+ms.service: active-directory
+ms.subservice: develop
+ms.devlang: na
+ms.topic: conceptual
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 05/07/2019
+ms.author: jmprieur
+ms.custom: aaddev 
+#Customer intent: As an application developer, I want to learn how to write a protected Web API using the Microsoft identity platform for developers.
+ms.collection: M365-identity-device-management
+---
+
+# Protected web API - adding authorization to your API
+
+This article describes how you can add authorization to your Web API. This protection ensures that it's only called by:
+
+- applications on behalf of users with the right scopes 
+- or by daemon apps with the right application roles.
+
+For an ASP.NET / ASP.NET Core Web API to be protected, you'll need to add the `[Authorize]` attribute on:
+
+- the Controller itself if you want all the actions of the controller to be protected
+- or the individual controller action for your API.
+
+```CSharp
+    [Authorize]
+    public class TodoListController : Controller
+    {
+     ...
+    }
+```
+
+But this protection isn't enough. It only guaranties that ASP.NET / ASP.NET Core will validate the token. Your API needs to verify that the token used to call your Web API was requested with the claims it expects, in particular:
+
+- the **scopes** if the API is called on behalf of a user
+- the **app roles** if the API can be called from a daemon app.
+
+## Verifying scopes in APIs called on behalf of users
+
+If your API is called by a client app on behalf of a user, then it needs to request a bearer token with specific scopes for the API (see [Code configuration | Bearer token](scenario-protected-web-api-app-configuration.md#bearer-token))
+
+```CSharp
+[Authorize]
+public class TodoListController : Controller
+{
+    /// <summary>
+    /// The Web API will only accept tokens 1) for users, 2) having the `access_as_user` scope for
+    /// this API
+    /// </summary>
+    const string scopeRequiredByAPI = "access_as_user";
+
+    // GET: api/values
+    [HttpGet]
+    public IEnumerable<TodoItem> Get()
+    {
+        VerifyUserHasAnyAcceptedScope(scopeRequiredByAPI);
+        // Do the work and return the result
+        ...
+    }
+...
+}
+```
+
+The `VerifyUserHasAnyAcceptedScope` method would do something like the following:
+
+- verify that there's a claims named `http://schemas.microsoft.com/identity/claims/scope` or `scp`
+- verify that the claim has a value containing the scope expected by the API.
+
+```CSharp
+    /// <summary>
+    /// When applied to an <see cref="HttpContext"/>, verifies that the user authenticated in the 
+    /// Web API has any of the accepted scopes.
+    /// If the authenticated user does not have any of these <paramref name="acceptedScopes"/>, the
+    /// method throws an HTTP Unauthorized with the message telling which scopes are expected in the token
+    /// </summary>
+    /// <param name="acceptedScopes">Scopes accepted by this API</param>
+    /// <exception cref="HttpRequestException"/> with a <see cref="HttpResponse.StatusCode"/> set to 
+    /// <see cref="HttpStatusCode.Unauthorized"/>
+    public static void VerifyUserHasAnyAcceptedScope(this HttpContext context,
+                                                     params string[] acceptedScopes)
+    {
+        if (acceptedScopes == null)
+        {
+            throw new ArgumentNullException(nameof(acceptedScopes));
+        }
+        Claim scopeClaim = HttpContext?.User
+                                      ?.FindFirst("http://schemas.microsoft.com/identity/claims/scope");
+        if (scopeClaim == null || !scopeClaim.Value.Split(' ').Intersect(acceptedScopes).Any())
+        {
+            context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
+            string message = $"The 'scope' claim does not contain scopes '{string.Join(",", acceptedScopes)}' or was not found";
+            throw new HttpRequestException(message);
+        }
+    }
+```
+
+This sample code is for ASP.NET Core. For ASP.NET just replace `HttpContext.User` by `ClaimsPrincipal.Current`, and the claim type `"http://schemas.microsoft.com/identity/claims/scope"` by `"scp"` (See also the code snippet below)
+
+## Verifying app roles in APIs called by daemon apps
+
+If your Web API is called by a [Daemon application](scenario-daemon-overview.md), then that application should require an application permission to your Web API. We've seen in [scenario-protected-web-api-app-registration.md#how-to-expose-application-permissions--app-roles-] that your API exposes such permissions (for instance as the `access_as_application` app role).
+You now need to have your APIs verify that the token it received contains the `roles` claims and
+that this claim has the value it expects. The code doing this verification is similar to the code that verifies delegated permissions, except that, instead of testing for `scopes`, your controller action will test for `roles`:
+
+```CSharp
+[Authorize]
+public class TodoListController : ApiController
+{
+    public IEnumerable<TodoItem> Get()
+    {
+        ValidateAppRole("access_as_application");
+        ...
+    }
+```
+
+The `ValidateAppRole()` method can be something like this:
+
+```CSharp
+private void ValidateAppRole(string appRole)
+{
+    //
+    // The `role` claim tells you what permissions the client application has in the service.
+    // In this case we look for a `role` value of `access_as_application`
+    //
+    Claim roleClaim = ClaimsPrincipal.Current.FindFirst("roles");
+    if (roleClaim == null || !roleClaim.Value.Split(' ').Contains(appRole))
+    {
+        throw new HttpResponseException(new HttpResponseMessage 
+        { StatusCode = HttpStatusCode.Unauthorized, 
+            ReasonPhrase = $"The 'roles' claim does not contain '{appRole}' or was not found" 
+        });
+    }
+}
+}
+```
+
+This sample code is for ASP.NET. For ASP.NET Core, just replace `ClaimsPrincipal.Current` by `HttpContext.User` and the `"roles"` claim name by `"http://schemas.microsoft.com/identity/claims/roles"` (see also the code snippet above)
+
+### Accepting app only tokens if the Web API should only be called by daemon apps
+
+The `roles` claim is also used for users in user assignment patterns (See [How to: Add app roles in your application and receive them in the token](howto-add-app-roles-in-azure-ad-apps.md)). So just checking roles will allow apps to sign in as users and the other way around, if the roles are assignable to both. We recommend having different roles declared for users and apps to prevent this confusion.
+
+If you want to only allow daemon applications to call your Web API, you'll want to add a condition, when you validate the app role, that the token is an app-only token:
+
+```CSharp
+string oid = ClaimsPrincipal.Current.FindFirst("oid");
+string sub = ClaimsPrincipal.Current.FindFirst("sub");
+bool isAppOnlyToken = oid == sub;
+```
+
+Checking the inverse condition will allow only apps that sign in a user, to call your API.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Move to production](scenario-protected-web-api-production.md)

articles/active-directory/hybrid/how-to-connect-install-prerequisites.md

@@ -43,6 +43,9 @@ Before you install Azure AD Connect, there are a few things that you need.
 * It is recommended to [enable the Active Directory recycle bin](how-to-connect-sync-recycle-bin.md).
 
 ### Azure AD Connect server
+>[!IMPORTANT]
+>The Azure AD Connect server contains critical identity data and should be treated as a Tier 0 component as documented in [the Active Directory administrative tier model](https://docs.microsoft.com/windows-server/identity/securing-privileged-access/securing-privileged-access-reference-material#ADATM_BM)
+
 * Azure AD Connect cannot be installed on Small Business Server or Windows Server Essentials before 2019 (Windows Server Essentials 2019 is supported). The server must be using Windows Server standard or better.
 * Installing Azure AD Connect on a Domain Controller is not recommended due to security practices and more restrictive settings that can prevent Azure AD Connect from installing correctly
 * The Azure AD Connect server must have a full GUI installed. It is **not supported** to install on server core.