-
Notifications
You must be signed in to change notification settings - Fork 113
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* feat: Add Sdk client vNext * Add access token management docs; Add realm client * feat: Finish UserClient; add AuthorzationOptions overloads * feat: Add IKeycloakGroupClient * feat: Add IKeycloakProtectionClient, rename Auth Server to IAuthorizationServer * docs: Add IAuthorizationServerClient docs
- Loading branch information
1 parent
332376d
commit 27590c9
Showing
118 changed files
with
12,513 additions
and
1,262 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 was deleted.
Oops, something went wrong.
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,46 @@ | ||
| # Access Token Management | ||
|
|
||
| Keycloak comes with a fully functional Admin REST API with all features provided by the Admin Console. To invoke the API you need to obtain an access token with the appropriate permissions. | ||
|
|
||
| Please refer to [official docs](https://www.keycloak.org/docs/latest/server_development/#authenticating-with-a-service-account) for more details on how to setup Service Account. | ||
|
|
||
| ## Configure Service Account | ||
|
|
||
| We need to create a *Service Account* in **master** realm, configure a special *Audience Mapper* that adds **security-admin-console** audience to the token, and assign *Service Account Role* - **"admin"**. | ||
|
|
||
| Create a service account client called **"admin-api"** and enable *Client Authentication* and *Service Account Roles*. | ||
|
|
||
| Then, [download adapter config](/configuration/configuration-keycloak#download-adapter-config) from Keycloak and added it to "appsettings.json" to "Keycloak section. Here is how it looks like: | ||
|
|
||
| ```json | ||
| { | ||
| "Keycloak": { | ||
| "realm": "master", | ||
| "auth-server-url": "http://localhost:8080/", | ||
| "ssl-required": "none", | ||
| "resource": "admin-api", | ||
| "credentials": { | ||
| "secret": "k9LYTWKfbNOyfzFt2ZZsFl3Z4x4aAecf" | ||
| }, | ||
| "confidential-port": 0 | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 💡 See [admin-api export file](/admin-rest-api/admin-api.spec) if you want to import it and see how it looks in Keycloak. | ||
|
|
||
| ## Add Token Management | ||
|
|
||
| Luckily, there is a production-ready library called [DuendeSoftware/Duende.AccessTokenManagement](https://github.com/DuendeSoftware/Duende.AccessTokenManagement) that retrieves and caches tokens. | ||
|
|
||
| To install it run: | ||
|
|
||
| ```bash | ||
| dotnet add package Duende.AccessTokenManagement | ||
| ``` | ||
|
|
||
| See [the docs](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki/worker-applications) on how to configure and use this library to use Service Accounts. | ||
|
|
||
| ### Example | ||
|
|
||
| <<< @/../tests/Keycloak.AuthServices.IntegrationTests/Admin/KeycloakRealmClientTests.cs#GetRealmAsync_RealmExists_Success {3-14,18 cs:line-numbers} |
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,7 @@ | ||
| # OpenAPI Support <Badge type="warning" text="preview" /> | ||
|
|
||
| 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. |
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,14 @@ | ||
| # Admin API Reference | ||
|
|
||
| [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk/) provides a basic support for common and most popular API endpoints. | ||
|
|
||
| The full API documentation - <https://www.keycloak.org/docs-api/latest/rest-api/>. | ||
|
|
||
| >[!IMPORTANT] | ||
| > **Keycloak.AuthServices** is an open source project with limited developer capacity. Many API endpoints might be missing. But **contributions are encouraged**! | ||
| > | ||
| > [](https://github.com/nikiforovall/keycloak-authorization-services-dotnet) | ||
| 💡**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. | ||
|
|
||
| <<< @/../src/Keycloak.AuthServices.Sdk\Admin\IKeycloakClient.cs |
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,120 @@ | ||
| # admin-api (Service Client) | ||
|
|
||
| Here is an configuration file for admin-api client. Note, you might need to assign master realm roles after export separately. | ||
|
|
||
| ```json | ||
| { | ||
| "clientId": "admin-api", // [!code highlight] | ||
| "name": "", | ||
| "description": "", | ||
| "rootUrl": "", | ||
| "adminUrl": "", | ||
| "baseUrl": "", | ||
| "surrogateAuthRequired": false, | ||
| "enabled": true, | ||
| "alwaysDisplayInConsole": false, | ||
| "clientAuthenticatorType": "client-secret", | ||
| "secret": "k9LYTWKfbNOyfzFt2ZZsFl3Z4x4aAecf", // [!code highlight] | ||
| "redirectUris": [ | ||
| "/*" | ||
| ], | ||
| "webOrigins": [ | ||
| "/*" | ||
| ], | ||
| "notBefore": 0, | ||
| "bearerOnly": false, | ||
| "consentRequired": false, | ||
| "standardFlowEnabled": true, | ||
| "implicitFlowEnabled": false, | ||
| "directAccessGrantsEnabled": true, | ||
| "serviceAccountsEnabled": true, | ||
| "publicClient": false, | ||
| "frontchannelLogout": true, | ||
| "protocol": "openid-connect", | ||
| "attributes": { | ||
| "oidc.ciba.grant.enabled": "false", | ||
| "oauth2.device.authorization.grant.enabled": "false", | ||
| "client.secret.creation.time": "1714665890", | ||
| "backchannel.logout.session.required": "true", | ||
| "backchannel.logout.revoke.offline.tokens": "false" | ||
| }, | ||
| "authenticationFlowBindingOverrides": {}, | ||
| "fullScopeAllowed": true, | ||
| "nodeReRegistrationTimeout": -1, | ||
| "protocolMappers": [ | ||
| { | ||
| "name": "Client IP Address", | ||
| "protocol": "openid-connect", | ||
| "protocolMapper": "oidc-usersessionmodel-note-mapper", | ||
| "consentRequired": false, | ||
| "config": { | ||
| "user.session.note": "clientAddress", | ||
| "introspection.token.claim": "true", | ||
| "id.token.claim": "true", | ||
| "access.token.claim": "true", | ||
| "claim.name": "clientAddress", | ||
| "jsonType.label": "String" | ||
| } | ||
| }, | ||
| { | ||
| "name": "Audience", | ||
| "protocol": "openid-connect", | ||
| "protocolMapper": "oidc-audience-mapper", | ||
| "consentRequired": false, | ||
| "config": { | ||
| "included.client.audience": "security-admin-console", // [!code highlight] | ||
| "id.token.claim": "false", | ||
| "lightweight.claim": "false", | ||
| "introspection.token.claim": "true", | ||
| "access.token.claim": "true" | ||
| } | ||
| }, | ||
| { | ||
| "name": "Client ID", | ||
| "protocol": "openid-connect", | ||
| "protocolMapper": "oidc-usersessionmodel-note-mapper", | ||
| "consentRequired": false, | ||
| "config": { | ||
| "user.session.note": "client_id", | ||
| "introspection.token.claim": "true", | ||
| "id.token.claim": "true", | ||
| "access.token.claim": "true", | ||
| "claim.name": "client_id", | ||
| "jsonType.label": "String" | ||
| } | ||
| }, | ||
| { | ||
| "name": "Client Host", | ||
| "protocol": "openid-connect", | ||
| "protocolMapper": "oidc-usersessionmodel-note-mapper", | ||
| "consentRequired": false, | ||
| "config": { | ||
| "user.session.note": "clientHost", | ||
| "introspection.token.claim": "true", | ||
| "id.token.claim": "true", | ||
| "access.token.claim": "true", | ||
| "claim.name": "clientHost", | ||
| "jsonType.label": "String" | ||
| } | ||
| } | ||
| ], | ||
| "defaultClientScopes": [ | ||
| "web-origins", | ||
| "acr", | ||
| "profile", | ||
| "roles", | ||
| "email" | ||
| ], | ||
| "optionalClientScopes": [ | ||
| "address", | ||
| "phone", | ||
| "offline_access", | ||
| "microprofile-jwt" | ||
| ], | ||
| "access": { | ||
| "view": true, | ||
| "configure": true, | ||
| "manage": true | ||
| } | ||
| } | ||
| ``` |
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,81 @@ | ||
| # 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. | ||
|
|
||
|
|
||
| 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. | ||
|
|
||
| > [!NOTE] | ||
| > See full list of API endpoints - [Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/#_overview) | ||
| Keycloak provides a comprehensive set of endpoints that cover a wide range of administrative operations. These endpoints are organized into different resource types, such as realms, users, roles, and clients, making it easy to navigate and manipulate the Keycloak configuration. | ||
|
|
||
| ❗ To get started with the Admin REST API, you need to authenticate and obtain an access token. Once you have the token, you can include it in the Authorization header of your HTTP requests to authenticate and authorize your API calls. | ||
|
|
||
| > [!NOTE] | ||
| > See [Admin REST API - Server Development](https://www.keycloak.org/docs/latest/server_development/#admin-rest-api) documentation for more details. | ||
| ## Add to your code | ||
|
|
||
| Install [Keycloak.AuthServices.Sdk](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk): | ||
|
|
||
| ```bash | ||
| dotnet add package Keycloak.AuthServices.Sdk | ||
| ``` | ||
|
|
||
| > [!IMPORTANT] | ||
| > Admin API is protected so you need to acquire access token somehow. See [Access Token Management](/admin-rest-api/access-token) | ||
| You can use `IKeycloakClient` from Web APIs, Worker, Console apps, etc. It is fully integrated with [IHttpClientFactory](https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory) and therefore you don't need to worry about `HttpClient` lifetime and the way you work with it. | ||
|
|
||
| To add it to DI, you can use convenience extensions method `AddKeycloakAdminHttpClient`: | ||
|
|
||
| ```csharp | ||
| public static IHttpClientBuilder AddKeycloakAdminHttpClient( | ||
| this IServiceCollection services, | ||
| KeycloakAdminClientOptions keycloakAdminClientOptions, | ||
| Action<HttpClient>? configureClient = default | ||
| ) | ||
| ``` | ||
|
|
||
| It registers typed client with umbrella interface `IKeycloakClient` and adds `KeycloakAdminClientOptions` to DI so you can use it as `IOptions<KeycloakAdminClientOptions>` in your code. | ||
|
|
||
| > [!NOTE] | ||
| > 💡 `AddKeycloakAdminHttpClient` returns `IHttpClientBuilder` so you can proceed and configure underlying `HttpClient`. | ||
| > | ||
| > For example, here is how to add Polly and some custom delegating handlers: | ||
| >```csharp | ||
| > services | ||
| > .AddKeycloakAdminHttpClient(configuration) | ||
| > .AddStandardResilienceHandler() | ||
| > .AddHttpMessageHandler<TimingHandler>() | ||
| > .AddHttpMessageHandler<ValidateHeaderHandler>(); | ||
| >``` | ||
| ## Console App | ||
| Here is how to use it from a Console App: | ||
| ```csharp | ||
| var services = new ServiceCollection(); | ||
| var keycloakOptions = new KeycloakAdminClientOptions | ||
| { | ||
| AuthServerUrl = "http://localhost:8080/", | ||
| Realm = "master", | ||
| Resource = "admin-api", | ||
| }; | ||
| services.AddKeycloakAdminHttpClient(keycloakOptions); | ||
| var sp = services.BuildServiceProvider(); | ||
| var client = sp.GetRequiredService<IKeycloakClient>(); | ||
| var realm = await client.GetRealmAsync("Test"); | ||
| ``` | ||
| > [!WARNING] | ||
| > In the code above the **key part** is missing - Authentication and Authorization. Because of that, you will receive **401 (Unauthorized)**. In the [next section](/admin-rest-api/access-token) I will show you how to obtain access token and successfully invoke Admin API endpoints. | ||
| Here is `IKeycloakClient`: | ||
|
|
||
| <<< @/../src/Keycloak.AuthServices.Sdk\Admin\IKeycloakClient.cs |
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,3 @@ | ||
| # IKeycloakGroupClient | ||
|
|
||
| <<< @/../src/Keycloak.AuthServices.Sdk/Admin/IKeycloakGroupClient.cs |
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,3 @@ | ||
| # IKeycloakRealmClient | ||
|
|
||
| <<< @/../src/Keycloak.AuthServices.Sdk/Admin/IKeycloakRealmClient.cs |
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,3 @@ | ||
| # IKeycloakUserClient | ||
|
|
||
| <<< @/../src/Keycloak.AuthServices.Sdk/Admin/IKeycloakUserClient.cs |
Oops, something went wrong.