-
Notifications
You must be signed in to change notification settings - Fork 118
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Add Aspire Hosting package (#111)
* feat: Add Keycloak.AuthServices.Aspire.Hosting package * Add Keycloak.AuthServices.Templates package * Add docs
- Loading branch information
1 parent
7e6aa0c
commit 940edad
Showing
66 changed files
with
6,786 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # Aspire Support | ||
|
|
||
| [.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview) is an opinionated, cloud ready stack for building observable, production ready, distributed applications. | ||
|
|
||
| `Keycloak.AuthServices.Aspire.Hosting` adds a support to run Keycloak Instance as a component. It is intended to be used together with `Keycloak.AuthServices`. | ||
|
|
||
| See working example here. [Examples/Aspire + Web API](/examples/aspire-web-api) | ||
|
|
||
| ## Add to existing application | ||
|
|
||
| Install [Keycloak.AuthServices.Aspire.Hosting](https://www.nuget.org/packages/Keycloak.AuthServices.Aspire.Hosting) package to "AppHost": | ||
|
|
||
| ```bash | ||
| dotnet add package Keycloak.AuthServices.Aspire.Hosting | ||
| ``` | ||
|
|
||
| Modify the `AppHost/Program.cs`: | ||
|
|
||
| ```csharp | ||
| // AppHost/Program.cs | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var keycloak = builder // [!code focus] | ||
| .AddKeycloakContainer("keycloak"); // [!code focus] | ||
| var realm = keycloak.AddRealm("Test"); // [!code focus] | ||
| builder.AddProject<Projects.Api>("api").WithReference(keycloak).WithReference(realm); // [!code focus] | ||
| builder.Build().Run(); | ||
| ``` | ||
|
|
||
| Here is what it does: | ||
|
|
||
| 1. Starts the instance of Keycloak as docker container. | ||
| 2. `WithReference(keycloak)` adds Keycloak server instance to Service Discovery. | ||
| 3. `WithReference(realm)` adds `Keycloak__Realm` and `Keycloak__AuthServerUrl` environment variables. | ||
|
|
||
| From this point you are almost finished, the only this is left is to configure Authentication missing parts: | ||
|
|
||
| ```csharp | ||
| var builder = WebApplication.CreateBuilder(args); | ||
| var services = builder.Services; | ||
| var configuration = builder.Configuration; | ||
|
|
||
| builder.AddServiceDefaults(); | ||
|
|
||
| services.AddKeycloakWebApiAuthentication( // [!code focus] | ||
| configuration, // [!code focus] | ||
| options => // [!code focus] | ||
| { // [!code focus] | ||
| options.Audience = "workspaces-client"; // [!code focus] | ||
| options.RequireHttpsMetadata = false; // [!code focus] | ||
| } // [!code focus] | ||
| ); // [!code focus] | ||
| services.AddAuthorization(); // [!code focus] | ||
| var app = builder.Build(); | ||
|
|
||
| app.UseHttpsRedirection(); | ||
|
|
||
| app.UseAuthentication(); | ||
| app.UseAuthorization(); | ||
|
|
||
| app.MapGet("/hello", () => "Hello World!").RequireAuthorization(); | ||
|
|
||
| app.Run(); | ||
|
|
||
| ``` | ||
|
|
||
| Run: | ||
|
|
||
| ```bash | ||
| dotnet run --project ./AppHost | ||
| ``` | ||
|
|
||
| ### Import configuration files | ||
|
|
||
| You can reference import files and bind Keycloak data volumes to persist Keycloak configuration and share it with others. | ||
|
|
||
| ```csharp | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var keycloak = builder | ||
| .AddKeycloakContainer("keycloak") | ||
| .WithDataVolume() | ||
| .WithImport("./KeycloakConfiguration/Test-realm.json") | ||
| .WithImport("./KeycloakConfiguration/Test-users-0.json"); | ||
|
|
||
| var realm = keycloak.AddRealm("Test"); | ||
|
|
||
| builder.AddProject<Projects.Api>("api").WithReference(keycloak).WithReference(realm); | ||
|
|
||
| builder.Build().Run(); | ||
| ``` | ||
|
|
||
| > [!TIP] | ||
| > You can sync your current configuration via CLI | ||
| Inside docker container run: | ||
|
|
||
| ```bash | ||
| /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/import --realm Test | ||
| ``` | ||
|
|
||
| ## Start from Template | ||
|
|
||
| You can use [Keycloak.AuthServices.Templates](https://www.nuget.org/packages/Keycloak.AuthServices.Templates) to scaffold the new Aspire Project that has `Keycloak.AuthServices` integration configured. | ||
|
|
||
| Install template: | ||
|
|
||
| ```bash | ||
| dotnet new install Keycloak.AuthServices.Templates | ||
| ``` | ||
|
|
||
| Scaffold a solution: | ||
|
|
||
| ```bash | ||
| dotnet new keycloak-aspire-starter -o $dev/KeycloakAspireStarter --EnableKeycloakImport | ||
| ``` | ||
|
|
||
| See [Aspire Template](/devex/templates#aspire-web-api) for more details. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| # Templates | ||
|
|
||
| You can use [dotnet-new](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new) command to scaffold various solution items. `Keyclaok.AuthServices` provides you with templates to get started with Keycloak and .NET | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Install: | ||
|
|
||
| ```bash | ||
| dotnet new install Keycloak.AuthServices.Templates | ||
| ``` | ||
|
|
||
| List installed packages: | ||
|
|
||
| ```bash | ||
| ❯ dotnet new list keycloak | ||
| # These templates matched your input: 'keycloak' | ||
|
|
||
| # Template Name Short Name Language Tags | ||
| # ----------------------- ----------------------- -------- ------------------------------------- | ||
| # Keycloak Aspire Starter keycloak-aspire-starter [C#] Common/.NET Aspire/Cloud/API/Keycloak | ||
| # Keycloak WebApi keycloak-webapi [C#] Common/API/Keycloak | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > To successfully run commands below - replace `$dev` with the actual working directory. | ||
| > | ||
| > You can set shell variable by running next command: `export dev=~/projects` | ||
| ## Web API | ||
|
|
||
| Use `dotnet new keycloak-webapi -h` to discover how to use this template. | ||
|
|
||
| ### Example | ||
|
|
||
| Verify the output of the command by using `--dry-run` option: | ||
|
|
||
| ```bash | ||
| ❯ dotnet new keycloak-webapi -o $dev/KeycloakWebApi --dry-run | ||
| # File actions would have been taken: | ||
| # Create: $dev\KeycloakWebApi\Directory.Build.props | ||
| # Create: $dev\KeycloakWebApi\Directory.Packages.props | ||
| # Create: $dev\KeycloakWebApi\Extensions.OpenApi.cs | ||
| # Create: $dev\KeycloakWebApi\KeycloakWebApi.csproj | ||
| # Create: $dev\KeycloakWebApi\Program.cs | ||
| # Create: $dev\KeycloakWebApi\Properties\launchSettings.json | ||
| # Create: $dev\KeycloakWebApi\README.md | ||
| # Create: $dev\KeycloakWebApi\appsettings.Development.json | ||
| # Create: $dev\KeycloakWebApi\appsettings.json | ||
| ``` | ||
|
|
||
| Generate: | ||
|
|
||
| ```bash | ||
| ❯ dotnet new keycloak-webapi -o $dev/KeycloakWebApi | ||
| # The template "Keycloak WebApi" was created successfully. | ||
| ``` | ||
|
|
||
| Run: | ||
|
|
||
| ```bash | ||
| ❯ dotnet run --project $dev/KeycloakWebApi | ||
| # Building... | ||
| # info: Microsoft.Hosting.Lifetime[14] | ||
| # Now listening on: https://localhost:7107 | ||
| # info: Microsoft.Hosting.Lifetime[14] | ||
| # Now listening on: http://localhost:5064 | ||
| # info: Microsoft.Hosting.Lifetime[0] | ||
| # Application started. Press Ctrl+C to shut down. | ||
| # info: Microsoft.Hosting.Lifetime[0] | ||
| # Hosting environment: Development | ||
| # info: Microsoft.Hosting.Lifetime[0] | ||
| # Content root path: $dev\KeycloakWebApi | ||
| ``` | ||
|
|
||
| ⚠️To finish the configuration process you will need to: | ||
|
|
||
| 1. Start Keycloak instance, see the generated `README.md` file. | ||
| 2. Create a *Realm* | ||
| 3. Register a *Client* | ||
| 4. Update `appsettings.Development.json` correspondingly. | ||
|
|
||
| ## Aspire + Web API | ||
|
|
||
| Use `dotnet new keycloak-aspire-starter -h` to discover how to use this template. | ||
|
|
||
| ### Example | ||
|
|
||
| Verify the output of the command by using `--dry-run` option: | ||
|
|
||
| ```bash | ||
| ❯ dotnet new keycloak-aspire-starter -o $dev/KeycloakAspireStarter --EnableKeycloakImport --dry-run | ||
| # File actions would have been taken: | ||
| # Create: $dev\KeycloakAspireStarter\.gitignore | ||
| # Create: $dev\KeycloakAspireStarter\Api\Api.csproj | ||
| # Create: $dev\KeycloakAspireStarter\Api\Extensions.OpenApi.cs | ||
| # Create: $dev\KeycloakAspireStarter\Api\Program.cs | ||
| # Create: $dev\KeycloakAspireStarter\Api\Properties\launchSettings.json | ||
| # Create: $dev\KeycloakAspireStarter\Api\appsettings.Development.json | ||
| # Create: $dev\KeycloakAspireStarter\Api\appsettings.json | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\AppHost.csproj | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\KeycloakConfiguration\Test-realm.json | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\KeycloakConfiguration\Test-users-0.json | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\Program.cs | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\Properties\launchSettings.json | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\appsettings.Development.json | ||
| # Create: $dev\KeycloakAspireStarter\AppHost\appsettings.json | ||
| # Create: $dev\KeycloakAspireStarter\Directory.Build.props | ||
| # Create: $dev\KeycloakAspireStarter\Directory.Packages.props | ||
| # Create: $dev\KeycloakAspireStarter\KeycloakAspireStarter.sln | ||
| # Create: $dev\KeycloakAspireStarter\README.md | ||
| # Create: $dev\KeycloakAspireStarter\ServiceDefaults\Extensions.cs | ||
| # Create: $dev\KeycloakAspireStarter\ServiceDefaults\ServiceDefaults.csproj | ||
| # Create: $dev\KeycloakAspireStarter\global.json | ||
| ``` | ||
|
|
||
| Generate: | ||
|
|
||
| ```bash | ||
| ❯ dotnet new keycloak-aspire-starter -o $dev/KeycloakAspireStarter --EnableKeycloakImport | ||
| # The template "Keycloak Aspire Starter" was created successfully. | ||
| ``` | ||
|
|
||
| We want to enable automatically imported realm by adding `--EnableKeycloakImport` option. | ||
|
|
||
| Run: | ||
|
|
||
| ```bash | ||
| ❯ dotnet run --project $dev/KeycloakAspireStarter/AppHost/ | ||
| # Building... | ||
| # info: Aspire.Hosting.DistributedApplication[0] | ||
| # Aspire version: 8.0.1+a6e341ebbf956bbcec0dda304109815fcbae70c9 | ||
| # info: Aspire.Hosting.DistributedApplication[0] | ||
| # Distributed application starting. | ||
| # info: Aspire.Hosting.DistributedApplication[0] | ||
| # Application host directory is: $dev\KeycloakAspireStarter\AppHost | ||
| # info: Aspire.Hosting.DistributedApplication[0] | ||
| # Now listening on: http://localhost:15056 | ||
| # info: Aspire.Hosting.DistributedApplication[0] | ||
| # Distributed application started. Press Ctrl+C to shut down. | ||
| ``` | ||
|
|
||
| Additionally, open Keycloak master realm by navigating: <http://localhost:8080/>. Use `admin:admin` as credentials. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # Aspire + Web API | ||
|
|
||
| This samples contains Keycloak installation configured via configuration files. | ||
|
|
||
| Here is what it does: | ||
|
|
||
| 1. Starts a Keycloak Instance as part of Aspire Integration | ||
| 2. Imports realm and test users (`test1:test`, `test2:test`) | ||
|
|
||
| The Keycloak is already configured, all you need to do is to run sample and try to retrieve token via Swagger UI. | ||
|
|
||
| Run: | ||
|
|
||
| ```bash | ||
| dotnet run --project ./AppHost | ||
| ``` | ||
|
|
||
| ## Code | ||
|
|
||
| `AppHost`: | ||
|
|
||
| <<< @/../samples/GettingStartedAndAspire/AppHost/Program.cs | ||
|
|
||
| `Api`: | ||
|
|
||
| <<< @/../samples/GettingStartedAndAspire/Api/Program.cs | ||
|
|
||
| See sample source code: [keycloak-authorization-services-dotnet/tree/main/samples/GettingStartedAndAspire](https://github.com/NikiforovAll/keycloak-authorization-services-dotnet/tree/main/samples/GettingStartedAndAspire) |
Oops, something went wrong.