Jennyf/scopes roles (#1742)

* initial commit for app permissions

* add test coverage

* remove IEnumerable and use string[]

* PR comments

Author: jennyf19

src/Microsoft.Identity.Web/Microsoft.Identity.Web.xml

@@ -15,7 +15,7 @@ public interface IAuthRequiredScopeMetadata
         /// <summary>
         /// Scopes accepted by this web API.
         /// </summary>
-        IEnumerable<string>? AcceptedScope { get; }
+        string[]? AcceptedScope { get; }
 
         /// <summary>
         /// Fully qualified name of the configuration key containing the required scopes (separated

src/Microsoft.Identity.Web/Policy/IAuthRequiredScopeMetadata.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Collections.Generic;
+
+namespace Microsoft.Identity.Web
+{
+    /// <summary>
+    /// This is the metadata that describes required auth scopes or app permissions for a given endpoint
+    /// in a web API. It's the underlying data structure the requirement <see cref="ScopeOrAppPermissionAuthorizationRequirement"/> will look for
+    /// in order to validate scopes in the scope claims or app permissions in the roles claim.
+    /// </summary>
+    public interface IAuthRequiredScopeOrAppPermissionMetadata
+    {
+        /// <summary>
+        /// App permissions accepted by this web API.
+        /// App permissions appear in the roles claim of the token.
+        /// </summary>
+        string[]? AcceptedAppPermission { get; }
+
+        /// <summary>
+        /// Fully qualified name of the configuration key containing the required
+        /// app permissions (separated by spaces).
+        /// </summary>
+        string? RequiredAppPermissionsConfigurationKey { get; }
+
+        /// <summary>
+        /// Scopes accepted by this web API.
+        /// </summary>
+        string[]? AcceptedScope { get; }
+
+        /// <summary>
+        /// Fully qualified name of the configuration key containing the required scopes (separated
+        /// by spaces).
+        /// </summary>
+        string? RequiredScopesConfigurationKey { get; }
+    }
+}

src/Microsoft.Identity.Web/Policy/IAuthRequiredScopeOrAppPermissionMetadata.cs

@@ -58,5 +58,29 @@ public static AuthorizationPolicyBuilder RequireScope(
             authorizationPolicyBuilder.Requirements.Add(new ScopeAuthorizationRequirement(allowedValues));
             return authorizationPolicyBuilder;
         }
+
+        /// <summary>
+        /// Adds a <see cref="ScopeOrAppPermissionAuthorizationRequirement"/> to the current instance which requires
+        /// that the current user has the specified claim and that the claim value must be one of the allowed values.
+        /// </summary>
+        /// <param name="authorizationPolicyBuilder">Used for building policies during application startup.</param>
+        /// <param name="allowedScopeValues">scopes (the value of scope or scp) accepted by this app.</param>
+        /// <param name="allowedAppPermissionValues">App permission (in role claim) that this app accepts.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
+        public static AuthorizationPolicyBuilder RequireScopeOrAppPermission(
+            this AuthorizationPolicyBuilder authorizationPolicyBuilder,
+            IEnumerable<string> allowedScopeValues,
+            IEnumerable<string> allowedAppPermissionValues)
+        {
+            if (authorizationPolicyBuilder == null)
+            {
+                throw new ArgumentNullException(nameof(authorizationPolicyBuilder));
+            }
+
+            authorizationPolicyBuilder.Requirements.Add(new ScopeOrAppPermissionAuthorizationRequirement(
+                allowedScopeValues,
+                allowedAppPermissionValues));
+            return authorizationPolicyBuilder;
+        }
     }
 }

src/Microsoft.Identity.Web/Policy/PolicyBuilderExtensions.cs

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.Extensions.Options;
+
+namespace Microsoft.Identity.Web
+{
+    /// <summary>
+    /// RequireScopeOrAppPermissionOptions.
+    /// </summary>
+    internal class RequireScopeOrAppPermissionOptions : IPostConfigureOptions<AuthorizationOptions>
+    {
+        private readonly AuthorizationPolicy _defaultPolicy;
+
+        /// <summary>
+        /// Sets the default policy.
+        /// </summary>
+        public RequireScopeOrAppPermissionOptions()
+        {
+            _defaultPolicy = new AuthorizationPolicyBuilder()
+                .AddRequirements(new ScopeOrAppPermissionAuthorizationRequirement())
+                .Build();
+        }
+
+        /// <inheritdoc/>
+        public void PostConfigure(
+            string name,
+            AuthorizationOptions options)
+        {
+            if (options == null)
+            {
+                throw new ArgumentNullException(nameof(options));
+            }
+
+            options.DefaultPolicy = options.DefaultPolicy is null
+                                     ? _defaultPolicy
+                                     : AuthorizationPolicy.Combine(options.DefaultPolicy, _defaultPolicy);
+        }
+    }
+}

src/Microsoft.Identity.Web/Policy/RequireScopeOrAppPermissionOptions.cs

@@ -19,7 +19,7 @@ public class RequiredScopeAttribute : Attribute, IAuthRequiredScopeMetadata
         /// <summary>
         /// Scopes accepted by this web API.
         /// </summary>
-        public IEnumerable<string>? AcceptedScope { get; set; }
+        public string[]? AcceptedScope { get; set; }
 
         /// <summary>
         /// Fully qualified name of the configuration key containing the required scopes (separated

src/Microsoft.Identity.Web/Policy/RequiredScopeAttribute.cs

@@ -52,7 +52,7 @@ public RequiredScopeMetadata(string[] scope)
                 AcceptedScope = scope;
             }
 
-            public IEnumerable<string>? AcceptedScope { get; }
+            public string[]? AcceptedScope { get; }
 
             public string? RequiredScopesConfigurationKey { get; }
         }

src/Microsoft.Identity.Web/Policy/RequiredScopeExtensions.cs

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+
+namespace Microsoft.Identity.Web.Resource
+{
+    /// <summary>
+    /// This attribute is used on a controller, pages, or controller actions
+    /// to declare (and validate) the scopes or app permissions required by a web API. 
+    /// These scopes or app permissions can be declared in two ways:
+    /// hardcoding them, or declaring them in the configuration. Depending on your
+    /// choice, use either one or the other of the constructors.
+    /// For details, see https://aka.ms/ms-id-web/required-scope-or-app-permissions-attribute.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
+    public class RequiredScopeOrAppPermissionAttribute : Attribute, IAuthRequiredScopeOrAppPermissionMetadata
+    {
+        /// <summary>
+        /// Scopes accepted by this web API.
+        /// </summary>
+        public string[]? AcceptedScope { get; set; }
+
+        /// <summary>
+        /// Fully qualified name of the configuration key containing the required scopes (separated
+        /// by spaces).
+        /// </summary>
+        /// <example>
+        /// If the appsettings.json file contains a section named "AzureAd", in which
+        /// a property named "Scopes" contains the required scopes, the attribute on the
+        /// controller/page/action to protect should be set to the following:
+        /// <code>
+        /// [RequiredScopeOrAppPermission(RequiredScopesConfigurationKey="AzureAd:Scopes")]
+        /// </code>
+        /// </example>
+        public string? RequiredScopesConfigurationKey { get; set; }
+
+        /// <summary>
+        /// App permissions accepted by this web API.
+        /// App permissions appear in the roles claim of the token.
+        /// </summary>
+        public string[]? AcceptedAppPermission { get; set; }
+
+        /// <summary>
+        /// Fully qualified name of the configuration key containing the required app permissions (separated
+        /// by spaces).
+        /// </summary>
+        /// <example>
+        /// If the appsettings.json file contains a section named "AzureAd", in which
+        /// a property named "AppPermissions" contains the required app permissions, the attribute on the
+        /// controller/page/action to protect should be set to the following:
+        /// <code>
+        /// [RequiredScopeOrAppPermission(RequiredAppPermissionsConfigurationKey="AzureAd:AppPermissions")]
+        /// </code>
+        /// </example>
+        public string? RequiredAppPermissionsConfigurationKey { get; set; }
+
+        /// <summary>
+        /// Verifies that the web API is called with the right app permissions.
+        /// If the token obtained for this API is on behalf of the authenticated user does not have
+        /// any of these <paramref name="acceptedScopes"/> in its scope claim, 
+        /// nor <paramref name="acceptedAppPermissions"/> in its roles claim, the
+        /// method updates the HTTP response providing a status code 403 (Forbidden)
+        /// and writes to the response body a message telling which scopes are expected in the token.
+        /// </summary>
+        /// <param name="acceptedScopes">Scopes accepted by this web API.</param>
+        /// <param name="acceptedAppPermissions">App permissions accepted by this web API.</param>
+        /// <remarks>When neither the scopes nor app permissions match, the response is a 403 (Forbidden),
+        /// because the user is authenticated (hence not 401), but not authorized.</remarks>
+        /// <example>
+        /// Add the following attribute on the controller/page/action to protect:
+        ///
+        /// <code>
+        /// [RequiredScopeOrAppPermission(new [] { "access_as_user" }, new [] { "access_as_app" })]
+        /// </code>
+        /// </example>
+        /// <seealso cref="M:RequiredScopeOrAppPermissionAttribute()"/> and <see cref="RequiredAppPermissionsConfigurationKey"/>
+        /// if you want to express the required scopes or app permissions from the configuration.
+        public RequiredScopeOrAppPermissionAttribute(string[] acceptedScopes, string[] acceptedAppPermissions)
+        {
+            AcceptedScope = acceptedScopes ?? throw new ArgumentNullException(nameof(acceptedScopes));
+            AcceptedAppPermission = acceptedAppPermissions ?? throw new ArgumentNullException(nameof(acceptedAppPermissions));
+        }
+
+        /// <summary>
+        /// Default constructor.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// [RequiredScopeOrAppPermission(RequiredScopesConfigurationKey="AzureAD:Scope", RequiredAppPermissionsConfigurationKey="AzureAD:AppPermission")]
+        /// class Controller : BaseController
+        /// {
+        /// }
+        /// </code>
+        /// </example>
+        public RequiredScopeOrAppPermissionAttribute()
+        {
+        }
+    }
+}

src/Microsoft.Identity.Web/Policy/RequiredScopeOrAppPermissionAttribute.cs

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+
+namespace Microsoft.Identity.Web
+{
+    /// <summary>
+    /// Extensions for building the required scope or app permission attribute during application startup.
+    /// </summary>
+    public static class RequiredScopeOrAppPermissionExtensions
+    {
+        /// <summary>
+        /// This method adds support for the required scope or app permission attribute. It adds a default policy that
+        /// adds a scope requirement or app permission requirement.
+        /// This requirement looks for IAuthRequiredScopeOrAppPermissionMetadata on the current endpoint.
+        /// </summary>
+        /// <param name="services">The services being configured.</param>
+        /// <returns>Services.</returns>
+        public static IServiceCollection AddRequiredScopeOrAppPermissionAuthorization(this IServiceCollection services)
+        {
+            services.AddAuthorization();
+
+            services.TryAddEnumerable(ServiceDescriptor.Singleton<IPostConfigureOptions<AuthorizationOptions>, RequireScopeOrAppPermissionOptions>());
+            services.TryAddEnumerable(ServiceDescriptor.Singleton<IAuthorizationHandler, ScopeOrAppPermissionAuthorizationHandler>());
+            return services;
+        }
+
+        /// <summary>
+        /// This method adds metadata to route endpoint to describe required scopes or app permissions. It's the imperative version of
+        /// the [RequiredScopeOrAppPermission] attribute.
+        /// </summary>
+        /// <typeparam name="TBuilder">Class implementing <see cref="IEndpointConventionBuilder"/>.</typeparam>
+        /// <param name="endpointConventionBuilder">To customize the endpoints.</param>
+        /// <param name="scope">Scope.</param>
+        /// <param name="appPermission">App permission.</param>
+        /// <returns>Builder.</returns>
+        public static TBuilder RequireScopeOrAppPermission<TBuilder>(this TBuilder endpointConventionBuilder, string[] scope, string[] appPermission)
+            where TBuilder : IEndpointConventionBuilder
+        {
+            return endpointConventionBuilder.WithMetadata(new RequiredScopeOrAppPermissionMetadata(scope, appPermission));
+        }
+
+        private sealed class RequiredScopeOrAppPermissionMetadata : IAuthRequiredScopeMetadata
+        {
+            public RequiredScopeOrAppPermissionMetadata(string[] scope, string[] appPermission)
+            {
+                AcceptedScope = scope;
+                AcceptedAppPermission = appPermission;
+            }
+
+            public string[]? AcceptedScope { get; }
+            public string[]? AcceptedAppPermission { get; }
+
+            public string? RequiredScopesConfigurationKey { get; }
+            public string? RequiredAppPermissionsConfigurationKey { get; }
+        }
+    }
+}

src/Microsoft.Identity.Web/Policy/RequiredScopeOrAppPermissionExtensions.cs

@@ -4,7 +4,6 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Security.Claims;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Http;