From 9ae90e971a0df3b09d22396f46f892242d145970 Mon Sep 17 00:00:00 2001 From: enisn Date: Thu, 19 Mar 2026 13:02:41 +0300 Subject: [PATCH] docs: explain external user lookup integration --- docs/en/modules/cms-kit/index.md | 50 +++++++++++++++++++++++++++++ docs/en/modules/identity.md | 55 +++++++++++++++++++++++++++++++- 2 files changed, 104 insertions(+), 1 deletion(-) diff --git a/docs/en/modules/cms-kit/index.md b/docs/en/modules/cms-kit/index.md index 630540fde9..344b719889 100644 --- a/docs/en/modules/cms-kit/index.md +++ b/docs/en/modules/cms-kit/index.md @@ -38,6 +38,56 @@ All features are individually usable. If you disable a feature, it completely di - CMS Kit uses [distributed cache](../../framework/fundamentals/caching.md) for responding faster. > Using a distributed cache, such as [Redis](../../framework/fundamentals/redis-cache.md), is highly recommended for data consistency in distributed/clustered deployments. +## Identity Integration for User Lookup + +CMS Kit uses `ICmsUserLookupService` when it needs user information for features such as comments, ratings, blog post management and user synchronization. + +If the CMS Kit and Identity modules run in the same application, no extra configuration is typically needed. + +If the Identity module runs in another application or service (for example, in a tiered or distributed solution), CMS Kit may need to call the Identity integration endpoints remotely to create or update `CmsUser` records. + +In that case, the calling application should: + +* Depend on `Volo.Abp.Identity.HttpApi.Client`. +* Add `AbpIdentityHttpApiClientModule` and an IdentityModel module (`AbpHttpClientIdentityModelWebModule` for web applications or `AbpHttpClientIdentityModelModule` for non-web hosts). +* Configure `RemoteServices:AbpIdentity` to point to the application that hosts the Identity module. +* Configure `IdentityClients` for client credentials flow so the lookup can use server-to-server authentication. +* Expose integration services on the application that hosts the Identity module. + +Example module dependency for a web application: + +```csharp +[DependsOn( + typeof(AbpIdentityHttpApiClientModule), + typeof(AbpHttpClientIdentityModelWebModule) +)] +public class MyWebModule : AbpModule +{ +} +``` + +Example `appsettings.json` configuration: + +```json +"RemoteServices": { + "AbpIdentity": { + "BaseUrl": "https://localhost:44388/", + "UseCurrentAccessToken": false + } +}, +"IdentityClients": { + "Default": { + "GrantType": "client_credentials", + "ClientId": "MyProject_Web", + "ClientSecret": "your-client-secret", + "Authority": "https://localhost:44322/", + "Scope": "your-internal-api-scope" + } +} +``` + +See the [Identity module's External User Lookup Service section](../identity.md#external-user-lookup-service) and the [Synchronous Interservice Communication guide](../../guides/synchronous-interservice-communication.md) for the complete setup. + ## How to Install [ABP CLI](../../cli) allows installing a module to a solution using the `add-module` command. You can install the CMS Kit module in a command-line terminal with the following command: diff --git a/docs/en/modules/identity.md b/docs/en/modules/identity.md index b302f74428..d92f4b7b8e 100644 --- a/docs/en/modules/identity.md +++ b/docs/en/modules/identity.md @@ -126,6 +126,58 @@ Configure(options => }); ``` +### External User Lookup Service + +`UserLookupService` first queries the local user store. If an `IExternalUserLookupServiceProvider` implementation is available, it can also query an external source, create the local copy of the user and keep the local data synchronized. + +The Identity module provides two common implementations: + +* `IdentityUserRepositoryExternalUserLookupServiceProvider`: Uses `IIdentityUserRepository` for in-process lookups. +* `HttpClientExternalUserLookupServiceProvider`: Uses `IIdentityUserIntegrationService` to resolve users from a remote Identity application. + +This is especially useful for reusable modules, such as CMS Kit, that keep module-specific user records but still need to resolve users from the Identity module. + +If your application is monolithic, this typically works without any extra configuration. + +If the Identity module runs in another application or service (for example, in a tiered or distributed solution), then the calling application should: + +* Depend on `Volo.Abp.Identity.HttpApi.Client`. +* Add `AbpIdentityHttpApiClientModule` and an IdentityModel module (`AbpHttpClientIdentityModelWebModule` for web applications or `AbpHttpClientIdentityModelModule` for non-web hosts). +* Configure the `RemoteServices:AbpIdentity` endpoint. +* Configure an `IdentityClients` entry for server-to-server authentication. +* Expose integration services on the application that hosts the Identity module. + +Example configuration for the application that exposes the Identity integration endpoints: + +```csharp +Configure(options => +{ + options.ExposeIntegrationServices = true; +}); +``` + +Example configuration for the calling application: + +```json +"RemoteServices": { + "AbpIdentity": { + "BaseUrl": "https://localhost:44388/", + "UseCurrentAccessToken": false + } +}, +"IdentityClients": { + "Default": { + "GrantType": "client_credentials", + "ClientId": "MyProject_Web", + "ClientSecret": "your-client-secret", + "Authority": "https://localhost:44322/", + "Scope": "your-internal-api-scope" + } +} +``` + +The exact `ClientId`, `ClientSecret` and `Scope` values depend on the application that hosts the Identity module. See the [Integration Services](../framework/api-development/integration-services.md) and [Synchronous Interservice Communication](../guides/synchronous-interservice-communication.md) documents for the full setup. + ## Options `IdentityOptions` is the standard [options class](../framework/fundamentals/options.md) provided by the Microsoft [Identity library](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity). So, you can set these options in the `ConfigureServices` method of your [module](../framework/architecture/modularity/basics.md) class. @@ -274,10 +326,11 @@ Following custom repositories are defined for this module: #### Application Services * `IdentityUserAppService` (implements `IIdentityUserAppService`): Implements the use cases of the user management UI. +* `IdentityUserIntegrationService` (implements `IIdentityUserIntegrationService`): Used for module-to-module and service-to-service user and role lookup operations. * `IdentityRoleAppService` (implement `IIdentityRoleAppService`): Implements the use cases of the role management UI. * `IdentityClaimTypeAppService` (implements `IIdentityClaimTypeAppService`): Implements the use cases of the claim type management UI. * `IdentitySettingsAppService` (implements `IIdentitySettingsAppService`): Used to get and update settings for the Identity module. -* `IdentityUserLookupAppService` (implements `IIdentityUserLookupAppService`): Used to get information for a user by `id` or `userName`. It is aimed to be used internally by the ABP. +* `IdentityUserLookupAppService` (implements `IIdentityUserLookupAppService`): Kept for backward compatibility and internally delegates to `IIdentityUserIntegrationService`. * `ProfileAppService` (implements `IProfileAppService`): Used to change a user's profile and the password. * ```IdentitySecurityLogAppService``` (implements ```IIdentitySecurityLogAppService```): Implements the use cases of the security logs UI. * ```OrganizationUnitAppService``` (implements ```OrganizationUnitAppService```): Implements the use cases of the organization unit management UI.