Add support for managing organizations in Keycloak

NETCore.Keycloak.Client/HttpClients/Abstraction/IKcOrganizations.cs

@@ -0,0 +1,108 @@
+using NETCore.Keycloak.Client.Models;
+using NETCore.Keycloak.Client.Models.Organizations;
+
+namespace NETCore.Keycloak.Client.HttpClients.Abstraction;
+
+/// <summary>
+/// Keycloak organizations REST client
+/// </summary>
+public interface IKcOrganizations
+{
+    /// <summary>
+    /// Creates a new organization in a specified Keycloak realm.
+    ///
+    /// POST /{realm}/organizations
+    /// </summary>
+    /// <param name="realm">The Keycloak realm where the organization will be created.</param>
+    /// <param name="accessToken">The access token used for authentication.</param>
+    /// <param name="organization">The organization representation to create.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A <see cref="KcResponse{T}"/> indicating the result.</returns>
+    Task<KcResponse<object>> CreateAsync(
+        string realm,
+        string accessToken,
+        KcOrganization organization,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Updates an existing organization in a specified Keycloak realm.
+    ///
+    /// PUT /{realm}/organizations/{organizationId}
+    /// </summary>
+    /// <param name="realm">The Keycloak realm where the organization exists.</param>
+    /// <param name="accessToken">The access token used for authentication.</param>
+    /// <param name="organizationId">The ID of the organization to update.</param>
+    /// <param name="organization">The updated organization representation.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A <see cref="KcResponse{T}"/> indicating the result.</returns>
+    Task<KcResponse<object>> UpdateAsync(
+        string realm,
+        string accessToken,
+        string organizationId,
+        KcOrganization organization,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes an organization from a specified Keycloak realm.
+    ///
+    /// DELETE /{realm}/organizations/{organizationId}
+    /// </summary>
+    /// <param name="realm">The Keycloak realm where the organization exists.</param>
+    /// <param name="accessToken">The access token used for authentication.</param>
+    /// <param name="organizationId">The ID of the organization to delete.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A <see cref="KcResponse{T}"/> indicating the result.</returns>
+    Task<KcResponse<object>> DeleteAsync(
+        string realm,
+        string accessToken,
+        string organizationId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves a specific organization by its ID from a specified Keycloak realm.
+    ///
+    /// GET /{realm}/organizations/{organizationId}
+    /// </summary>
+    /// <param name="realm">The Keycloak realm to query.</param>
+    /// <param name="accessToken">The access token used for authentication.</param>
+    /// <param name="organizationId">The ID of the organization to retrieve.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A <see cref="KcResponse{OrganizationRepresentation}"/> with the organization details.</returns>
+    Task<KcResponse<KcOrganization>> GetAsync(
+        string realm,
+        string accessToken,
+        string organizationId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves a list of organizations from a specified Keycloak realm, optionally filtered by criteria.
+    ///
+    /// GET /{realm}/organizations
+    /// </summary>
+    /// <param name="realm">The Keycloak realm from which organizations will be listed.</param>
+    /// <param name="accessToken">The access token used for authentication.</param>
+    /// <param name="filter">Optional filter criteria.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A <see cref="KcResponse{T}"/> containing an enumerable of organizations.</returns>
+    Task<KcResponse<IEnumerable<KcOrganization>>> ListAsync(
+        string realm,
+        string accessToken,
+        KcOrganizationFilter filter = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves the count of organizations in a specified Keycloak realm, optionally filtered.
+    ///
+    /// GET /{realm}/organizations/count
+    /// </summary>
+    /// <param name="realm">The Keycloak realm to query.</param>
+    /// <param name="accessToken">The access token used for authentication.</param>
+    /// <param name="filter">Optional filter criteria.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A <see cref="KcResponse{long}"/> with the count of organizations.</returns>
+    Task<KcResponse<long>> CountAsync(
+        string realm,
+        string accessToken,
+        KcOrganizationFilter filter = null,
+        CancellationToken cancellationToken = default);
+}

NETCore.Keycloak.Client/HttpClients/Abstraction/IKeycloakClient.cs

@@ -76,4 +76,9 @@ public interface IKeycloakClient
     /// See <see cref="IKcScopeMappings"/> for detailed operations.
     /// </summary>
     public IKcScopeMappings ScopeMappings { get; }
+
+    /// <summary>
+    /// Gets the organizations REST client for managing organizations.
+    /// </summary>
+    public IKcOrganizations Organizations { get; }
 }

NETCore.Keycloak.Client/HttpClients/Implementation/KcOrganizations.cs

@@ -0,0 +1,136 @@
+using Microsoft.Extensions.Logging;
+using NETCore.Keycloak.Client.HttpClients.Abstraction;
+using NETCore.Keycloak.Client.Models;
+using NETCore.Keycloak.Client.Models.Organizations;
+
+namespace NETCore.Keycloak.Client.HttpClients.Implementation;
+
+/// <summary>
+///     Organization service API for managing organizations in Keycloak.
+/// </summary>
+internal sealed class KcOrganizations(string baseUrl, ILogger logger) : KcHttpClientBase(logger, baseUrl), IKcOrganizations
+{
+    // Primary constructor on the class declaration is used; no explicit ctor body required.
+
+    public Task<KcResponse<object>> CreateAsync(
+        string realm,
+        string accessToken,
+        KcOrganization organization,
+        CancellationToken cancellationToken = default)
+    {
+        ValidateAccess(realm, accessToken);
+        ValidateNotNull(nameof(organization), organization);
+
+        var url = $"{BaseUrl}/{realm}/organizations";
+        return ProcessRequestAsync<object>(
+            url,
+            HttpMethod.Post,
+            accessToken,
+            "Unable to create organization",
+            organization,
+            "application/json",
+            cancellationToken);
+    }
+
+    public Task<KcResponse<object>> UpdateAsync(
+        string realm,
+        string accessToken,
+        string organizationId,
+        KcOrganization organization,
+        CancellationToken cancellationToken = default)
+    {
+        ValidateAccess(realm, accessToken);
+        ValidateRequiredString(nameof(organizationId), organizationId);
+        ValidateNotNull(nameof(organization), organization);
+
+        var url = $"{BaseUrl}/{realm}/organizations/{organizationId}";
+        return ProcessRequestAsync<object>(
+            url,
+            HttpMethod.Put,
+            accessToken,
+            "Unable to update organization",
+            organization,
+            "application/json",
+            cancellationToken);
+    }
+
+    public Task<KcResponse<object>> DeleteAsync(
+        string realm,
+        string accessToken,
+        string organizationId,
+        CancellationToken cancellationToken = default)
+    {
+        ValidateAccess(realm, accessToken);
+        ValidateRequiredString(nameof(organizationId), organizationId);
+
+        var url = $"{BaseUrl}/{realm}/organizations/{organizationId}";
+        return ProcessRequestAsync<object>(
+            url,
+            HttpMethod.Delete,
+            accessToken,
+            "Unable to delete organization",
+            null,
+            "application/json",
+            cancellationToken);
+    }
+
+    public Task<KcResponse<KcOrganization>> GetAsync(
+        string realm,
+        string accessToken,
+        string organizationId,
+        CancellationToken cancellationToken = default)
+    {
+        ValidateAccess(realm, accessToken);
+        ValidateRequiredString(nameof(organizationId), organizationId);
+
+        var url = $"{BaseUrl}/{realm}/organizations/{organizationId}";
+        return ProcessRequestAsync<KcOrganization>(
+            url,
+            HttpMethod.Get,
+            accessToken,
+            "Unable to get organization",
+            null,
+            "application/json",
+            cancellationToken);
+    }
+
+    public Task<KcResponse<IEnumerable<KcOrganization>>> ListAsync(
+        string realm,
+        string accessToken,
+        KcOrganizationFilter filter = null,
+        CancellationToken cancellationToken = default)
+    {
+        ValidateAccess(realm, accessToken);
+        filter ??= new KcOrganizationFilter();
+
+        var url = $"{BaseUrl}/{realm}/organizations{filter.BuildQuery()}";
+        return ProcessRequestAsync<IEnumerable<KcOrganization>>(
+            url,
+            HttpMethod.Get,
+            accessToken,
+            "Unable to list organizations",
+            null,
+            "application/json",
+            cancellationToken);
+    }
+
+    public Task<KcResponse<long>> CountAsync(
+        string realm,
+        string accessToken,
+        KcOrganizationFilter filter = null,
+        CancellationToken cancellationToken = default)
+    {
+        ValidateAccess(realm, accessToken);
+        filter ??= new KcOrganizationFilter();
+
+        var url = $"{BaseUrl}/{realm}/organizations/count{filter.BuildQuery()}";
+        return ProcessRequestAsync<long>(
+            url,
+            HttpMethod.Get,
+            accessToken,
+            "Unable to count organizations",
+            null,
+            "application/json",
+            cancellationToken);
+    }
+}

NETCore.Keycloak.Client/HttpClients/Implementation/KeycloakClient.cs

@@ -44,6 +44,9 @@ public sealed class KeycloakClient : IKeycloakClient
     /// <inheritdoc cref="IKeycloakClient.ScopeMappings"/>
     public IKcScopeMappings ScopeMappings { get; }
 
+    /// <inheritdoc cref="IKeycloakClient.Organizations"/>
+    public IKcOrganizations Organizations { get; }
+
     /// <summary>
     /// Initializes a new instance of the <see cref="KeycloakClient"/> class.
     /// Provides access to various Keycloak API services through respective clients.
@@ -86,5 +89,6 @@ public KeycloakClient(string baseUrl, ILogger logger = null)
         ProtocolMappers = new KcProtocolMappers(adminUrl, logger);
         ScopeMappings = new KcScopeMappings(adminUrl, logger);
         RoleMappings = new KcRoleMappings(adminUrl, logger);
+        Organizations = new KcOrganizations(adminUrl, logger);
     }
 }

NETCore.Keycloak.Client/Models/Organizations/KcOrganization.cs

@@ -0,0 +1,59 @@
+using System.Text.Json.Serialization;
+
+namespace NETCore.Keycloak.Client.Models.Organizations;
+
+/// <summary>
+/// Represents an organization resource.
+/// </summary>
+public sealed class KcOrganization
+{
+    /// <summary>
+    /// Gets or sets the organization id.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public string Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization name.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public string Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization alias.
+    /// </summary>
+    [JsonPropertyName("alias")]
+    public string Alias { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the organization is enabled.
+    /// </summary>
+    [JsonPropertyName("enabled")]
+    public bool? Enabled { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization description.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets the redirect URL for the organization.
+    /// </summary>
+    [JsonPropertyName("redirectUrl")]
+    public string RedirectUrl { get; set; }
+
+    /// <summary>
+    /// Custom attributes.
+    /// Key = attribute name
+    /// Value = list of values (Keycloak style)
+    /// </summary>
+    [JsonPropertyName("attributes")]
+    public Dictionary<string, List<string>> Attributes { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization domains.
+    /// </summary>
+    [JsonPropertyName("domains")]
+    public List<KcOrganizationDomain> Domains { get; set; } = new();
+}

NETCore.Keycloak.Client/Models/Organizations/KcOrganizationDomain.cs

@@ -0,0 +1,21 @@
+using System.Text.Json.Serialization;
+
+namespace NETCore.Keycloak.Client.Models.Organizations;
+
+/// <summary>
+/// Represents organization domain information.
+/// </summary>
+public sealed class KcOrganizationDomain
+{
+    /// <summary>
+    /// Gets or sets the domain name.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public string Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the domain is verified.
+    /// </summary>
+    [JsonPropertyName("verified")]
+    public bool? Verified { get; set; }
+}