adressing PR feedback

Author: jmprieur

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

@@ -56,9 +56,9 @@ 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** (that client applications will refer to as **delegated permissions** for your Web API)
-- One or several **app roles** (that client applications will refer to as **application permissions** for your Web API)
+- 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:
 
@@ -84,15 +84,15 @@ The scopes are also displayed on the consent screen that's presented to end user
 
 In this paragraph, you'll learn how to register your protected Web API so that it can be called securely by daemon applications:
 
-- you' statuill need to expose application permissions
-- tenant admins may require AAD to acquire tokens for your Web App only for registered 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 JSON block below.  Leave the `allowedMemberTypes` to "Application" only.
+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)
@@ -114,7 +114,7 @@ The content of `appRoles` should be the following (the `id` can be any unique GU
 
 #### How to ensure that Azure AD issues tokens for your Web API only to allowed clients
 
-The Web API tests for the app role (that's the developer way of doing it). But you can even ask Azure Active Directory to issue a token for your Web API only to applications that were approved by the tenant admin. To add this additional security:
+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 ...`
 
@@ -127,9 +127,9 @@ The Web API tests for the app role (that's the developer way of doing it). But y
 
    > [!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 `invalid_client: AADSTS501051: Application xxxx is not assigned to a role for the xxxx`
+   > 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 to your Web API</span>. Therefore, any daemon client (that is any client using client credentials flow) would still be able to obtain the access token for the  Web 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 is done in this sample, 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`).
+   > 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**
 

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

@@ -16,7 +16,7 @@ ms.workload: identity
 ms.date: 05/07/2019
 ms.author: jmprieur
 ms.custom: aaddev 
-#Customer intent: As an application developer, I want to know how to write a protected Web API using the Microsoft identity platform for developers.
+#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
 ---
 
@@ -30,7 +30,7 @@ This article describes how you can add authorization to your Web API. This prote
 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
-- the individual controller action for your API, otherwise.
+- or the individual controller action for your API.
 
 ```CSharp
     [Authorize]
@@ -73,14 +73,14 @@ public class TodoListController : Controller
 
 The `VerifyUserHasAnyAcceptedScope` method would do something like the following:
 
-- verify that there's a claims named `scope`
-- verify that the claim has a value containing the scope expected by the API. 
+- 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 authentication user does not have any of these <paramref name="acceptedScopes"/>, 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>
@@ -104,15 +104,13 @@ The `VerifyUserHasAnyAcceptedScope` method would do something like the following
     }
 ```
 
-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 `"scope"` (See also the code snippet below)
-
+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 you 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. To do this, the code is similar to the code that verifies delegated permissions, except that, instead of testing for `scopes`, your controller action will test for `roles`:
+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]
@@ -125,26 +123,47 @@ public class TodoListController : ApiController
     }
 ```
 
-The ValidateAppRole() method can be something like this:
+The `ValidateAppRole()` method can be something like this:
 
 ```CSharp
-    private void ValidateAppRole(string appRole)
+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`
+    //
+
+    if (!isAppOnlyToken)
     {
-        //
-        // 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 scopeClaim = ClaimsPrincipal.Current.FindFirst("roles");
-        if (scopeClaim == null || (scopeClaim.Value != appRole))
-        {
-            throw new HttpResponseException(new HttpResponseMessage { StatusCode = HttpStatusCode.Unauthorized, ReasonPhrase = $"The 'roles' claim does not contain '{appRole}' or was not found" });
-        }
     }
+    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 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;
+```
+
+Of course checking the inverse condition will allow only app that sign-in a user to call your API.
+
 ## Next steps
 
 > [!div class="nextstepaction"]