From 6b111b71dbfa15ec341233eb11b1f4cdad441b91 Mon Sep 17 00:00:00 2001 From: maliming Date: Sun, 19 Jul 2026 12:10:23 +0800 Subject: [PATCH] Update IdentityServer module documentation --- docs/en/modules/identity-server-pro.md | 81 +++++++---- docs/en/modules/identity-server.md | 126 +++++++++++++++--- .../identityserver-to-openiddict.md | 18 +-- .../identityserver4-step-by-step.md | 22 +-- .../deployment/identityserver-deployment.md | 82 +++--------- 5 files changed, 206 insertions(+), 123 deletions(-) diff --git a/docs/en/modules/identity-server-pro.md b/docs/en/modules/identity-server-pro.md index 48ead33082..14aa5bf278 100644 --- a/docs/en/modules/identity-server-pro.md +++ b/docs/en/modules/identity-server-pro.md @@ -16,19 +16,22 @@ This module provides integration and management functionality for Identity Serve * Set **permissions** for clients. * Create **standard identity resources** (like role, profile) easily. * Create custom **identity resources**. -* Manage **API resources** +* Manage **API resources**. +* Manage **API scopes**. + +> **Legacy module:** Current ABP startup templates use the [OpenIddict module](./openiddict.md). This IdentityServer4 administration module remains available for existing applications that still use the [open-source IdentityServer integration](identity-server.md), but it is not installed in newly generated applications. See [the module description page](https://abp.io/modules/Volo.identityserver.Ui) for an overview of the module features. ## How to Install -Identity Server is pre-installed in [the startup templates](../solution-templates). So, no need to manually install it. +This module was pre-installed in startup templates before ABP v6.0. Current templates use OpenIddict. Install this module only in an application that uses IdentityServer4, and don't install the IdentityServer and OpenIddict provider modules together. ## Packages This module follows the [module development best practices guide](../framework/architecture/best-practices) and consists of several NuGet and NPM packages. See the guide if you want to understand the packages and relations between them. -You can visit [Identity module package list page](https://abp.io/packages?moduleName=Volo.Identity.Pro) to see list of packages related with this module. +You can visit the [Identity Server module package list](https://abp.io/packages?moduleName=Volo.IdentityServer.Ui) to see the related packages. ## User Interface @@ -39,6 +42,7 @@ Identity Server module adds the following items to the "Main" menu, under the "A * **Clients**: Client management page. * **Identity resources**: Identity resource management page. * **API resources**: API resource management page. +* **API scopes**: API scope management page. `AbpIdentityServerMenuNames` class has the constants for the menu item names. @@ -54,6 +58,8 @@ You can create new clients or edit existing clients in this page: ![identity-server-edit-client-modal](../images/identity-server-edit-client-modal.png) +New client secrets submitted during create or update are SHA-256 hashed before they are stored. Configure the consuming client with the original secret value, not the stored hash, and retain the original value in your secret-management system because it cannot be recovered from the hash. + #### Identity Resource Management Identity resource page is used to manage identity resources of Identity Server. Identity resources are data like user ID, name, or email address of a user. @@ -76,9 +82,15 @@ You can create a new API resource or edit an existing API resource in this page: ![identity-server-edit-api-resource-modal](../images/identity-server-edit-api-resource-modal.png) +New API resource secrets submitted during update are also SHA-256 hashed before persistence. The consumer must use the original secret value. + +#### API Scope Management + +API scopes define the scopes that clients can request. The API scopes page allows you to create, update and delete scopes independently from API resources. + ## Data Seed -This module adds some initial data (see [the data seed system](../framework/infrastructure/data-seeding.md)) to the database when you run the `.DbMigrator` application: +The domain package provides `IIdentityResourceDataSeeder`, which a legacy application can call from its IdentityServer data seed contributor when the `.DbMigrator` application runs (see the [data seed system](../framework/infrastructure/data-seeding.md)): * Creates standard identity resources which are role, profile, phone, openid, email and address. @@ -106,6 +118,7 @@ public override void PreConfigureServices(ServiceConfigurationContext context) * `UpdateAbpClaimTypes` (default: true): Updates `AbpClaimTypes` to be compatible with identity server claims. * `IntegrateToAspNetIdentity` (default: true): Integrate to ASP.NET Identity. * `AddDeveloperSigningCredential` (default: true): Set false to suppress AddDeveloperSigningCredential() call on the IIdentityServerBuilder. +* `AddIdentityServerCookieAuthentication` (default: true): Adds IdentityServer's default cookie authentication handlers. Set it to `false` when the host registers and configures these handlers itself. `IIdentityServerBuilder` can be configured in `PreConfigureServices` method of your Identity Server [module](../framework/architecture/modularity/basics.md). Example: @@ -132,9 +145,15 @@ This module follows the [Entity Best Practices & Conventions](../framework/archi API Resources are needed for allowing clients to request access tokens. * `ApiResource` (aggregate root): Represents an API resource in the system. - * `ApiSecret` (collection): secrets of the API resource. - * `ApiScope` (collection): scopes of the API resource. + * `ApiResourceSecret` (collection): secrets of the API resource. + * `ApiResourceScope` (collection): scope names associated with the API resource. * `ApiResourceClaim` (collection): claims of the API resource. + +##### ApiScope + +* `ApiScope` (aggregate root): Represents an API scope. + * `ApiScopeClaim` (collection): Claims included for the scope. + * `ApiScopeProperty` (collection): Custom properties of the scope. ##### Client @@ -157,12 +176,16 @@ Persisted Grants stores AuthorizationCodes, RefreshTokens and UserConsent. * `PersistedGrant` (aggregate root): Represents PersistedGrant for identity server. +##### DeviceFlowCodes + +* `DeviceFlowCodes` (aggregate root): Stores device authorization data until it expires. + ##### IdentityResource Identity resources are data like user ID, name, or email address of a user. -* `IdentityResource` (aggregate root): Represents and Identity Server identity resource. - * `IdentityClaim` (collection): Claims of identity resource. +* `IdentityResource` (aggregate root): Represents an Identity Server identity resource. + * `IdentityResourceClaim` (collection): Claims of the identity resource. #### Repositories @@ -171,7 +194,9 @@ This module follows the [Repository Best Practices & Conventions](../framework/a Following custom repositories are defined for this module: * `IApiResourceRepository` +* `IApiScopeRepository` * `IClientRepository` +* `IDeviceFlowCodesRepository` * `IPersistentGrantRepository` * `IIdentityResourceRepository` @@ -193,9 +218,10 @@ This module doesn't define any settings. #### Application Services -* `ApiResourceAppService` (implements `IApiResourceAppService`): Implements the use cases of the API resource management UI. -* `IdentityServerClaimTypeAppService` (implement `IIdentityServerClaimTypeAppService`): Used to get list of claims. -* `ApiResourceAppService` (implements `IApiResourceAppService`): Implements the use cases of the API resource management UI. +* `ClientAppService` (implements `IClientAppService`): Implements client management and client permission operations. +* `IdentityServerClaimTypeAppService` (implements `IIdentityServerClaimTypeAppService`): Gets the available claim types. +* `ApiResourceAppService` (implements `IApiResourceAppService`): Implements API resource management. +* `ApiScopeAppService` (implements `IApiScopeAppService`): Implements API scope management. * `IdentityResourceAppService` (implements `IIdentityResourceAppService`): Implements the use cases of the Identity resource management UI. ### Database Providers @@ -212,15 +238,20 @@ This module uses `AbpIdentityServer` for the connection string name. If you don' See the [connection strings](../framework/fundamentals/connection-strings.md) documentation for details. +IdentityServer configuration is host data. The built-in EF Core and MongoDB contexts ignore the current tenant, and the EF Core model isn't added to a tenant-only database. + #### Entity Framework Core ##### Tables * **IdentityServerApiResources** - * IdentityServerApiSecrets - * IdentityServerApiScopes - * IdentityServerApiScopeClaims - * IdentityServerApiClaims + * IdentityServerApiResourceSecrets + * IdentityServerApiResourceScopes + * IdentityServerApiResourceClaims + * IdentityServerApiResourceProperties +* **IdentityServerApiScopes** + * IdentityServerApiScopeClaims + * IdentityServerApiScopeProperties * **IdentityServerClients** * IdentityServerClientScopes * IdentityServerClientSecrets @@ -232,21 +263,25 @@ See the [connection strings](../framework/fundamentals/connection-strings.md) do * IdentityServerClientClaims * IdentityServerClientProperties * **IdentityServerPersistedGrants** +* **IdentityServerDeviceFlowCodes** * **IdentityServerIdentityResources** - * IdentityServerIdentityClaims + * IdentityServerIdentityResourceClaims + * IdentityServerIdentityResourceProperties #### MongoDB ##### Collections * **IdentityServerApiResources** +* **IdentityServerApiScopes** * **IdentityServerClients** * **IdentityServerPersistedGrants** +* **IdentityServerDeviceFlowCodes** * **IdentityServerIdentityResources** ### Permissions -See the `AbpIdentityServerPermissions` class members for all permissions defined for this module. +The module defines separate read, create, update and delete permissions for clients, identity resources, API resources and API scopes. Client management also has a permission for managing the permissions granted to a client. See the `AbpIdentityServerPermissions` class for the exact permission names. ### Angular UI @@ -266,7 +301,7 @@ export const appConfig: ApplicationConfig = { }; ``` -The identity server module should be imported and lazy-loaded in your routing module. It has a static `creatRoutes` method for configuration. Available options are listed below. It is available for import from `@volo/abp.ng.identity-server`. +The Identity Server module should be lazy-loaded in your routing configuration. Import and call the `createRoutes` function from `@volo/abp.ng.identity-server`. Available options are listed below. ```js // app.routes.ts @@ -280,17 +315,17 @@ const APP_ROUTES: Routes = [ ]; ``` -> If you have generated your project via the startup template, you do not have to do anything, because it already has both files configured. +> Applications generated from a legacy IdentityServer startup template already have both files configured.

Options

-You can modify the look and behavior of the module pages by passing the following options to `createRoutes` static method: +You can modify the look and behavior of the module pages by passing the following options to the `createRoutes` function: - **entityActionContributors:** Changes grid actions. Please check [Entity Action Extensions for Angular](../framework/ui/angular/entity-action-extensions.md) for details. - **toolbarActionContributors:** Changes page toolbar. Please check [Page Toolbar Extensions for Angular](../framework/ui/angular/page-toolbar-extensions.md) for details. - **entityPropContributors:** Changes table columns. Please check [Data Table Column Extensions for Angular](../framework/ui/angular/data-table-column-extensions.md) for details. - **createFormPropContributors:** Changes create form fields. Please check [Dynamic Form Extensions for Angular](../framework/ui/angular/dynamic-form-extensions.md) for details. -- **editFormPropContributors:** Changes create form fields. Please check [Dynamic Form Extensions for Angular](../framework/ui/angular/dynamic-form-extensions.md) for details. +- **editFormPropContributors:** Changes edit form fields. Please check [Dynamic Form Extensions for Angular](../framework/ui/angular/dynamic-form-extensions.md) for details. #### Services / Models @@ -330,6 +365,6 @@ export const environment = { The Identity Server module remote URL configuration shown above is optional. If you don't set a URL, the `default.url` will be used as fallback. -## Distributed Events +## CORS Cache Invalidation -This module defines events for `Client` aggregate and `ClientCorsOrigin` entity. When a `Client` or `ClientCorsOrigin` changes, `AllowedCorsOriginsCacheItemInvalidator` invalidates the cache for `AllowedCorsOriginsCacheItem`. See the [standard distributed events](../framework/infrastructure/event-bus/distributed) for more information about distributed events. +When a `Client` or `ClientCorsOrigin` changes in the current process, local entity-change handlers invalidate the cached set of allowed CORS origins. Applications don't need to clear this cache after using the module's repositories or application services. diff --git a/docs/en/modules/identity-server.md b/docs/en/modules/identity-server.md index 5df207a17b..f79f135056 100644 --- a/docs/en/modules/identity-server.md +++ b/docs/en/modules/identity-server.md @@ -7,13 +7,15 @@ # IdentityServer Module -IdentityServer module provides a full integration with the [IdentityServer4](https://github.com/IdentityServer/IdentityServer4) (IDS) framework, which provides advanced authentication features like single sign-on and API access control. This module persists clients, resources and other IDS-related objects to database. **This module is replaced by** [OpenIddict module](./openiddict.md) after ABP v6.0 in the startup templates. +IdentityServer module provides a full integration with the [IdentityServer4](https://github.com/IdentityServer/IdentityServer4) (IDS) framework, which provides advanced authentication features like single sign-on and API access control. This module persists clients, resources and other IDS-related objects to a database. -> Note: You can not use IdentityServer and OpenIddict modules together. They are separate OpenID provider libraries for the same job. +> **Legacy module:** The ABP startup templates have used the [OpenIddict module](./openiddict.md) instead of IdentityServer since ABP v6.0. IdentityServer4 is archived and no longer maintained by its owners. ABP still ships the IdentityServer integration packages for applications that already depend on them, but new applications should use OpenIddict. See the [IdentityServer to OpenIddict migration guide](../release-info/migration-guides/identityserver-to-openiddict.md) when upgrading an existing application. + +> Note: You cannot use the IdentityServer and OpenIddict modules together. They are separate OpenID provider libraries for the same job. ## How to Install -You don't need this module when you are using OpenIddict module. However, if you want to keep using IdentityServer4 for your applications, you can install this module and remove the OpenIddict module. You can continue to use it as package and get updates easily, or you can include its source code into your solution (see `get-source` [CLI](../cli) command) to develop your custom module. +You don't need this module when you are using the OpenIddict module. If an existing application must keep using IdentityServer4, install the corresponding IdentityServer packages and remove the OpenIddict modules. You can use the released packages or include the module source code in your solution (see the `get-source` [CLI](../cli) command) to customize it. ### The Source Code @@ -49,6 +51,7 @@ public override void PreConfigureServices(ServiceConfigurationContext context) * `UpdateAbpClaimTypes` (default: true): Updates `AbpClaimTypes` to be compatible with identity server claims. * `IntegrateToAspNetIdentity` (default: true): Integrate to ASP.NET Identity. * `AddDeveloperSigningCredential` (default: true): Set false to suppress AddDeveloperSigningCredential() call on the IIdentityServerBuilder. +* `AddIdentityServerCookieAuthentication` (default: true): Adds IdentityServer's default cookie authentication handlers. Set it to `false` when the host registers and configures these handlers itself. `IIdentityServerBuilder` can be configured in `PreConfigureServices` method of your Identity Server [module](../framework/architecture/modularity/basics.md). Example: @@ -62,6 +65,61 @@ public override void PreConfigureServices(ServiceConfigurationContext context) } ```` +### AbpClaimsServiceOptions + +`AbpClaimsServiceOptions.RequestedClaims` adds claim types to the set requested from the profile service while IdentityServer creates tokens. The module adds ABP's tenant and edition claim types by default. You can append application-specific claim types in `ConfigureServices`: + +````csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.RequestedClaims.Add("department_id"); + }); +} +```` + +The profile service must also issue the claim for the current user; adding its name to this list does not create the claim value. + +### TokenCleanupOptions + +The module registers a background worker that removes expired persisted grants and device-flow codes. Configure it in `ConfigureServices`: + +````csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + Configure(options => + { + options.IsCleanupEnabled = true; + options.CleanupPeriod = 3_600_000; + }); +} +```` + +* `IsCleanupEnabled` (default: `true`) controls whether the worker is registered. The global [background worker](../framework/infrastructure/background-workers/index.md) switch must also be enabled for it to run. +* `CleanupPeriod` (default: `3,600,000` milliseconds) sets the interval between cleanup passes. + +The worker uses the distributed lock named `TokenCleanupBackgroundWorker`, so only the instance that acquires the lock performs a cleanup pass. `CleanupBatchSize` and `CleanupLoopCount` are obsolete and are no longer used by the cleanup service. + +### Wildcard Subdomains for Client URLs + +IdentityServer normally requires exact redirect URI and CORS origin matches. For a multi-tenant application that uses subdomains, the module provides replacement validators for client values containing a `{0}` placeholder, such as `https://{0}.mydomain.com/signin-oidc`: + +````csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + context.Services.AddAbpStrictRedirectUriValidator(); + context.Services.AddAbpClientConfigurationValidator(); + context.Services.AddAbpWildcardSubdomainCorsPolicyService(); +} +```` + +Register all three services when both redirect URLs and CORS origins use the placeholder. Keep the scheme, host suffix and port as restrictive as possible; these validators expand the configured client URL boundary. + +`AbpStrictRedirectUriValidator` also accepts the placeholder-free form when the configured URL with `{0}.` removed contains the requested URI. For example, configuring `http://{0}.ng.abp.io/index.html` also accepts `http://ng.abp.io`. This fallback can accept a requested URI with a shorter path than the configured value. Do not register the wildcard validator for clients that require exact redirect-path matching; keep IdentityServer's default strict validator and enumerate their exact redirect URIs instead. + +`AbpWildcardSubdomainCorsPolicyService` has equivalent placeholder-free behavior for origins: configuring `https://{0}.abp.io` also accepts the base origin `https://abp.io`. CORS origins have no path component, so constrain the scheme, host suffix and port. + ## Internals ### Domain Layer @@ -73,10 +131,18 @@ public override void PreConfigureServices(ServiceConfigurationContext context) API Resources are needed for allowing clients to request access tokens. * `ApiResource` (aggregate root): Represents an API resource in the system. - * `ApiSecret` (collection): secrets of the API resource. - * `ApiScope` (collection): scopes of the API resource. + * `ApiResourceSecret` (collection): secrets of the API resource. + * `ApiResourceScope` (collection): scope names associated with the API resource. * `ApiResourceClaim` (collection): claims of the API resource. +##### ApiScope + +API scopes model the scopes that clients can request independently from API resources. + +* `ApiScope` (aggregate root): Represents an API scope. + * `ApiScopeClaim` (collection): Claims included for the scope. + * `ApiScopeProperty` (collection): Custom properties of the scope. + ##### Client Clients represent applications that can request tokens from your Identity Server. @@ -98,25 +164,31 @@ Persisted Grants stores AuthorizationCodes, RefreshTokens and UserConsent. * `PersistedGrant` (aggregate root): Represents PersistedGrant for identity server. +##### DeviceFlowCodes + +* `DeviceFlowCodes` (aggregate root): Stores the user and device codes and serialized data used by the device authorization flow until they expire. + ##### IdentityResource Identity resources are data like user ID, name, or email address of a user. -* `IdentityResource` (aggregate root): Represents and Identity Server identity resource. - * `IdentityClaim` (collection): Claims of identity resource. +* `IdentityResource` (aggregate root): Represents an Identity Server identity resource. + * `IdentityResourceClaim` (collection): Claims of the identity resource. #### Repositories Following custom repositories are defined for this module: * `IApiResourceRepository` +* `IApiScopeRepository` * `IClientRepository` +* `IDeviceFlowCodesRepository` * `IPersistentGrantRepository` * `IIdentityResourceRepository` #### Domain Services -This module doesn't contain any domain service but overrides the services below; +The module integrates the following IdentityServer services: * `AbpProfileService` (Used when `AbpIdentityServerBuilderOptions.IntegrateToAspNetIdentity` is true) * `AbpClaimsService` @@ -128,12 +200,7 @@ This module doesn't define any settings. ### Application Layer -#### Application Services - -* `ApiResourceAppService` (implements `IApiResourceAppService`): Implements the use cases of the API resource management UI. -* `IdentityServerClaimTypeAppService` (implement `IIdentityServerClaimTypeAppService`): Used to get list of claims. -* `ApiResourceAppService` (implements `IApiResourceAppService`): Implements the use cases of the API resource management UI. -* `IdentityResourceAppService` (implements `IIdentityResourceAppService`): Implements the use cases of the Identity resource management UI. +The open-source module doesn't provide application services or HTTP APIs for administration. The [Identity Server Pro module](identity-server-pro.md) provides the management application and user interfaces. ### Database Providers @@ -149,15 +216,22 @@ This module uses `AbpIdentityServer` for the connection string name. If you don' See the [connection strings](../framework/fundamentals/connection-strings.md) documentation for details. +IdentityServer configuration is host data. The built-in EF Core and MongoDB contexts ignore the current tenant, and `ConfigureIdentityServer()` skips the model when an EF Core database is configured as tenant-only. Keep the IdentityServer tables or collections in the host/shared database when tenants use separate databases. + +The EF Core and MongoDB provider modules replace IdentityServer's in-memory stores with database-backed stores. If no persistence provider registers a client store, resource store, persisted-grant store or device-flow store, the domain module falls back to values from the `IdentityServer:Clients`, `IdentityServer:ApiResources` and `IdentityServer:IdentityResources` configuration sections and to in-memory grant/device stores. Do not rely on these fallback stores for production persistence. + #### Entity Framework Core ##### Tables * **IdentityServerApiResources** - * IdentityServerApiSecrets - * IdentityServerApiScopes - * IdentityServerApiScopeClaims - * IdentityServerApiClaims + * IdentityServerApiResourceSecrets + * IdentityServerApiResourceScopes + * IdentityServerApiResourceClaims + * IdentityServerApiResourceProperties +* **IdentityServerApiScopes** + * IdentityServerApiScopeClaims + * IdentityServerApiScopeProperties * **IdentityServerClients** * IdentityServerClientScopes * IdentityServerClientSecrets @@ -169,14 +243,26 @@ See the [connection strings](../framework/fundamentals/connection-strings.md) do * IdentityServerClientClaims * IdentityServerClientProperties * **IdentityServerPersistedGrants** +* **IdentityServerDeviceFlowCodes** * **IdentityServerIdentityResources** - * IdentityServerIdentityClaims + * IdentityServerIdentityResourceClaims + * IdentityServerIdentityResourceProperties #### MongoDB ##### Collections * **IdentityServerApiResources** +* **IdentityServerApiScopes** * **IdentityServerClients** * **IdentityServerPersistedGrants** -* **IdentityServerIdentityResources** \ No newline at end of file +* **IdentityServerDeviceFlowCodes** +* **IdentityServerIdentityResources** + +## Relations to Permission Management + +The optional `Volo.Abp.PermissionManagement.Domain.IdentityServer` integration lets applications grant permissions to a client by using the `GetForClientAsync`, `GetAllForClientAsync` and `SetForClientAsync` extensions on `IPermissionManager` and `IResourcePermissionManager`. Client permission values are stored on the host side. When a client is deleted, the integration removes both its ordinary and resource permission grants through the client's distributed deletion event. + +## Entity Extensions + +The module's [module entity extension](../framework/architecture/modularity/extending/module-entity-extensions.md) API supports the `Client`, `ApiResource` and `IdentityResource` aggregate roots. Configure these extensions before application startup, and create an EF Core migration when an extra property is mapped to a database column. diff --git a/docs/en/release-info/migration-guides/identityserver-to-openiddict.md b/docs/en/release-info/migration-guides/identityserver-to-openiddict.md index 2770722a51..b44f1c4b55 100644 --- a/docs/en/release-info/migration-guides/identityserver-to-openiddict.md +++ b/docs/en/release-info/migration-guides/identityserver-to-openiddict.md @@ -7,12 +7,12 @@ # Migration Identity Server to OpenIddict Guide -This document explains how to migrate to [OpenIddict](https://github.com/openiddict/openiddict-core) from Identity Server. From now on the ABP startup templates uses `OpenIddict` as the auth server by default since version v6.0.0. +This document explains how to migrate an application from IdentityServer4 to [OpenIddict](https://github.com/openiddict/openiddict-core). ABP startup templates have used OpenIddict as the authentication server by default since v6.0.0. -## History -We are not removing Identity Server packages and we will continue to release new versions of Identity Server related NuGet/NPM packages. That means you won't have an issue while upgrading to v6.0 when the stable version releases. We will continue to fix bugs in our packages for a while. ABP 7.0 will be based on .NET 7. If Identity Server continues to work with .NET 7, we will also continue to ship NuGet packages for our IDS integration. +> The checklist below describes the v6.0 transition. For a layer-by-layer migration, use the [IdentityServer to OpenIddict step-by-step guide](openiddict-step-by-step.md) and apply the package version that matches the ABP version of your application. -On the other hand, Identity Server ends support for the open-source Identity Server in the end of 2022. The Identity Server team has decided to move to Duende IDS and ABP will not be migrated to the commercial Duende IDS. You can see the Duende Identity Server announcement from [this link](https://blog.duendesoftware.com/posts/20220111_fair_trade). +## History +IdentityServer4 is archived and no longer maintained by its owners. ABP did not migrate its integration to the commercial Duende IdentityServer product. The ABP IdentityServer integration packages are still shipped for existing applications, while new applications use OpenIddict. See the [Duende IdentityServer announcement](https://blog.duendesoftware.com/posts/20220111_fair_trade) for the background. ## OpenIddict Migration Steps @@ -21,7 +21,7 @@ On the other hand, Identity Server ends support for the open-source Identity Ser * Replace all `IdentityServer` modules with corresponding `OpenIddict` modules. eg `AbpIdentityServerDomainModule` to `AbpOpenIddictDomainModule`, `AbpAccountWebIdentityServerModule` to `AbpAccountWebOpenIddictModule`. * Rename the `ConfigureIdentityServer` to `ConfigureOpenIddict` in your `ProjectNameDbContext` class. * Remove the `UseIdentityServer` and add `UseAbpOpenIddictValidation` after `UseAuthentication`. -* Add follow code to your startup module. +* Add the following code to your startup module. ```cs public override void PreConfigureServices(ServiceConfigurationContext context) @@ -38,7 +38,7 @@ public override void PreConfigureServices(ServiceConfigurationContext context) } ``` -* If your project is not separate AuthServer please also add `ForwardIdentityAuthenticationForBearer` +* If your project does not have a separate AuthServer, also add `ForwardIdentityAuthenticationForBearer`. ```cs private void ConfigureAuthentication(ServiceConfigurationContext context) @@ -48,9 +48,9 @@ private void ConfigureAuthentication(ServiceConfigurationContext context) ``` * Remove the `IdentityServerDataSeedContributor` from the `Domain` project. -* Create a new version of the project, with the same name as your existing project. -* Copy the `ProjectName.Domain\OpenIddict\OpenIddictDataSeedContributor.cs` of new project into your project and update `appsettings.json` base on `ProjectName.DbMigrator\appsettings.json`, Be careful to change the port number. -* Copy the `Index.cshtml.cs` and `Index.cs` of new project to your project if you're using `IClientRepository` in `IndexModel`. +* Generate a temporary project with the same name and architecture as the existing project so you can compare the current OpenIddict setup. +* Copy the generated `ProjectName.Domain\OpenIddict\OpenIddictDataSeedContributor.cs` into your project and update `appsettings.json` based on `ProjectName.DbMigrator\appsettings.json`. Adjust the ports and client URLs for your application. +* Copy the generated `Index.cshtml.cs` and `Index.cshtml` files into your project if your `IndexModel` still uses `IClientRepository`. * Update the scope name from `role` to `roles` in `AddAbpOpenIdConnect` method. * Remove `options.OAuthClientSecret(configuration["AuthServer:SwaggerClientSecret"]);` from `HttpApi.Host` project. * AuthServer no longer requires `JWT bearer authentication`. Please remove it. eg `AddJwtBearer` and `UseJwtTokenMiddleware`. diff --git a/docs/en/release-info/migration-guides/identityserver4-step-by-step.md b/docs/en/release-info/migration-guides/identityserver4-step-by-step.md index 844d5ae071..da617cd237 100644 --- a/docs/en/release-info/migration-guides/identityserver4-step-by-step.md +++ b/docs/en/release-info/migration-guides/identityserver4-step-by-step.md @@ -7,11 +7,13 @@ # Migrating from OpenIddict to IdentityServer4 Step by Step Guide -ABP startup templates use `OpenIddict` OpenID provider from v6.0.0 by default and `IdentityServer` projects are renamed to `AuthServer` in tiered/separated solutions. Since OpenIddict is the default OpenID provider library for ABP templates since v6.0, you may want to keep using [IdentityServer4](https://github.com/IdentityServer/IdentityServer4) library, even it is **archived and no longer maintained by the owners**. ABP doesn't provide support for newer versions of IdentityServer. This guide provides layer-by-layer guidance for migrating your existing [OpenIddict](https://github.com/openiddict/openiddict-core) application to IdentityServer4. +ABP startup templates use the `OpenIddict` OpenID provider from v6.0.0 by default, and `IdentityServer` projects were renamed to `AuthServer` in tiered/separated solutions. This guide provides the v6.0-era, layer-by-layer steps for migrating an existing [OpenIddict](https://github.com/openiddict/openiddict-core) application to IdentityServer4. + +> IdentityServer4 is archived and no longer maintained by its owners. ABP doesn't support newer IdentityServer or Duende IdentityServer versions through this module. Use this guide only when an existing system has a compatibility requirement that prevents migration to OpenIddict; new applications should remain on OpenIddict. ## IdentityServer4 Migration Steps -Use the `abp update` command to update your existing application. See [Upgrading docs](../upgrading.md) for more info. Apply required migrations by following the [Migration Guides](../migration-guides) based on your application version. +These steps target an application that is already on ABP 6.0.x. Keep every `Volo.Abp.*` package on the exact 6.0.x patch version used by the application. Complete any version update separately with the CLI and migration guides for that release line before applying these provider-replacement steps. ### Domain.Shared Layer @@ -138,8 +140,6 @@ typeof(AbpIdentityServerEntityFrameworkCoreModule), ```csharp using Volo.Abp.IdentityServer.EntityFrameworkCore; ... - using Volo.Abp.OpenIddict.EntityFrameworkCore; - ... protected override void OnModelCreating(ModelBuilder builder) { base.OnModelCreating(builder); @@ -150,7 +150,7 @@ typeof(AbpIdentityServerEntityFrameworkCoreModule), builder.ConfigureIdentityServer(); ``` -> Not: You need to create new migration after updating the fluent api. Navigate to *EntityFrameworkCore* folder and add a new migration. Ex, `dotnet ef migrations add Updated_To_IdentityServer ` +> Note: Create a new migration after updating the fluent API. Navigate to the *EntityFrameworkCore* folder and run, for example, `dotnet ef migrations add Updated_To_IdentityServer`. ### MongoDB Layer @@ -186,14 +186,14 @@ typeof(AbpIdentityServerMongoDbModule), ### DbMigrator Project -- In `appsettings.json` **replace OpenIddict section with IdentityServer** since IdentityServerDataSeeder will be using these information for initial data seeding: +- In `appsettings.json` **replace the OpenIddict section with IdentityServer** because IdentityServerDataSeeder uses this configuration for initial data seeding. Rename the `Applications` property to `Clients` and preserve its existing child entries. The minimal valid structure is: ```json - "IdentityServer": { // Rename OpenIddict to IdentityServer - "Clients ": { // Rename Applications to Clients - ... - } + { + "IdentityServer": { + "Clients": {} } + } ``` @@ -223,7 +223,7 @@ typeof(AbpIdentityServerMongoDbModule), ### UI Layer -You can follow the migrations guides from IdentityServer to OpenIddict in **reverse order** to update your UIs. You can also check the source-code for [Index.cshtml.cs](https://github.com/abpframework/abp-samples/blob/master/OpenId2Ids/src/OpenId2Ids.AuthServer/Pages/Index.cshtml) and [Index.cshtml](https://github.com/abpframework/abp-samples/blob/master/OpenId2Ids/src/OpenId2Ids.AuthServer/Pages/Index.cshtml.cs) files for **AuthServer** project. +You can follow the migration guides from IdentityServer to OpenIddict in reverse order to update your UIs. You can also check the sample source for [Index.cshtml.cs](https://github.com/abpframework/abp-samples/blob/master/OpenId2Ids/src/OpenId2Ids.AuthServer/Pages/Index.cshtml.cs) and [Index.cshtml](https://github.com/abpframework/abp-samples/blob/master/OpenId2Ids/src/OpenId2Ids.AuthServer/Pages/Index.cshtml) in the **AuthServer** project. - [Angular UI Migration](openiddict-angular.md) - [MVC/Razor UI Migration](openiddict-mvc.md) diff --git a/docs/en/solution-templates/layered-web-application/deployment/identityserver-deployment.md b/docs/en/solution-templates/layered-web-application/deployment/identityserver-deployment.md index db6975e04f..48f62b9c70 100644 --- a/docs/en/solution-templates/layered-web-application/deployment/identityserver-deployment.md +++ b/docs/en/solution-templates/layered-web-application/deployment/identityserver-deployment.md @@ -7,19 +7,21 @@ # IdentityServer Deployment -IdentityServer configuration may be different based on deployment configurations. Basically, you need update identityserver client related data and update your hosting preferences based on your deployment environment. +> This page applies only to applications that still use the legacy [IdentityServer module](../../../modules/identity-server.md). Current startup templates use OpenIddict; see [Configuring OpenIddict](../../../deployment/configuring-openIddict.md) for current applications. -## Update Cors Origins +IdentityServer configuration changes between deployment environments. Update the IdentityServer client data and the host settings for the deployed URLs before releasing the application. -Cors origins configuration for **gateways**, **microservices** swagger authorization and **Angular/Blazor** (web assembly) must be updated for deployment. This can be found under **App** configuration in *appsettings.json* +## Update CORS Origins + +CORS origin configuration for **gateways**, **microservices** Swagger authorization and **Angular/Blazor WebAssembly** applications must be updated for deployment. It is under the **App** section in *appsettings.json*. ```json "CorsOrigins": "https://*.MyProjectName.com,http://localhost:4200,https://localhost:44307,https://localhost:44325,https://localhost:44353,https://localhost:44367,https://localhost:44388,https://localhost:44381,https://localhost:44361", ``` -## Update Redirect Allowed Urls +## Update Redirect Allowed URLs -This configuration must be done if **Angular** or **Blazor** (web assembly) is used as back-office web application. It is found under **App** configuration in appsettings.json +Update this configuration when an **Angular** or **Blazor WebAssembly** application is used as the back-office application. It is under the **App** section in *appsettings.json*. ```json "RedirectAllowedUrls": "http://localhost:4200,https://localhost:44307" @@ -29,90 +31,50 @@ This configuration must be done if **Angular** or **Blazor** (web assembly) is u `IdentityServerDataSeedContributor` uses **IdentityServer.Clients** section of `appsettings.json` for `ClientId`, `RedirectUri`, `PostLogoutRedirectUri`, `CorsOrigins`. -Update DbMigrator project `appsettings.json` **IdentityServer.Clients.RootUrls** with production values: +Update the DbMigrator project's `appsettings.json` **IdentityServer.Clients.RootUrls** values for production: ![db-migrator-appsettings](../../../images/db-migrator-appsettings.png) Or, manually add production values to `IdentityServerClientRedirectUris`, `IdentityServerClientPostLogoutRedirectUris`, `IdentityServerClientCorsOrigins` tables in your database. -> If you are using microservice template on-the-fly migration and not using dbmigrator project, update **IdentityService** appsettings. +> If you use the microservice template's on-the-fly migration instead of a DbMigrator project, update the **IdentityService** settings. -Eventually, you shouldn't have `localhost` related data. +Remove all `localhost` values from the production client data. ## Update IdentityServer -You need to update token signing certificate and identityserver midware based on your hosting environment. +Update the token-signing certificate and IdentityServer middleware for your hosting environment. ### Signing Certificate -Default development environment uses [developer signing certificates option](https://github.com/abpframework/abp/blob/dev/modules/identityserver/src/Volo.Abp.IdentityServer.Domain/Volo/Abp/IdentityServer/AbpIdentityServerBuilderOptions.cs#L29). Using developer signing certificates may cause *IDX10501: Signature validation failed* error on production. +The default `AbpIdentityServerBuilderOptions.AddDeveloperSigningCredential` value enables a developer signing credential. Don't use a developer signing credential in production; configure a real certificate through `IIdentityServerBuilder` pre-configuration. Otherwise, signing keys can change between deployments and cause errors such as *IDX10501: Signature validation failed*. -Update **IdentityServerModule** with using real certificate on `IIdentityServerBuilder` pre-configuration. +Update **IdentityServerModule** to use a real certificate in `IIdentityServerBuilder` pre-configuration. ![idsrv-certificate](../../../images/idsrv-certificate.png) -You can also [create self-signed certificate](https://docs.abp.io/en/commercial/5.0/startup-templates/microservice/tye-integration#create-developer-certificates) and use it. - -> If you are using self signed certificate, do not forget to set the certificate (.pfx file) as `EmbeddedResource` and set `CopyToOutputDirectory`. File needs to exist physically. +Load the production certificate from your deployment platform's certificate or secret store. Don't embed the production private key in the application assembly or commit it to the source repository. ### Use HTTPS -Update **IdentityServerModule** to [enfcore https](https://docs.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-6.0&tabs=visual-studio). Add `UseHsts` to add hsts headers to clients, add `UseHttpsRedirection` to redirect http requests to https. +Update **IdentityServerModule** to [enforce HTTPS](https://learn.microsoft.com/aspnet/core/security/enforcing-ssl). Add `UseHsts` to send HSTS headers and `UseHttpsRedirection` to redirect HTTP requests to HTTPS. ![use-https](../../../images/use-https.png) ### Behind Load Balancer -To redirect http requests to https from load balancer, update `OnApplicationInitialization` method of the **IdentityServerModule** with the midware below: +When TLS terminates at a reverse proxy or load balancer, use ASP.NET Core Forwarded Headers Middleware so IdentityServer receives the original scheme and host. Follow the [Forwarded Headers](../../../deployment/forwarded-headers.md) guide and the [ASP.NET Core proxy and load balancer guidance](https://learn.microsoft.com/aspnet/core/host-and-deploy/proxy-load-balancer). -```csharp -app.Use((httpContext, next) => -{ - httpContext.Request.Scheme = "https"; - return next(); -}); -``` +Configure the proxy addresses or networks in `ForwardedHeadersOptions.KnownProxies` or `KnownNetworks`, and call `UseForwardedHeaders` before authentication, IdentityServer, HTTPS redirection and HSTS middleware. If you enable `X-Forwarded-Host`, restrict `AllowedHosts` and configure the proxy to overwrite incoming forwarded headers. + +Don't set `HttpContext.Request.Scheme` unconditionally. Don't derive the IdentityServer origin from a custom request header unless the application first verifies that the request came through a trusted proxy; internet clients can forge ordinary request headers. ### Kubernetes -A common scenario is running applications in kubernetes environment. While IdentityServer needs to face internet on https, internal requests can be done using http. +A common scenario is running applications in Kubernetes. While IdentityServer must be exposed to the internet over HTTPS, internal requests can use HTTP. ![idsrv-k8s](../../../images/idsrv-k8s.png) -**HttpApi.Host** and **Web** applications authority should be set to http since token validations will done using http request. - -![api-resource-internal-idsrv](../../../images/api-resource-internal-idsrv.png) - -> You can use different appsettings files like *appsettings.production.json* to override these values or directly override environment values from kubernetes. +Keep the externally advertised IdentityServer authority and origin on the public HTTPS URL. If services use cluster-local routing, configure internal DNS or the ingress so that the public authority resolves through the trusted internal route without changing the issuer or accepting a client-controlled origin. -To isolate internal identityserver requests from external network (internet), append extra header instead of overwriting. -For ingress, you can use `nginx.ingress.kubernetes.io/configuration-snippet`: - -```yaml -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: myidentityserver-ingress - annotations: - nginx.ingress.kubernetes.io/rewrite-target: / - nginx.ingress.kubernetes.io/force-ssl-redirect: "true" - nginx.ingress.kubernetes.io/proxy-buffer-size: "32k" - nginx.ingress.kubernetes.io/proxy-buffers-number: "8" - nginx.ingress.kubernetes.io/configuration-snippet: | - more_set_input_headers "from-ingress: true"; -spec: -``` - -You need to set the IdentityServer origin based on header. Update `OnApplicationInitialization` method of the **IdentityServerModule** with the midware below: - -```csharp -app.Use(async (ctx, next) => -{ - if (ctx.Request.Headers.ContainsKey("from-ingress")) - { - ctx.SetIdentityServerOrigin("https://myidentityserver.com"); - } - - await next(); -}); -``` +> You can use environment-specific files such as *appsettings.Production.json* or environment variables to override these values in Kubernetes.