Add support for managing organizations in Keycloak

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

@@ -0,0 +1,128 @@
+using NETCore.Keycloak.Client.Exceptions;
+using NETCore.Keycloak.Client.Models;
+using NETCore.Keycloak.Client.Models.Organizations;
+
+namespace NETCore.Keycloak.Client.HttpClients.Abstraction;
+
+/// <summary>
+/// Keycloak organizations REST client.
+/// <see href="https://www.keycloak.org/docs-api/latest/rest-api/index.html#_organizations"/>
+/// </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 of the operation.
+    /// </returns>
+    /// <exception cref="KcException">Thrown if any required parameter is null, empty, or invalid.</exception>
+    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 of the operation.
+    /// </returns>
+    /// <exception cref="KcException">Thrown if any required parameter is null, empty, or invalid.</exception>
+    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 of the operation.
+    /// </returns>
+    /// <exception cref="KcException">Thrown if any required parameter is null, empty, or invalid.</exception>
+    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{T}"/> containing the <see cref="KcOrganization"/> details.
+    /// </returns>
+    /// <exception cref="KcException">Thrown if any required parameter is null, empty, or invalid.</exception>
+    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 <see cref="KcOrganization"/> objects.
+    /// </returns>
+    /// <exception cref="KcException">Thrown if any required parameter is null, empty, or invalid.</exception>
+    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{T}"/> with the count of organizations.
+    /// </returns>
+    /// <exception cref="KcException">Thrown if any required parameter is null, empty, or invalid.</exception>
+    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,141 @@
+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;
+
+/// <inheritdoc cref="IKcOrganizations"/>
+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.
+
+    /// <inheritdoc cref="IKcOrganizations.CreateAsync"/>
+    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);
+    }
+
+    /// <inheritdoc cref="IKcOrganizations.UpdateAsync"/>
+    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);
+    }
+
+    /// <inheritdoc cref="IKcOrganizations.DeleteAsync"/>
+    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);
+    }
+
+    /// <inheritdoc cref="IKcOrganizations.GetAsync"/>
+    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);
+    }
+
+    /// <inheritdoc cref="IKcOrganizations.ListAsync"/>
+    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);
+    }
+
+    /// <inheritdoc cref="IKcOrganizations.CountAsync"/>
+    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,83 @@
+using System.Text.Json.Serialization;
+
+namespace NETCore.Keycloak.Client.Models.Organizations;
+
+/// <summary>
+/// Represents an organization resource in Keycloak.
+/// <see href="https://www.keycloak.org/docs-api/latest/rest-api/index.html#OrganizationRepresentation"/>
+/// </summary>
+public sealed class KcOrganization
+{
+    /// <summary>
+    /// Gets or sets the organization id.
+    /// </summary>
+    /// <value>
+    /// A string representing the unique identifier of the organization.
+    /// </value>
+    [JsonPropertyName("id")]
+    public string Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization name.
+    /// </summary>
+    /// <value>
+    /// A string representing the display name of the organization.
+    /// </value>
+    [JsonPropertyName("name")]
+    public string Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization alias.
+    /// </summary>
+    /// <value>
+    /// A string representing an alternate identifier or alias for the organization.
+    /// </value>
+    [JsonPropertyName("alias")]
+    public string Alias { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the organization is enabled.
+    /// </summary>
+    /// <value>
+    /// A nullable boolean that is true when the organization is enabled, false when disabled,
+    /// or null if the enabled state is not set.
+    /// </value>
+    [JsonPropertyName("enabled")]
+    public bool? Enabled { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization description.
+    /// </summary>
+    /// <value>
+    /// A string containing a human-readable description for the organization.
+    /// </value>
+    [JsonPropertyName("description")]
+    public string Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets the redirect URL for the organization.
+    /// </summary>
+    /// <value>
+    /// A string representing the redirect URL associated with the organization (for example, after login or registration flows).
+    /// </value>
+    [JsonPropertyName("redirectUrl")]
+    public string RedirectUrl { get; set; }
+
+    /// <summary>
+    /// Custom attributes associated with the organization.
+    /// </summary>
+    /// <value>
+    /// A dictionary where the key is the attribute name and the value is a list of values for that attribute (Keycloak style).
+    /// </value>
+    [JsonPropertyName("attributes")]
+    public Dictionary<string, List<string>> Attributes { get; set; }
+
+    /// <summary>
+    /// Gets or sets the organization domains.
+    /// </summary>
+    /// <value>
+    /// A collection of <see cref="KcOrganizationDomain"/> representing domains associated with the organization.
+    /// </value>
+    [JsonPropertyName("domains")]
+    public ICollection<KcOrganizationDomain> Domains { get; set; } = [];
+}