feat: Add Kiota SDK for Admin API (#85)

* feat: Add Kiota SDK for Admin API * Add projects description * Add KeycloakAdminApiClient * Fix build warnings * Add docs
NikiforovAll · May 5, 2024 · 5aae2c6 · 5aae2c6
1 parent cf22078
commit 5aae2c6
Show file tree

Hide file tree

Showing 477 changed files with 39,391 additions and 34 deletions.
diff --git a/KeycloakAuthorizationServicesDotNet.sln b/KeycloakAuthorizationServicesDotNet.sln
@@ -68,6 +68,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TestWebApi", "tests\TestWeb
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Keycloak.AuthServices.Authorization.Tests", "tests\Keycloak.AuthServices.Authorization.Tests\Keycloak.AuthServices.Authorization.Tests.csproj", "{331F4EF5-9CFE-4060-B903-69CCE9062BFD}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Keycloak.AuthServices.Sdk.Kiota", "src\Keycloak.AuthServices.Sdk.Kiota\Keycloak.AuthServices.Sdk.Kiota.csproj", "{8C43A1C1-0069-4B21-ADDE-5268EB214820}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -142,6 +144,10 @@ Global
 		{331F4EF5-9CFE-4060-B903-69CCE9062BFD}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{331F4EF5-9CFE-4060-B903-69CCE9062BFD}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{331F4EF5-9CFE-4060-B903-69CCE9062BFD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8C43A1C1-0069-4B21-ADDE-5268EB214820}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8C43A1C1-0069-4B21-ADDE-5268EB214820}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8C43A1C1-0069-4B21-ADDE-5268EB214820}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8C43A1C1-0069-4B21-ADDE-5268EB214820}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -165,6 +171,7 @@ Global
 		{7499F9F0-1132-46B4-AAA2-D60D9F113293} = {96857509-627A-4FD2-AC82-34387619A7B1}
 		{0F40EFE2-8D17-46B2-A91B-EC4BCB93E77C} = {96857509-627A-4FD2-AC82-34387619A7B1}
 		{331F4EF5-9CFE-4060-B903-69CCE9062BFD} = {96857509-627A-4FD2-AC82-34387619A7B1}
+		{8C43A1C1-0069-4B21-ADDE-5268EB214820} = {F9D5C5B8-9933-4AE0-ADAC-6B8C15F7552A}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {E1907BFD-C144-4B48-AA40-972F499D4E08}

diff --git a/assets/install-keycloak.png b/assets/install-keycloak.png
diff --git a/docs/.vitepress/V1/Authentication.README.md b/docs/.vitepress/V1/Authentication.README.md
@@ -33,7 +33,7 @@ For more details see an example - [Program.cs](../../samples/AuthorizationAndCle
 
 "workspace-authz" is a "confidential client".
 
-![install-keycloak](../../assets/install-keycloak.png)
+<!-- ![install-keycloak](../../assets/install-keycloak.png) -->
 
 Here is how non-confidential client installation configuration look like:
 ```csharp

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -72,6 +72,7 @@ export default withMermaid({
                             ]
                         },
                         { text: 'OpenAPI Support', link: '/admin-rest-api/admin-api-openapi' },
+                        { text: 'Generated Client - Kiota', link: '/admin-rest-api/admin-api-kiota' },
                     ]
                 },
                 {

diff --git a/docs/admin-rest-api/admin-api-kiota.md b/docs/admin-rest-api/admin-api-kiota.md
@@ -0,0 +1,28 @@
+# Generated Client - Kiota <Badge type="warning" text="preview" />
+
+This `KeycloakAdminApiClient` was generated using the *Kiota* library.
+
+> [!NOTE]
+> Kiota is a powerful command line tool developed by Microsoft that simplifies the process of generating API clients for calling any OpenAPI-described API. See [OpenAPI Support](/admin-rest-api/admin-api-openapi) for more details.
+
+```csharp
+/// <summary>
+/// Adds <see cref="KeycloakAdminApiClient"/> for Keycloak Admin API.
+/// </summary>
+/// <returns>The IHttpClientBuilder for further configuration.</returns>
+public static IHttpClientBuilder AddKeycloakAdminHttpClient(
+    this IServiceCollection services,
+    IConfiguration configuration,
+    Action<HttpClient>? configureClient = default,
+    string keycloakClientSectionName = KeycloakAdminClientOptions.Section
+);
+```
+
+>[!TIP]
+> Kiota supports partial client generation, you can generate only the functionality you need. In this case, you can use source code of this library as an example.
+
+## Example
+
+This is an example of how to use `KeycloakAdminApiClient` together with [Access Token Management](/admin-rest-api/access-token).
+
+<<< @/../tests/Keycloak.AuthServices.IntegrationTests/AdminKiota/KeycloakRealmKiotaClientTests.cs#GetRealmAsyncKiota_RealmExists_Success
diff --git a/docs/admin-rest-api/admin-api-openapi.md b/docs/admin-rest-api/admin-api-openapi.md
@@ -5,3 +5,7 @@ From Keycloak documentation:
 > The OpenAPI definitions are a feature that is currently in preview. Please provide your feedback by [joining this discussion](https://github.com/keycloak/keycloak/discussions/8898) while we’re continuing to work on this. If you find something is outdated or wrong, create a GitHub issue and provide a pull request.
 
 It means we can use OpenAPI definitions to generate full-fledged API.
+
+* <https://www.keycloak.org/docs-api/latest/rest-api/>
+* <https://www.keycloak.org/docs-api/latest/rest-api/openapi.json>
+* <https://www.keycloak.org/docs/latest/release_notes/>
diff --git a/docs/admin-rest-api/admin-api-reference.md b/docs/admin-rest-api/admin-api-reference.md
@@ -11,4 +11,6 @@ The full API documentation - <https://www.keycloak.org/docs-api/latest/rest-api/
 
 💡**Alternatively**, you may want to use OpenAPI definition for Keycloak to generate a client based on your generator of choice - see [OpenAPI Support](/admin-rest-api/admin-api-openapi) for more details.
 
+👍**Keycloak.AuthServices.Sdk.Kiota** provides out-of-the box client generated based on [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/overview) - see [Generated Client - Kiota](/admin-rest-api/admin-api-kiota) for more details.
+
 <<< @/../src/Keycloak.AuthServices.Sdk/Admin/IKeycloakClient.cs
diff --git a/docs/admin-rest-api/admin-rest-api.md b/docs/admin-rest-api/admin-rest-api.md
@@ -1,7 +1,11 @@
 # HTTP Admin REST API
 
-[Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk) provides a typed HTTP Client to work with Keycloak Admin HTTP REST API.
+[Keycloak.AuthServices](https://www.nuget.org/packages?q=Keycloak.AuthServices) has to options for integration with the Admin REST API.
 
+| NuGet | Description |
+|------|-------------|
+| [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk) | Provides a typed HTTP Client to work with Keycloak Admin HTTP REST API. A high quality SDK client written manually, but not all functionality is implemented. |
+| [Keycloak.AuthServices.Sdk.Kiota](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk.Kiota) | A client generated based on OpenAPI Spec, **full functionality** covered|
 
 The Admin REST API in Keycloak provides a programmatic way to manage and administer Keycloak instances. It allows you to perform various administrative tasks such as creating and managing realms, users, roles, clients, and more. To interact with the Admin REST API, you can use HTTP requests to send commands and retrieve data. The API follows the REST architectural style and is designed to be simple and intuitive to use.
 
@@ -31,10 +35,15 @@ You can use `IKeycloakClient` from Web APIs, Worker, Console apps, etc. It is fu
 To add it to DI, you can use convenience extensions method `AddKeycloakAdminHttpClient`:
 
 ```csharp
+/// <summary>
+/// Adds <see cref="IKeycloakClient"/>, <see cref="IKeycloakRealmClient"/>, <see cref="IKeycloakUserClient"/>, <see cref="IKeycloakGroupClient"/> HTTP clients for Keycloak Admin API.
+/// </summary>
+/// <returns>The IHttpClientBuilder for further configuration.</returns>
 public static IHttpClientBuilder AddKeycloakAdminHttpClient(
     this IServiceCollection services,
-    KeycloakAdminClientOptions keycloakAdminClientOptions,
-    Action<HttpClient>? configureClient = default
+    IConfiguration configuration,
+    Action<HttpClient>? configureClient = default,
+    string keycloakClientSectionName = KeycloakAdminClientOptions.Section
 )
 ```
 

diff --git a/docs/introduction.md b/docs/introduction.md
@@ -17,8 +17,9 @@ Keycloak.AuthServices is a [family of packages](https://www.nuget.org/packages?q
 
 ## Packages
 
-| Package                                                                                                                 | Description                                                                                                                                                                             |
-| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Keycloak.AuthServices.Authentication](https://www.nuget.org/packages/Keycloak.AuthServices.Authentication/2.0.0-pre-1) | As an OAuth2, OpenID Connect, and SAML compliant server, Keycloak can secure any application and service as long as the technology stack they are using supports any of these protocols. This library provides AspNetCore integration for JwtBearer and OpenIdConnect.                                                                                                                        |
-| [Keycloak.AuthServices.Authorization](https://www.nuget.org/packages/Keycloak.AuthServices.Authorization/2.0.0-pre-1)   | Provides Role-Based Access Control (RBAC) and integration with the Keycloak Authorization Server.                                                                                       |
-| [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk/2.0.0-pre-1)                       | Provides integration with the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/21.1.1/rest-api/), allowing you to manage users, roles, clients, and realms programmatically. Provides integration with the [Protection REST API](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_protection_api) - a UMA-compliant set of endpoints. |
+| Package                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Keycloak.AuthServices.Authentication](https://www.nuget.org/packages/Keycloak.AuthServices.Authentication) | As an OAuth2, OpenID Connect, and SAML compliant server, Keycloak can secure any application and service as long as the technology stack they are using supports any of these protocols. This library provides AspNetCore integration for JwtBearer and OpenIdConnect.                                                                                                          |
+| [Keycloak.AuthServices.Authorization](https://www.nuget.org/packages/Keycloak.AuthServices.Authorization)   | Provides Role-Based Access Control (RBAC) and integration with the Keycloak Authorization Server.                                                                                                                                                                                                                                                                               |
+| [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk)                       | Provides integration with the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/21.1.1/rest-api/), allowing you to manage users, groups, and realms programmatically. Provides integration with the [Protection REST API](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_protection_api) - a UMA-compliant set of endpoints. |
+| [Keycloak.AuthServices.Sdk.Kiota](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk.Kiota)     | Provides integration with the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/21.1.1/rest-api/). The client is generated based on Open API Spec |
diff --git a/docs/public/icon.png b/docs/public/icon.png
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
@@ -13,6 +13,7 @@
     <PackageProjectUrl>https://github.com/NikiforovAll/keycloak-authorization-services-dotnet</PackageProjectUrl>
     <RepositoryUrl>https://github.com/NikiforovAll/keycloak-authorization-services-dotnet</RepositoryUrl>
     <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>icon.png</PackageIcon>
     <PackageReleaseNotes>The release notes are available at https://github.com/NikiforovAll/keycloak-authorization-services-dotnet/releases</PackageReleaseNotes>
   </PropertyGroup>
 
@@ -24,6 +25,8 @@
   <ItemGroup>
     <!-- Include README.md to NuGet package -->
     <None Include="../../README.md" Pack="true" PackagePath="\"/>
+    <!-- Include icon.png to NuGet package -->
+    <None Include="../../docs/public/icon.png" Pack="true" PackagePath="\"/>
   </ItemGroup>
 
   <PropertyGroup Label="Build">

diff --git a/src/Directory.Packages.props b/src/Directory.Packages.props
@@ -15,6 +15,17 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0"/>
   </ItemGroup>
 
+  <ItemGroup Label="Kiota">
+		<PackageVersion Include="Microsoft.Kiota.Abstractions" Version="1.7.11" />
+		<PackageVersion Include="Microsoft.Kiota.Authentication.Azure" Version="1.1.4" />
+		<PackageVersion Include="Microsoft.Kiota.Http.HttpClientLibrary" Version="1.3.7" />
+		<PackageVersion Include="Microsoft.Kiota.Serialization.Form" Version="1.1.5" />
+		<PackageVersion Include="Microsoft.Kiota.Serialization.Json" Version="1.1.8" />
+		<PackageVersion Include="Microsoft.Kiota.Serialization.Multipart" Version="1.1.3" />
+		<PackageVersion Include="Microsoft.Kiota.Serialization.Text" Version="1.1.4" />
+	</ItemGroup>
+
+
   <ItemGroup Label="Release">
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0"/>
     <PackageVersion Include="MinVer" Version="5.0.0"/>

diff --git a/src/Keycloak.AuthServices.Authentication/Keycloak.AuthServices.Authentication.csproj b/src/Keycloak.AuthServices.Authentication/Keycloak.AuthServices.Authentication.csproj
@@ -6,7 +6,7 @@
 
   <PropertyGroup Label="Package">
     <Product>Keycloak.AuthServices.Authentication</Product>
-    <Description>OICD Authentication; JWT Bearer Authentication for Keycloak</Description>
+    <Description>Simple and configurable JWT Bearer Authentication for Web APIs and OIDC+Cookie Authentication for Web Apps.</Description>
     <PackageTags>Keycloak;Authentication;Authrorization;authserver;JWT;OICD;jwt-authentication</PackageTags>
   </PropertyGroup>
 

diff --git a/src/Keycloak.AuthServices.Authorization/Keycloak.AuthServices.Authorization.csproj b/src/Keycloak.AuthServices.Authorization/Keycloak.AuthServices.Authorization.csproj
@@ -6,8 +6,8 @@
 
   <PropertyGroup Label="Package">
     <Product>Keycloak.AuthServices.Authorization</Product>
-    <Description>Keycloak Authorization Server integration. Decision + Rpt</Description>
-    <PackageTags>Keycloak;Authrorization;authserver</PackageTags>
+    <Description>Adds Keycloak Authorization - including RBAC, Authorization Server, Claims Transformation and more.</Description>
+    <PackageTags>Keycloak;Authrorization;AuthorizationServer;RBAC</PackageTags>
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/src/Keycloak.AuthServices.Common/Keycloak.AuthServices.Common.csproj b/src/Keycloak.AuthServices.Common/Keycloak.AuthServices.Common.csproj
@@ -6,7 +6,7 @@
 
   <PropertyGroup Label="Package">
     <Product>Keycloak.AuthServices.Common</Product>
-    <Description>Utils for Keycloak.AuthServices</Description>
+    <Description>Base library for Keycloak.AuthServices packages</Description>
   </PropertyGroup>
 
 

diff --git a/src/Keycloak.AuthServices.Sdk.Kiota/Admin/AdminRequestBuilder.cs b/src/Keycloak.AuthServices.Sdk.Kiota/Admin/AdminRequestBuilder.cs
@@ -0,0 +1,33 @@
+// <auto-generated/>
+using Keycloak.AuthServices.Sdk.Kiota.Admin.Admin.Realms;
+using Microsoft.Kiota.Abstractions;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Threading.Tasks;
+using System;
+namespace Keycloak.AuthServices.Sdk.Kiota.Admin.Admin {
+    /// <summary>
+    /// Builds and executes requests for operations under \admin
+    /// </summary>
+    public class AdminRequestBuilder : BaseRequestBuilder {
+        /// <summary>The realms property</summary>
+        public RealmsRequestBuilder Realms { get =>
+            new RealmsRequestBuilder(PathParameters, RequestAdapter);
+        }
+        /// <summary>
+        /// Instantiates a new <see cref="AdminRequestBuilder"/> and sets the default values.
+        /// </summary>
+        /// <param name="pathParameters">Path parameters for the request</param>
+        /// <param name="requestAdapter">The request adapter to use to execute the requests.</param>
+        public AdminRequestBuilder(Dictionary<string, object> pathParameters, IRequestAdapter requestAdapter) : base(requestAdapter, "{+baseurl}/admin", pathParameters) {
+        }
+        /// <summary>
+        /// Instantiates a new <see cref="AdminRequestBuilder"/> and sets the default values.
+        /// </summary>
+        /// <param name="rawUrl">The raw URL to use for the request builder.</param>
+        /// <param name="requestAdapter">The request adapter to use to execute the requests.</param>
+        public AdminRequestBuilder(string rawUrl, IRequestAdapter requestAdapter) : base(requestAdapter, "{+baseurl}/admin", rawUrl) {
+        }
+    }
+}