diff --git a/docs/en/modules/account.md b/docs/en/modules/account.md index 844e00e06f..2148ca5d42 100644 --- a/docs/en/modules/account.md +++ b/docs/en/modules/account.md @@ -37,6 +37,8 @@ Social/external login buttons becomes visible if you setup it. See the *Social/E ![account-module-register](../images/account-module-register.png) +New users receive every Identity role marked as `Default`. + ### Forgot Password & Reset Password `/Account/ForgotPassword` page provides a way of sending password reset link to user's email address. The user then clicks to the link and determines a new password. @@ -51,6 +53,34 @@ Social/external login buttons becomes visible if you setup it. See the *Social/E ![account-module-manage-account](../images/account-module-manage-account.png) +`IdentitySettingNames.User.IsUserNameUpdateEnabled` and `IdentitySettingNames.User.IsEmailUpdateEnabled` control whether the profile application service accepts changes to those fields. Both settings are `true` by default. External users can't change a local password; the built-in MVC profile page omits the password group for them and the application service rejects a password change. + +### Login and Registration Settings + +The Account module defines two client-visible settings. Both are `true` by default: + +* `AccountSettingNames.IsSelfRegistrationEnabled` controls self-registration. It is enforced by `IAccountAppService.RegisterAsync` as well as the built-in registration pages. +* `AccountSettingNames.EnableLocalLogin` controls the local username/password login UI and handlers in the MVC Account pages, the OpenIddict and IdentityServer integrations, and the Angular Account layout. In Angular, `AuthWrapperService` reads the setting; the Basic Theme's `AuthWrapperComponent` shows the account content when it is enabled and a no-login-schemes warning when it is disabled. + +These settings are independent. Disabling local login doesn't disable the registration application service. Set `IsSelfRegistrationEnabled` to `false` as well when users must not create local accounts. Change the values with `ISettingManager` like other [settings](../framework/infrastructure/settings.md). Global or tenant values are normally appropriate because the login and registration requests run before a user is authenticated. + +### Extending the MVC Profile Page + +The MVC `/Account/Manage` page is built from the contributors in `ProfileManagementPageOptions.Contributors`. Implement `IProfileManagementPageContributor` to add a group backed by a view component, then register it from your module: + +```csharp +Configure(options => +{ + options.Contributors.Add(new MyProfileManagementPageContributor()); +}); +``` + +Each contributor receives a `ProfileManagementPageCreationContext` and appends `ProfileManagementPageGroup` instances to its `Groups` collection. Contributors run in registration order on both GET and POST requests, and can resolve services through `context.ServiceProvider` when visibility depends on the current user or another runtime condition. + +### Angular UI Extensibility + +The Angular `createRoutes` function accepts three module-specific options: `redirectUrl`, `isPersonalSettingsChangedConfirmationActive` and `editFormPropContributors`. The form contributor key is `eAccountComponents.PersonalSettings`. The login, register, forgot-password, reset-password and manage-profile routes are also registered with the corresponding `eAccountComponents` keys for [component replacement](../framework/ui/angular/component-replacement.md). See [Dynamic Form Extensions](../framework/ui/angular/dynamic-form-extensions.md) for the contributor pattern. + ## OpenIddict Integration [Volo.Abp.Account.Web.OpenIddict](https://www.nuget.org/packages/Volo.Abp.Account.Web.OpenIddict) package provides integration for the [OpenIddict](https://github.com/openiddict). This package comes as installed with the [application startup template](../solution-templates/layered-web-application). See the [OpenIddict Module](./openiddict.md) documentation. @@ -63,6 +93,15 @@ Social/external login buttons becomes visible if you setup it. See the *Social/E The Account Module has already configured to handle social or external logins out of the box. You can follow the ASP.NET Core documentation to add a social/external login provider to your application. +The MVC login and registration pages also recognize a Windows authentication scheme. `AbpAccountOptions.WindowsAuthenticationSchemeName` identifies that scheme and defaults to `"Windows"`. Set it when the registered scheme uses another name: + +```csharp +Configure(options => +{ + options.WindowsAuthenticationSchemeName = "Negotiate"; +}); +``` + ### Example: Facebook Authentication Follow the [ASP.NET Core Facebook integration document](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/social/facebook-logins) to support the Facebook login for your application. diff --git a/docs/en/modules/identity.md b/docs/en/modules/identity.md index d92f4b7b8e..6b66763cf1 100644 --- a/docs/en/modules/identity.md +++ b/docs/en/modules/identity.md @@ -45,15 +45,20 @@ This page is used to see the list of users. You can create/edit and delete users A user can have zero or more roles. Users inherit permissions from their roles. In addition, you can assign permissions directly to the users (by clicking the *Actions* button, then selecting the *Permissions*). +Role changes submitted through the general create or update input are applied only when the current user has the `AbpIdentity.Users.Update.ManageRoles` permission; otherwise, the submitted `RoleNames` value is ignored. Role changes performed by the administration workflow are filtered to prevent privilege escalation: except for an operator in the built-in `admin` role, an operator can only add or remove roles that they already have, and roles outside that set are kept unchanged. An operator in the `admin` role can assign any role. + +When users edit their own record through the Identity administration service, a submitted `IsActive` change is ignored, and the built-in MVC, Blazor and MudBlazor user interfaces hide that field. The current user also can't delete their own account from this service. + #### Roles Roles are used to group permissions assign them to users. ![identity-module-roles](../images/identity-module-roles.png) -Beside the role name, there are two properties of a role: +Beside the role name, there are three properties of a role: * `Default`: If a role is marked as "default", then that role is assigned to new users by default when they register to the application themselves (using the [Account Module](account.md)). +* `Static`: A static role can't be renamed or deleted. Seeded roles, such as the built-in `admin` role, can use this flag to protect their identity in the application. * `Public`: A public role of a user can be seen by other users in the application. This feature has no usage in the Identity module, but provided as a feature that you may want to use in your own application. ## Other Features @@ -79,6 +84,7 @@ Since an OU can have a parent, all OUs of a tenant are in a **tree** structure. - There can be more than one root (where the `ParentId` is `null`). - There is a limit for the first-level children count of an OU (because of the fixed OU Code unit length explained below). +- A parent and all of its children must belong to the same tenant. Creating or moving an OU under an OU from another tenant is rejected. #### OU Code @@ -103,6 +109,10 @@ The `OrganizationUnitManager` class can be [injected](../framework/fundamentals/ - Move an OU in the OU tree. - Getting information about the OU tree and its items. +Roles can be assigned to an OU. A user gets both directly assigned roles and the roles of every OU they belong to. Adding or removing an OU role or membership invalidates the affected users' dynamic claims cache, so the effective role claims are rebuilt on the next refresh. + +`IdentitySettingNames.OrganizationUnit.MaxUserMembershipCount` limits how many OUs a user can belong to. Its default value is `int.MaxValue`. `IdentityUserManager.AddToOrganizationUnitAsync` and `SetOrganizationUnitsAsync` reject changes that exceed the configured value. + ### Identity Security Log The security log system records some important operations or changes about your account (like *login* and *change password*). You can also save the security log if needed. @@ -217,6 +227,38 @@ public class MyService : ITransientDependency `IdentitySettingNames` class (in the `Volo.Abp.Identity.Settings` namespace) defines constants for the setting names. +### ASP.NET Core Authentication Registration + +`AbpIdentityAspNetCoreModule` registers the ASP.NET Core Identity application and external cookie schemes by default. If the host configures authentication and cookies itself, disable this registration in `PreConfigureServices` and add the required schemes in the host: + +```csharp +PreConfigure(options => +{ + options.ConfigureAuthentication = false; +}); +``` + +Disabling this option only skips `AddAuthentication` and `AddIdentityCookies`; the Identity managers, stores, token providers and security-stamp validator remain registered. + +### Dynamic Claims Cache + +The Identity module caches the dynamic claims it builds for a user for one hour by default. Configure `IdentityDynamicClaimsPrincipalContributorCacheOptions.CacheAbsoluteExpiration` to change the absolute lifetime: + +```csharp +Configure(options => +{ + options.CacheAbsoluteExpiration = TimeSpan.FromMinutes(30); +}); +``` + +Identity operations that change a user's claims or effective roles clear the affected cache entries. The expiration remains the upper bound for entries that aren't explicitly invalidated. See the [Dynamic Claims](../framework/fundamentals/dynamic-claims.md) document for the end-to-end refresh pipeline. + +## Angular UI Extensibility + +The Angular `createRoutes` function accepts `entityActionContributors`, `toolbarActionContributors`, `entityPropContributors`, `createFormPropContributors` and `editFormPropContributors` for both `eIdentityComponents.Roles` and `eIdentityComponents.Users`. + +The [entity actions](../framework/ui/angular/entity-action-extensions.md), [page toolbars](../framework/ui/angular/page-toolbar-extensions.md), [table columns](../framework/ui/angular/data-table-column-extensions.md) and [dynamic forms](../framework/ui/angular/dynamic-form-extensions.md) guides use the Identity module to demonstrate these `createRoutes` contributors. To replace the complete roles or users component, register the corresponding key with `ReplaceableComponentsService` as described in the [component replacement](../framework/ui/angular/component-replacement.md) guide. + ## Distributed Events This module defines the following ETOs (Event Transfer Objects) to allow you to subscribe to changes on the entities of the module; @@ -327,13 +369,10 @@ Following custom repositories are defined for this module: * `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. +* `IdentityRoleAppService` (implements `IIdentityRoleAppService`): Implements the use cases of the role management UI. * `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. + +Profile editing and password changes are provided by the Account module's `ProfileAppService`. Claim type, Identity settings, security log and organization unit administration application services are not part of the open-source Identity module. ### Database Providers @@ -379,4 +418,3 @@ You can set the following properties of the `AbpIdentityDbProperties` class to c * `ConnectionStringName` (`AbpIdentity` by default) is the [connection string](../framework/fundamentals/connection-strings.md) name for this module. These are static properties. If you want to set, do it in the beginning of your application (typically, in `Program.cs`). -