240 lines
13 KiB
Markdown
240 lines
13 KiB
Markdown
---
|
|
phase: 19-app-registration-removal
|
|
plan: 01
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified:
|
|
- SharepointToolbox/Core/Models/AppRegistrationResult.cs
|
|
- SharepointToolbox/Core/Models/TenantProfile.cs
|
|
- SharepointToolbox/Services/IAppRegistrationService.cs
|
|
- SharepointToolbox/Services/AppRegistrationService.cs
|
|
- SharepointToolbox.Tests/Services/AppRegistrationServiceTests.cs
|
|
autonomous: true
|
|
requirements: [APPREG-02, APPREG-03, APPREG-06]
|
|
|
|
must_haves:
|
|
truths:
|
|
- "IsGlobalAdminAsync returns true when user has Global Admin directory role"
|
|
- "IsGlobalAdminAsync returns false (not throws) when user lacks role or gets 403"
|
|
- "RegisterAsync creates Application + ServicePrincipal + OAuth2PermissionGrants in sequence"
|
|
- "RegisterAsync rolls back (deletes Application) when any intermediate step fails"
|
|
- "RemoveAsync deletes the Application by appId and clears MSAL session"
|
|
- "TenantProfile.AppId is nullable and round-trips through JSON serialization"
|
|
- "AppRegistrationResult discriminates Success (with appId), Failure (with message), and Fallback"
|
|
artifacts:
|
|
- path: "SharepointToolbox/Core/Models/AppRegistrationResult.cs"
|
|
provides: "Discriminated result type for registration outcomes"
|
|
contains: "class AppRegistrationResult"
|
|
- path: "SharepointToolbox/Core/Models/TenantProfile.cs"
|
|
provides: "AppId nullable property for storing registered app ID"
|
|
contains: "AppId"
|
|
- path: "SharepointToolbox/Services/IAppRegistrationService.cs"
|
|
provides: "Service interface with IsGlobalAdminAsync, RegisterAsync, RemoveAsync, ClearMsalSessionAsync"
|
|
exports: ["IAppRegistrationService"]
|
|
- path: "SharepointToolbox/Services/AppRegistrationService.cs"
|
|
provides: "Implementation using GraphServiceClient"
|
|
contains: "class AppRegistrationService"
|
|
- path: "SharepointToolbox.Tests/Services/AppRegistrationServiceTests.cs"
|
|
provides: "Unit tests covering admin detection, registration, rollback, removal, session clear"
|
|
min_lines: 80
|
|
key_links:
|
|
- from: "SharepointToolbox/Services/AppRegistrationService.cs"
|
|
to: "GraphServiceClient"
|
|
via: "constructor injection of GraphClientFactory"
|
|
pattern: "GraphClientFactory"
|
|
- from: "SharepointToolbox/Services/AppRegistrationService.cs"
|
|
to: "MsalClientFactory"
|
|
via: "constructor injection for session eviction"
|
|
pattern: "MsalClientFactory"
|
|
---
|
|
|
|
<objective>
|
|
Create the AppRegistrationService with full Graph API registration/removal logic, the AppRegistrationResult model, and add AppId to TenantProfile. All unit-tested with mocked Graph calls.
|
|
|
|
Purpose: The service layer is the foundation for all Entra app registration operations. It must be fully testable before any UI is wired.
|
|
Output: IAppRegistrationService + implementation + AppRegistrationResult model + TenantProfile.AppId field + unit tests
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@C:/Users/dev/.claude/get-shit-done/workflows/execute-plan.md
|
|
@C:/Users/dev/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
@.planning/phases/19-app-registration-removal/19-RESEARCH.md
|
|
|
|
<interfaces>
|
|
<!-- Existing code the executor needs -->
|
|
|
|
From SharepointToolbox/Infrastructure/Auth/GraphClientFactory.cs:
|
|
```csharp
|
|
public class GraphClientFactory
|
|
{
|
|
public GraphClientFactory(MsalClientFactory msalFactory) { }
|
|
public async Task<GraphServiceClient> CreateClientAsync(string clientId, CancellationToken ct) { }
|
|
}
|
|
```
|
|
|
|
From SharepointToolbox/Infrastructure/Auth/MsalClientFactory.cs:
|
|
```csharp
|
|
public class MsalClientFactory
|
|
{
|
|
public string CacheDirectory { get; }
|
|
public async Task<IPublicClientApplication> GetOrCreateAsync(string clientId) { }
|
|
public MsalCacheHelper GetCacheHelper(string clientId) { }
|
|
}
|
|
```
|
|
|
|
From SharepointToolbox/Services/ISessionManager.cs:
|
|
```csharp
|
|
public interface ISessionManager
|
|
{
|
|
Task<ClientContext> GetOrCreateContextAsync(TenantProfile profile, CancellationToken ct = default);
|
|
Task ClearSessionAsync(string tenantUrl);
|
|
bool IsAuthenticated(string tenantUrl);
|
|
}
|
|
```
|
|
|
|
From SharepointToolbox/Core/Models/TenantProfile.cs:
|
|
```csharp
|
|
public class TenantProfile
|
|
{
|
|
public string Name { get; set; } = string.Empty;
|
|
public string TenantUrl { get; set; } = string.Empty;
|
|
public string ClientId { get; set; } = string.Empty;
|
|
public LogoData? ClientLogo { get; set; }
|
|
}
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 1: Models + Interface + Service implementation</name>
|
|
<files>
|
|
SharepointToolbox/Core/Models/AppRegistrationResult.cs,
|
|
SharepointToolbox/Core/Models/TenantProfile.cs,
|
|
SharepointToolbox/Services/IAppRegistrationService.cs,
|
|
SharepointToolbox/Services/AppRegistrationService.cs
|
|
</files>
|
|
<behavior>
|
|
- AppRegistrationResult.Success("appId123") carries appId, IsSuccess=true
|
|
- AppRegistrationResult.Failure("msg") carries message, IsSuccess=false
|
|
- AppRegistrationResult.FallbackRequired() signals fallback path, IsSuccess=false, IsFallback=true
|
|
- TenantProfile.AppId is nullable string, defaults to null, serializes/deserializes via System.Text.Json
|
|
</behavior>
|
|
<action>
|
|
1. Create `AppRegistrationResult.cs` in `Core/Models/`:
|
|
- Static factory methods: `Success(string appId)`, `Failure(string errorMessage)`, `FallbackRequired()`
|
|
- Properties: `bool IsSuccess`, `bool IsFallback`, `string? AppId`, `string? ErrorMessage`
|
|
- Use a private constructor pattern (not record, for consistency with other models in the project)
|
|
|
|
2. Update `TenantProfile.cs`:
|
|
- Add `public string? AppId { get; set; }` property (nullable, defaults to null)
|
|
- Existing properties unchanged
|
|
|
|
3. Create `IAppRegistrationService.cs` in `Services/`:
|
|
```csharp
|
|
public interface IAppRegistrationService
|
|
{
|
|
Task<bool> IsGlobalAdminAsync(string clientId, CancellationToken ct);
|
|
Task<AppRegistrationResult> RegisterAsync(string clientId, string tenantDisplayName, CancellationToken ct);
|
|
Task RemoveAsync(string clientId, string appId, CancellationToken ct);
|
|
Task ClearMsalSessionAsync(string clientId, string tenantUrl);
|
|
}
|
|
```
|
|
|
|
4. Create `AppRegistrationService.cs` in `Services/`:
|
|
- Constructor takes `GraphClientFactory`, `MsalClientFactory`, `ISessionManager`, `ILogger<AppRegistrationService>`
|
|
- `IsGlobalAdminAsync`: calls `graphClient.Me.TransitiveMemberOf.GetAsync()` filtered on `microsoft.graph.directoryRole`, checks for roleTemplateId `62e90394-69f5-4237-9190-012177145e10`. On any exception (including 403), return false and log warning.
|
|
- `RegisterAsync`:
|
|
a. Create Application object with `DisplayName = "SharePoint Toolbox - {tenantDisplayName}"`, `SignInAudience = "AzureADMyOrg"`, `IsFallbackPublicClient = true`, `PublicClient.RedirectUris = ["https://login.microsoftonline.com/common/oauth2/nativeclient"]`, `RequiredResourceAccess` for Graph (User.Read, User.Read.All, Group.Read.All, Directory.Read.All) and SharePoint (AllSites.FullControl) using the GUIDs from research.
|
|
b. Create ServicePrincipal with `AppId = createdApp.AppId`
|
|
c. Look up Microsoft Graph resource SP via filter `appId eq '00000003-0000-0000-c000-000000000000'`, get its `Id`
|
|
d. Look up SharePoint Online resource SP via filter `appId eq '00000003-0000-0ff1-ce00-000000000000'`, get its `Id`
|
|
e. Post `OAuth2PermissionGrant` for Graph scopes (`User.Read User.Read.All Group.Read.All Directory.Read.All`) with `ConsentType = "AllPrincipals"`, `ClientId = sp.Id`, `ResourceId = graphResourceSp.Id`
|
|
f. Post `OAuth2PermissionGrant` for SharePoint scopes (`AllSites.FullControl`) same pattern
|
|
g. On any exception after Application creation: try `DELETE /applications/{createdApp.Id}` (best-effort rollback, log warning on rollback failure), return `AppRegistrationResult.Failure(ex.Message)`
|
|
h. On success: return `AppRegistrationResult.Success(createdApp.AppId!)`
|
|
- `RemoveAsync`: calls `graphClient.Applications[$"(appId='{appId}')"].DeleteAsync(cancellationToken: ct)`. Log warning on failure but don't throw.
|
|
- `ClearMsalSessionAsync`:
|
|
a. Call `_sessionManager.ClearSessionAsync(tenantUrl)`
|
|
b. Get PCA via `_msalFactory.GetOrCreateAsync(clientId)`, loop `RemoveAsync` on all accounts
|
|
c. Call `_msalFactory.GetCacheHelper(clientId).UnregisterCache(pca.UserTokenCache)`
|
|
|
|
Use `private static List<RequiredResourceAccess> BuildRequiredResourceAccess()` as a helper. Use GUIDs from research doc (Graph permissions are HIGH confidence). For SharePoint AllSites.FullControl, use GUID `56680e0d-d2a3-4ae1-80d8-3c4a5c70c4a6` from research (LOW confidence — add a comment noting it should be verified against live tenant).
|
|
</action>
|
|
<verify>
|
|
<automated>dotnet build SharepointToolbox/SharepointToolbox.csproj --no-restore 2>&1 | tail -5</automated>
|
|
</verify>
|
|
<done>All 4 files exist, solution builds clean, AppRegistrationResult has 3 factory methods, TenantProfile has AppId, IAppRegistrationService has 4 methods, AppRegistrationService implements all 4 with rollback pattern</done>
|
|
</task>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 2: Unit tests for AppRegistrationService</name>
|
|
<files>SharepointToolbox.Tests/Services/AppRegistrationServiceTests.cs</files>
|
|
<behavior>
|
|
- IsGlobalAdminAsync returns true when transitiveMemberOf contains DirectoryRole with Global Admin templateId
|
|
- IsGlobalAdminAsync returns false when no matching role
|
|
- IsGlobalAdminAsync returns false (not throws) on ServiceException/403
|
|
- RegisterAsync returns Success with appId on full happy path
|
|
- RegisterAsync calls DELETE on Application when ServicePrincipal creation fails (rollback)
|
|
- RegisterAsync calls DELETE on Application when OAuth2PermissionGrant fails (rollback)
|
|
- RemoveAsync calls DELETE on Application by appId
|
|
- ClearMsalSessionAsync calls ClearSessionAsync + removes all MSAL accounts
|
|
- AppRegistrationResult.Success carries appId, .Failure carries message, .FallbackRequired sets IsFallback
|
|
- TenantProfile.AppId round-trips through JSON (null and non-null)
|
|
</behavior>
|
|
<action>
|
|
Create `SharepointToolbox.Tests/Services/AppRegistrationServiceTests.cs` with xUnit tests. Since `GraphServiceClient` is hard to mock directly (sealed/extension methods), test strategy:
|
|
|
|
1. **AppRegistrationResult model tests** (pure logic, no mocks):
|
|
- `Success_CarriesAppId`: verify IsSuccess=true, AppId set
|
|
- `Failure_CarriesMessage`: verify IsSuccess=false, ErrorMessage set
|
|
- `FallbackRequired_SetsFallback`: verify IsFallback=true
|
|
|
|
2. **TenantProfile.AppId tests**:
|
|
- `AppId_DefaultsToNull`
|
|
- `AppId_RoundTrips_ViaJson`: serialize+deserialize with System.Text.Json, verify AppId preserved
|
|
- `AppId_Null_RoundTrips_ViaJson`: verify null survives serialization
|
|
|
|
3. **AppRegistrationService tests** — For methods that call GraphServiceClient, use the project's existing pattern: if the project uses Moq or NSubstitute (check test csproj), mock `GraphClientFactory` to return a mock `GraphServiceClient`. If mocking Graph SDK is too complex, test the logic by:
|
|
- Extracting `BuildRequiredResourceAccess()` as internal and testing the scope GUIDs/structure directly
|
|
- Testing that the service constructor accepts the right dependencies
|
|
- For integration-like behavior, mark tests with `[Trait("Category","Integration")]` and skip in CI
|
|
|
|
Check the test project's existing packages first (`dotnet list SharepointToolbox.Tests package`) to see if Moq/NSubstitute is available. Use whichever mocking library the project already uses.
|
|
|
|
All tests decorated with `[Trait("Category", "Unit")]`.
|
|
</action>
|
|
<verify>
|
|
<automated>dotnet test SharepointToolbox.Tests --filter "FullyQualifiedName~AppRegistrationServiceTests" --no-restore --verbosity normal 2>&1 | tail -20</automated>
|
|
</verify>
|
|
<done>All unit tests pass. Coverage: AppRegistrationResult 3 factory methods tested, TenantProfile.AppId serialization tested, service constructor/dependency tests pass, BuildRequiredResourceAccess structure verified</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
1. `dotnet build` — full solution compiles
|
|
2. `dotnet test SharepointToolbox.Tests --filter "FullyQualifiedName~AppRegistrationServiceTests"` — all tests green
|
|
3. TenantProfile.AppId exists as nullable string
|
|
4. IAppRegistrationService has 4 methods: IsGlobalAdminAsync, RegisterAsync, RemoveAsync, ClearMsalSessionAsync
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- AppRegistrationService implements atomic registration with rollback
|
|
- IsGlobalAdminAsync uses transitiveMemberOf (not memberOf) for nested role coverage
|
|
- All unit tests pass
|
|
- Solution builds clean with no warnings in new files
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/19-app-registration-removal/19-01-SUMMARY.md`
|
|
</output>
|