DSI-8684: Public API - get service users with filter

Directory.Packages.props

@@ -70,6 +70,11 @@
     <PackageVersion Include="Swashbuckle.AspNetCore" Version="9.0.4" />
     <PackageVersion Include="System.Net.Http.Json" Version="9.0.9" />
   </ItemGroup>
+  <!-- Validation -->
+  <ItemGroup>
+    <PackageVersion Include="FluentValidation" Version="11.9.0" />
+    <PackageVersion Include="FluentValidation.DependencyInjectionExtensions" Version="11.9.0" />
+  </ItemGroup>
   <!-- Security -->
   <ItemGroup>
     <!-- Headers -->

dsi-platform.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 18
-VisualStudioVersion = 18.4.11626.88 stable
+VisualStudioVersion = 18.4.11626.88
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{3F245DBD-544F-4DD4-9B56-06B116BB9CFE}"
 EndProject
@@ -107,6 +107,12 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Dfe.SignIn.AppHost", "src\D
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Dfe.SignIn.ServiceDefaults", "src\Dfe.SignIn.ServiceDefaults\Dfe.SignIn.ServiceDefaults.csproj", "{282680D1-4103-4AC6-9238-0038A937DAA2}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{6EEA84BA-E9AD-4CD5-8E6F-4ABB0C0D4613}"
+	ProjectSection(SolutionItems) = preProject
+		Directory.Packages.props = Directory.Packages.props
+		Directory.Solution.props = Directory.Solution.props
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU

src/Dfe.SignIn.AppHost/AppHost.cs

@@ -27,6 +27,11 @@
 var internalApiConfig = builder.Configuration.GetSection("InternalApiClient");
 var redisConnectionString = redis.Resource.ConnectionStringExpression;
 
+// EntityFramework configuration sections
+var efOrganisationsConfig = builder.Configuration.GetSection("EntityFramework:Organisations");
+var efDirectoriesConfig = builder.Configuration.GetSection("EntityFramework:Directories");
+var efAuditConfig = builder.Configuration.GetSection("EntityFramework:Audit");
+
 builder.AddProject<Projects.Dfe_SignIn_Web_Help>("app-help", launchProfileName: "http")
     .WithSharedConfiguration(builder.Configuration, frontend.GetEndpoint("http"))
     .WithEnvironment("InteractionsRedisCache__ConnectionString", redisConnectionString)
@@ -64,8 +69,20 @@
     .WithEnvironment("SelectOrganisation__SelectOrganisationBaseAddress", selectOrgConfig["SelectOrganisationBaseAddress"])
     .WithEnvironment("InternalApiClient__Access__BaseAddress", internalApiConfig["Access:BaseAddress"])
     .WithEnvironment("InternalApiClient__Organisations__BaseAddress", internalApiConfig["Organisations:BaseAddress"])
+    .WithEnvironment("EntityFramework__Organisations__Username", efOrganisationsConfig["Username"])
+    .WithEnvironment("EntityFramework__Organisations__Password", efOrganisationsConfig["Password"])
+    .WithEnvironment("EntityFramework__Organisations__Name", efOrganisationsConfig["Name"])
+    .WithEnvironment("EntityFramework__Organisations__Host", efOrganisationsConfig["Host"])
+    .WithEnvironment("EntityFramework__Directories__Username", efDirectoriesConfig["Username"])
+    .WithEnvironment("EntityFramework__Directories__Password", efDirectoriesConfig["Password"])
+    .WithEnvironment("EntityFramework__Directories__Name", efDirectoriesConfig["Name"])
+    .WithEnvironment("EntityFramework__Directories__Host", efDirectoriesConfig["Host"])
+    .WithEnvironment("EntityFramework__Audit__Username", efAuditConfig["Username"])
+    .WithEnvironment("EntityFramework__Audit__Password", efAuditConfig["Password"])
+    .WithEnvironment("EntityFramework__Audit__Name", efAuditConfig["Name"])
+    .WithEnvironment("EntityFramework__Audit__Host", efAuditConfig["Host"])
     .WaitFor(redis);
 
 builder.AddExecutable("tool-tls-proxy", "pwsh", "../../", "-Command", "Start-DsiTlsProxy");
 
-builder.Build().Run();
+await builder.Build().RunAsync();

src/Dfe.SignIn.Base.Framework/Extensions/DateTimeExtensions.cs

@@ -0,0 +1,24 @@
+namespace Dfe.SignIn.Base.Framework.Extensions;
+
+/// <summary>
+/// Extensions for DateTime to handle conversion to UTC, treating unspecified kinds as UTC by default.
+/// </summary>
+public static class DateTimeExtensions
+{
+    /// <summary>
+    /// Returns the UTC equivalent of the given DateTime. If the input DateTime has an
+    /// unspecified kind, it will be treated as UTC.
+    /// </summary>
+    /// <param name="date">The DateTime to convert to UTC.</param>
+    /// <returns>The UTC equivalent of the given DateTime.</returns>
+    public static DateTime ToUtc(this DateTime date)
+        => date.Kind == DateTimeKind.Unspecified ? DateTime.SpecifyKind(date, DateTimeKind.Utc) : date.ToUniversalTime();
+
+    /// <summary>
+    /// Returns the UTC equivalent of the given DateTime, or null if the input is null.
+    /// </summary>
+    /// <param name="date">The nullable DateTime to convert to UTC.</param>
+    /// <returns>The UTC equivalent of the given DateTime, or null if the input is null.</returns>
+    public static DateTime? ToUtc(this DateTime? date)
+        => date.HasValue ? ToUtc(date.Value) : null;
+}

src/Dfe.SignIn.Core.Contracts/Access/ApplicationRole.cs

@@ -30,7 +30,7 @@ public sealed record ApplicationRole
     /// <summary>
     /// The numeric identifier of the role.
     /// </summary>
-    public required int NumericId { get; init; }
+    public required long NumericId { get; init; }
 
     /// <summary>
     /// A value indicating the status of the role.

src/Dfe.SignIn.Core.Contracts/Access/GetRolesOfApplication.cs → src/Dfe.SignIn.Core.Contracts/Access/GetApplicationRolesRequest.cs

@@ -5,8 +5,8 @@ namespace Dfe.SignIn.Core.Contracts.Access;
 /// <summary>
 /// Request to get the roles that are associated with an application.
 /// </summary>
-[AssociatedResponse(typeof(GetRolesOfApplicationResponse))]
-public sealed record GetRolesOfApplicationRequest
+[AssociatedResponse(typeof(GetApplicationRolesResponse))]
+public sealed record GetApplicationRolesRequest
 {
     /// <summary>
     /// The unique identifier of the application.
@@ -15,9 +15,9 @@ public sealed record GetRolesOfApplicationRequest
 }
 
 /// <summary>
-/// Response model for request <see cref="GetRolesOfApplicationRequest"/>.
+/// Response model for request <see cref="GetApplicationRolesRequest"/>.
 /// </summary>
-public sealed record GetRolesOfApplicationResponse
+public sealed record GetApplicationRolesResponse
 {
     /// <summary>
     /// An enumerable collection of application roles.

src/Dfe.SignIn.Core.Contracts/Applications/Application.cs

@@ -45,4 +45,14 @@ public sealed record Application
     /// page if possible. Role based services are not hidden.
     /// </summary>
     public required bool IsHiddenService { get; init; }
+
+    /// <summary>
+    /// Parent application ID, if this application is a child of another application.
+    /// </summary>
+    public Guid? ParentId { get; init; }
+
+    /// <summary>
+    /// The unique client identifier (e.g., "GIAS") of the parent application, if this application is a child of another application.
+    /// </summary>
+    public string? ParentClientId { get; init; }
 }

src/Dfe.SignIn.Core.Contracts/Applications/ApplicationRole.cs

@@ -0,0 +1,56 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Dfe.SignIn.Core.Contracts.Applications;
+
+/// <summary>
+/// A model representing a role in DfE Sign-in.
+/// </summary>
+public sealed record ApplicationRole
+{
+    /// <summary>
+    /// The unique value that identifies the role.
+    /// </summary>
+    public required Guid Id { get; init; }
+
+    /// <summary>
+    /// The parent role.
+    /// </summary>
+    public ApplicationRole? Parent { get; init; } = null;
+
+    /// <summary>
+    /// The code of the role.
+    /// </summary>
+    public required string Code { get; init; }
+
+    /// <summary>
+    /// The name of the role.
+    /// </summary>
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// The numeric identifier of the role.
+    /// </summary>
+    public required long NumericId { get; init; }
+
+    /// <summary>
+    /// A value indicating the status of the role.
+    /// </summary>
+    [EnumDataType(typeof(ApplicationRoleStatus))]
+    public required ApplicationRoleStatus Status { get; init; }
+}
+
+/// <summary>
+/// Represents the status of a role.
+/// </summary>
+public enum ApplicationRoleStatus
+{
+    /// <summary>
+    /// Indicates that a role is inactive.
+    /// </summary>
+    Inactive = 0,
+
+    /// <summary>
+    /// Indicates that a role is active.
+    /// </summary>
+    Active = 1,
+}

src/Dfe.SignIn.Core.Contracts/Applications/GetApplicationRolesRequest.cs

@@ -0,0 +1,26 @@
+using Dfe.SignIn.Base.Framework;
+
+namespace Dfe.SignIn.Core.Contracts.Applications;
+
+/// <summary>
+/// Request to get the roles that are associated with an application.
+/// </summary>
+[AssociatedResponse(typeof(GetApplicationRolesResponse))]
+public sealed record GetApplicationRolesRequest
+{
+    /// <summary>
+    /// The unique identifier of the application.
+    /// </summary>
+    public required Guid ApplicationId { get; init; }
+}
+
+/// <summary>
+/// Response model for request <see cref="GetApplicationRolesRequest"/>.
+/// </summary>
+public sealed record GetApplicationRolesResponse
+{
+    /// <summary>
+    /// An enumerable collection of application roles.
+    /// </summary>
+    public required IEnumerable<ApplicationRole> Roles { get; init; }
+}

src/Dfe.SignIn.Core.Contracts/Organisations/OrganisationRole.cs

@@ -0,0 +1,40 @@
+namespace Dfe.SignIn.Core.Contracts.Organisations;
+
+/// <summary>
+/// Represents an organisation role with an identifier and a display name.
+/// </summary>
+/// <param name="Id">The unique short identifier for the role.</param>
+/// <param name="Name">The display name of the role.</param>
+public sealed record OrganisationRole(short Id, string Name);
+
+/// <summary>
+/// Provides static references and lookup methods for well-known organisation roles.
+/// </summary>
+public static class OrganisationRoles
+{
+    /// <summary>
+    /// The standard end user role (Id = 0, Name = "End user").
+    /// </summary>
+    public static readonly OrganisationRole EndUser = new(0, "End user");
+
+    /// <summary>
+    /// The approver role (Id = 10000, Name = "Approver").
+    /// </summary>
+    public static readonly OrganisationRole Approver = new(10000, "Approver");
+
+    /// <summary>
+    /// Internal lookup dictionary for roles by their short Id.
+    /// </summary>
+    private static readonly IReadOnlyDictionary<short, OrganisationRole> ById =
+        new Dictionary<short, OrganisationRole> {
+            [EndUser.Id] = EndUser,
+            [Approver.Id] = Approver
+        };
+
+    /// <summary>
+    /// Gets a known <see cref="OrganisationRole"/> by its Id, or null if not found.
+    /// </summary>
+    /// <param name="roleId">The short Id of the role.</param>
+    /// <returns>The matching <see cref="OrganisationRole"/>, or null if not found.</returns>
+    public static OrganisationRole? FromId(short roleId) => ById.TryGetValue(roleId, out var role) ? role : null;
+}