From fd8f36ad73b5e72926f78fe4ca173e7e64484b38 Mon Sep 17 00:00:00 2001
From: Thomas Rittson <trittson@bitwarden.com>
Date: Wed, 26 Mar 2025 13:33:44 +1000
Subject: [PATCH] Cleanup and xmldocs

---
 .../OrganizationUsersController.cs            |  4 ++--
 .../Authorization/AuthorizeAttribute.cs       | 21 +++++++++++++++++++
 ...tribute.cs => IOrganizationRequirement.cs} | 17 ++++++---------
 .../OrganizationRequirementHandler.cs         |  9 +++++++-
 4 files changed, 37 insertions(+), 14 deletions(-)
 create mode 100644 src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/AuthorizeAttribute.cs
 rename src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/{OrganizationAuthorizeAttribute.cs => IOrganizationRequirement.cs} (56%)

diff --git a/src/Api/AdminConsole/Controllers/OrganizationUsersController.cs b/src/Api/AdminConsole/Controllers/OrganizationUsersController.cs
index 9809e09141..2ccc1b97db 100644
--- a/src/Api/AdminConsole/Controllers/OrganizationUsersController.cs
+++ b/src/Api/AdminConsole/Controllers/OrganizationUsersController.cs
@@ -137,7 +137,7 @@ public class OrganizationUsersController : Controller
         return response;
     }
 
-    [OrganizationAuthorize<OrganizationMemberRequirement>]
+    [Authorize<OrganizationMemberRequirement>]
     [HttpGet("mini-details")]
     public async Task<ListResponseModel<OrganizationUserUserMiniDetailsResponseModel>> GetMiniDetails(Guid orgId)
     {
@@ -147,7 +147,7 @@ public class OrganizationUsersController : Controller
     }
 
     [HttpGet("")]
-    [OrganizationAuthorize<ManageUsersRequirement>]
+    [Authorize<ManageUsersRequirement>]
     public async Task<ListResponseModel<OrganizationUserUserDetailsResponseModel>> Get(Guid orgId, bool includeGroups = false, bool includeCollections = false)
     {
         var organizationUsers = await _organizationUserUserDetailsQuery.GetOrganizationUserUserDetails(
diff --git a/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/AuthorizeAttribute.cs b/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/AuthorizeAttribute.cs
new file mode 100644
index 0000000000..93705e7fc1
--- /dev/null
+++ b/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/AuthorizeAttribute.cs
@@ -0,0 +1,21 @@
+#nullable enable
+
+using Microsoft.AspNetCore.Authorization;
+
+namespace Bit.Core.AdminConsole.OrganizationFeatures.Shared.Authorization;
+
+/// <summary>
+/// An attribute which requires authorization using the specified requirement.
+/// This uses the standard ASP.NET authorization middleware.
+/// </summary>
+/// <typeparam name="T">The IAuthorizationRequirement that will be used to authorize the user.</typeparam>
+public class AuthorizeAttribute<T>
+    : AuthorizeAttribute, IAuthorizationRequirementData
+    where T : IAuthorizationRequirement, new()
+{
+    public IEnumerable<IAuthorizationRequirement> GetRequirements()
+    {
+        var requirement = new T();
+        yield return requirement;
+    }
+}
diff --git a/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationAuthorizeAttribute.cs b/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/IOrganizationRequirement.cs
similarity index 56%
rename from src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationAuthorizeAttribute.cs
rename to src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/IOrganizationRequirement.cs
index 6ad4764a98..a2f2ff74e7 100644
--- a/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationAuthorizeAttribute.cs
+++ b/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/IOrganizationRequirement.cs
@@ -5,19 +5,14 @@ using Microsoft.AspNetCore.Authorization;
 
 namespace Bit.Core.AdminConsole.OrganizationFeatures.Shared.Authorization;
 
+/// <summary>
+/// A requirement that implements this interface will be handled by <see cref="OrganizationRequirementHandler"/>,
+/// which calls AuthorizeAsync with the organization details from the route.
+/// This is used for simple role-based checks.
+/// This may only be used on endpoints with {orgId} in their path.
+/// </summary>
 public interface IOrganizationRequirement : IAuthorizationRequirement
 {
     // TODO: avoid injecting all of ICurrentContext?
     public Task<bool> AuthorizeAsync(Guid organizationId, CurrentContextOrganization? organizationClaims, ICurrentContext currentContext);
 }
-
-public class OrganizationAuthorizeAttribute<T>
-    : AuthorizeAttribute, IAuthorizationRequirementData
-    where T : IOrganizationRequirement, new()
-{
-    public IEnumerable<IAuthorizationRequirement> GetRequirements()
-    {
-        var requirement = new T();
-        yield return requirement;
-    }
-}
diff --git a/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationRequirementHandler.cs b/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationRequirementHandler.cs
index 85303c67a2..5a2402d9e7 100644
--- a/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationRequirementHandler.cs
+++ b/src/Core/AdminConsole/OrganizationFeatures/Shared/Authorization/OrganizationRequirementHandler.cs
@@ -6,6 +6,13 @@ using Microsoft.AspNetCore.Http;
 
 namespace Bit.Core.AdminConsole.OrganizationFeatures.Shared.Authorization;
 
+/// <summary>
+/// Handles any requirement that implements <see cref="IOrganizationRequirement"/>.
+/// Retrieves the Organization ID from the route and then passes it to the requirement's AuthorizeAsync callback to
+/// determine whether the action is authorized.
+/// </summary>
+/// <param name="currentContext"></param>
+/// <param name="httpContextAccessor"></param>
 public class OrganizationRequirementHandler(ICurrentContext currentContext, IHttpContextAccessor httpContextAccessor)
     : AuthorizationHandler<IOrganizationRequirement>
 {
@@ -14,7 +21,7 @@ public class OrganizationRequirementHandler(ICurrentContext currentContext, IHtt
         var organizationId = httpContextAccessor.GetOrganizationId();
         if (organizationId is null)
         {
-            return;
+            throw new Exception("No organizationId found in route. IOrganizationRequirement cannot be used on this endpoint.");
         }
 
         var organization = currentContext.GetOrganization(organizationId.Value);