diff --git a/docs/en/Dependency-Injection.md b/docs/en/Dependency-Injection.md index f94901ad84..f4398488e5 100644 --- a/docs/en/Dependency-Injection.md +++ b/docs/en/Dependency-Injection.md @@ -59,9 +59,9 @@ Some specific types are registered to dependency injection by default. Examples: * MVC controllers (inherit ``Controller`` or ``AbpController``) are registered as transient. * MVC page models (inherit ``PageModel`` or ``AbpPageModel``) are registered as transient. * MVC view components (inherit ``ViewComponent`` or ``AbpViewComponent``) are registered as transient. -* Application services (implement ``IApplicationService`` interface or inherit ``ApplicationService`` class) are registered as transient. -* Repositories (implement ``IRepository`` interface) are registered as transient. -* Domain services (implement ``IDomainService`` interface) are registered as transient. +* Application services (inherit ``ApplicationService`` class or its subclasses) are registered as transient. +* Repositories (implement ``BasicRepositoryBase`` class or its subclasses) are registered as transient. +* Domain services (implement ``IDomainService`` interface or inherit ``DomainService`` class) are registered as transient. Example: diff --git a/docs/en/Modules/Account.md b/docs/en/Modules/Account.md index 94cdb7af95..72f6f55c0e 100644 --- a/docs/en/Modules/Account.md +++ b/docs/en/Modules/Account.md @@ -1,12 +1,54 @@ # Account Module -This module provides necessary UI pages/components to make the user login and register to the application. +Account module implements the basic authentication features like **login**, **register**, **forgot password** and **account management**. -> This document is incomplete. +This module is based on [Microsoft's Identity library](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity) and the [Identity Module](Identity.md). It has [IdentityServer](https://github.com/IdentityServer) integration (based on the [IdentityServer Module](IdentityServer.md)) to provide **single sign-on**, access control and other advanced authentication features. + +## How to Install + +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. + +### The Source Code + +The source code of this module can be accessed [here](https://github.com/abpframework/abp/tree/dev/modules/account). The source code is licensed with [MIT](https://choosealicense.com/licenses/mit/), so you can freely use and customize it. + +## User Interface + +This section introduces the main pages provided by this module. + +### Login + +`/Account/Login` page provides the login functionality. + +![account-module-login](../images/account-module-login.png) + +Social/external login buttons becomes visible if you setup it. See the *Social/External Logins* section below. Register and Forgot password and links redirect to the pages explained in the next sections. + +### Register + +`/Account/Register` page provides the new user registration functionality. + +![account-module-register](../images/account-module-register.png) + +### 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. + +![account-module-forgot-password](../images/account-module-forgot-password.png) + +### Account Management + +`/Account/Manage` page is used to change password and personal information of the user. + +![account-module-manage-account](../images/account-module-manage-account.png) + +## IdentityServer Integration + +[Volo.Abp.Account.Web.IdentityServer](https://www.nuget.org/packages/Volo.Abp.Account.Web.IdentityServer) package provides integration for the [IdentityServer](https://github.com/IdentityServer). This package comes as installed with the [application startup template](../Startup-Templates/Application.md). See the [IdentityServer Module](IdentityServer.md) documentation. ## Social/External Logins -The [Account Module](../Modules/Account.md) 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 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. ### Example: Facebook Authentication @@ -32,7 +74,3 @@ context.Services.AddAuthentication() ```` > It would be a better practice to use the `appsettings.json` or the ASP.NET Core User Secrets system to store your credentials, instead of a hard-coded value like that. Follow the [Microsoft's document](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/social/facebook-logins) to learn the user secrets usage. - -### Other UI Types - -Beginning from the v3.1, the [Angular UI](../UI/Angular/Quick-Start.md) uses authorization code flow (as a best practice) to authenticate the user by redirecting to the MVC UI login page. So, even if you are using the Angular UI, social/external login integration is same as explained above and it will work out of the box. As similar, The [Blazor UI](../UI/Blazor/Overall.md) also uses the MVC UI to logic. \ No newline at end of file diff --git a/docs/en/Modules/Audit-Logging.md b/docs/en/Modules/Audit-Logging.md index 039c61d3a2..30e1ef4e04 100644 --- a/docs/en/Modules/Audit-Logging.md +++ b/docs/en/Modules/Audit-Logging.md @@ -2,6 +2,59 @@ The Audit Logging Module basically implements the `IAuditingStore` to save the audit log objects to a database. -> Audit Logging module is already installed and configured for [the startup templates](../Startup-Templates/Index.md). So, most of the times you don't need to manually add this module to your application. +> This document covers only the audit logging module which persists audit logs to a database. See [the audit logging](../Audit-Logging.md) document for more about the audit logging system. -See [the audit logging system](../Audit-Logging.md) document for more about the audit logging. \ No newline at end of file +## How to Install + +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. + +### The Source Code + +The source code of this module can be accessed [here](https://github.com/abpframework/abp/tree/dev/modules/audit-logging). The source code is licensed with [MIT](https://choosealicense.com/licenses/mit/), so you can freely use and customize it. + +## Internals + +### Domain Layer + +#### Aggregates + +- `AuditLog` (aggregate root): Represents an audit log record in the system. + - `EntityChange` (collection): Changed entities of audit log. + - `AuditLogAction` (collection): Executed actions of audit log. + +#### Repositories + +Following custom repositories are defined for this module: + +- `IAuditLogRepository` + +### Database providers + +#### Common + +##### Table / collection prefix & schema + +All tables/collections use the `Abp` prefix by default. Set static properties on the `AbpAuditLoggingDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). + +##### Connection string + +This module uses `AbpAuditLogging` for the connection string name. If you don't define a connection string with this name, it fallbacks to the `Default` connection string. See the [connection strings](https://docs.abp.io/en/abp/latest/Connection-Strings) documentation for details. + +#### Entity Framework Core + +##### Tables + +- **AbpAuditLogs** + - AbpAuditLogActions + - AbpEntityChanges + - AbpEntityPropertyChanges + +#### MongoDB + +##### Collections + +- **AbpAuditLogs** + +## See Also + +* [Audit logging system](../Audit-Logging.md) \ No newline at end of file diff --git a/docs/en/Modules/Background-Jobs.md b/docs/en/Modules/Background-Jobs.md index 18d7f43486..6cce8a6c95 100644 --- a/docs/en/Modules/Background-Jobs.md +++ b/docs/en/Modules/Background-Jobs.md @@ -1,3 +1,55 @@ # Background Jobs Module -TODO \ No newline at end of file +The Background Jobs module implements the `IBackgroundJobStore` interface and makes possible to use the default background job manager of the ABP Framework. If you don't want to use this module, then you should implement the `IBackgroundJobStore` interface yourself. + +> This document covers only the background jobs module which persists background jobs to a database. See [the background jobs](../Background-Jobs.md) document for more about the background jobs system. + +## How to Install + +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. + +### The Source Code + +The source code of this module can be accessed [here](https://github.com/abpframework/abp/tree/dev/modules/background-jobs). The source code is licensed with [MIT](https://choosealicense.com/licenses/mit/), so you can freely use and customize it. + +## Internals + +### Domain Layer + +#### Aggregates + +- `BackgroundJobRecord` (aggregate root): Represents a background job record. + +#### Repositories + +Following custom repositories are defined for this module: + +- `IBackgroundJobRepository` + +### Database providers + +#### Common + +##### Table / collection prefix & schema + +All tables/collections use the `Abp` prefix by default. Set static properties on the `BackgroundJobsDbProperties` class if you need to change the table prefix or set a schema name (if supported by your database provider). + +##### Connection string + +This module uses `AbpBackgroundJobs` for the connection string name. If you don't define a connection string with this name, it fallbacks to the `Default` connection string. See the [connection strings](https://docs.abp.io/en/abp/latest/Connection-Strings) documentation for details. + +#### Entity Framework Core + +##### Tables + +- **AbpBackgroundJobs** + +#### MongoDB + +##### Collections + +- **AbpBackgroundJobs** + +## See Also + +* [Background job system](../Background-Jobs.md) \ No newline at end of file diff --git a/docs/en/Modules/Feature-Management.md b/docs/en/Modules/Feature-Management.md index 968b742092..9677e2f470 100644 --- a/docs/en/Modules/Feature-Management.md +++ b/docs/en/Modules/Feature-Management.md @@ -1,5 +1,106 @@ # Feature Management Module -> This module implements the `IFeatureStore` to store and manage feature values in a database. See the [Features System document](../Features.md) to understand the features first. +The Feature Management module implements the `IFeatureManagementStore` interface defined by the [Feature System](../Features.md). + +> This document covers only the feature management module which persists feature values to a database. See [the features](../Features.md) document for more about the feature system. + +## How to Install + +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. + +### The Source Code + +The source code of this module can be accessed [here](https://github.com/abpframework/abp/tree/dev/modules/feature-management). The source code is licensed with [MIT](https://choosealicense.com/licenses/mit/), so you can freely use and customize it. + +## User Interface + +### Feature Management Dialog + +Feature management module provides a reusable dialog to manage features related to an object. For example, the [Tenant Management Module](Tenant-Management.md) uses it to manage features of tenants in the Tenant Management page. + +![features-module-opening](../images/features-module-opening.png) + +When you click *Actions* -> *Features* for a tenant, the feature management dialog is opened. An example screenshot from this dialog with two features defined: + +![features-modal](../images/features-modal.png) + +In this dialog, you can enable, disable or set values for the features for a tenant. + +## IFeatureManager + +`IFeatureManager` is the main service provided by this module. It is used to read and change the setting values for the tenants in a multi-tenant application. `IFeatureManager` is typically used by the *Feature Management Dialog*. However, you can inject it if you need to set a feature value. + +> If you just want to read feature values, use the `IFeatureChecker` as explained in the [Features document](../Features.md). + +**Example: Get/set a feature's value for a tenant** + +````csharp +using System; +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.FeatureManagement; + +namespace Demo +{ + public class MyService : ITransientDependency + { + private readonly IFeatureManager _featureManager; + + public MyService(IFeatureManager featureManager) + { + _featureManager = featureManager; + } + + public async Task SetFeatureDemoAsync(Guid tenantId, string value) + { + await _featureManager + .SetForTenantAsync(tenantId, "Feature1", value); + + var currentValue = await _featureManager + .GetOrNullForTenantAsync("Feature1", tenantId); + } + } +} +```` + +## Feature Management Providers + +Features Management Module is extensible, just like the [features system](../Features.md). You can extend it by defining feature management providers. There are 3 pre-built feature management providers registered it the following order: + +* `DefaultValueFeatureManagementProvider`: Gets the value from the default value of the feature definition. It can not set the default value since default values are hard-coded on the feature definition. +* `EditionFeatureManagementProvider`: Gets or sets the feature values for an edition. Edition is a group of features assigned to tenants. Edition system has not implemented by the Tenant Management module. You can implement it yourself or purchase the ABP Commercial [SaaS Module](https://commercial.abp.io/modules/Volo.Saas) which implements it and also provides more SaaS features, like subscription and payment. +* `TenantFeatureManagementProvider`: Gets or sets the features values for tenants. + +`IFeatureManager` uses these providers on get/set methods. Typically, every feature management provider defines extension methods on the `IFeatureManager` service (like `SetForTenantAsync` defined by the tenant feature management provider). + +If you want to create your own provider, implement the `IFeatureManagementProvider` interface or inherit from the `FeatureManagementProvider` base class: + +````csharp +public class CustomFeatureProvider : FeatureManagementProvider +{ + public override string Name => "Custom"; + + public CustomFeatureProvider(IFeatureManagementStore store) + : base(store) + { + } +} +```` + +`FeatureManagementProvider` base class makes the default implementation (using the `IFeatureManagementStore`) for you. You can override base methods as you need. Every provider must have a unique name, which is `Custom` in this example (keep it short since it is saved to database for each feature value record). + +Once you create your provider class, you should register it using the `FeatureManagementOptions` [options class](../Options.md): + +````csharp +Configure(options => +{ + options.Providers.Add(); +}); +```` + +The order of the providers are important. Providers are executed in the reverse order. That means the `CustomFeatureProvider` is executed first for this example. You can insert your provider in any order in the `Providers` list. + +## See Also + +* [Features](../Features.md) -TODO \ No newline at end of file diff --git a/docs/en/Modules/Identity.md b/docs/en/Modules/Identity.md index 8cd7bf3966..c06f649723 100644 --- a/docs/en/Modules/Identity.md +++ b/docs/en/Modules/Identity.md @@ -1,38 +1,63 @@ # Identity Management Module -Identity module is used to manage organization units, roles, users and their permissions, based on the Microsoft Identity library. +Identity module is used to manage roles, users and their permissions, based on the [Microsoft Identity library](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity). -> **See [the source code](https://github.com/abpframework/abp/tree/dev/modules/identity). Documentation will come soon...** +## How to Install +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. -## Identity Security Log +### The Source Code -The security log can record some important operations or changes about your account. You can save the security log if needed. +The source code of this module can be accessed [here](https://github.com/abpframework/abp/tree/dev/modules/identity). The source code is licensed with [MIT](https://choosealicense.com/licenses/mit/), so you can freely use and customize it. -You can inject and use `IdentitySecurityLogManager` or `ISecurityLogManager` to write security logs. It will create a log object by default and fill in some common values, such as `CreationTime`, `ClientIpAddress`, `BrowserInfo`, `current user/tenant`, etc. Of course, you can override them. +## User Interface -```cs -await IdentitySecurityLogManager.SaveAsync(new IdentitySecurityLogContext() -{ - Identity = "IdentityServer"; - Action = "ChangePassword"; -}); -``` +This module provides [Blazor](../UI/Blazor/Overall.md), [Angular](../UI/Angular/Quick-Start.md) and [MVC / Razor Pages](../UI/AspNetCore/Overall.md) UI options. -Configure `AbpSecurityLogOptions` to provide the application name for the log or disable this feature. **Enabled** by default. +### Menu Items -```cs -Configure(options => -{ - options.ApplicationName = "AbpSecurityTest"; -}); -``` +This module adds an *Identity management* menu item under the *Administration* menu: + +![identity-module-menu](../images/identity-module-menu.png) + +The menu items and the related pages are authorized. That means the current user must have the related permissions to make them visible. The `admin` role (and the users with this role - like the `admin` user) already has these permissions. If you want to enable permissions for other roles/users, open the *Permissions* dialog on the *Roles* or *Users* page and check the permissions as shown below: + +![identity-module-permissions](../images/identity-module-permissions.png) + +See the [Authorization document](../Authorization.md) to understand the permission system. + +### Pages + +This section introduces the main pages provided by this module. + +#### Users + +This page is used to see the list of users. You can create/edit and delete users, assign users to roles. + +![identity-module-users](../images/identity-module-users.png) + +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*). + +#### 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: + +* `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)). +* `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 + +This section covers some other features provided by this module which don't have the UI pages. -## Organization Unit Management +### Organization Units -Organization units (OU) is a part of **Identity Module** and can be used to **hierarchically group users and entities**. +Organization Units (OU) can be used to **hierarchically group users and entities**. -### OrganizationUnit Entity +#### OrganizationUnit Entity An OU is represented by the **OrganizationUnit** entity. The fundamental properties of this entity are: @@ -41,8 +66,6 @@ An OU is represented by the **OrganizationUnit** entity. The fundamental propert - **Code**: A hierarchical string code that is unique for a tenant. - **DisplayName**: Shown name of the OU. -The OrganizationUnit entity's primary key (Id) is a **Guid** type and it derives from the [**FullAuditedAggregateRoot**](../Entities.md) class. - #### Organization Tree Since an OU can have a parent, all OUs of a tenant are in a **tree** structure. There are some rules for this tree; @@ -52,26 +75,248 @@ Since an OU can have a parent, all OUs of a tenant are in a **tree** structure. #### OU Code -OU code is automatically generated and maintained by the OrganizationUnit Manager. It's a string that looks something like this: +OU code is automatically generated and maintained by the `OrganizationUnitManager` service. It's a string that looks something like this: "**00001.00042.00005**" -This code can be used to easily query the database for all the children of an OU (recursively). There are some rules for this code: +This code can be used to easily query the database for all the children of an OU (recursively). There are some rules for this code (automatically applied when you use `OrganizationUnitManager`): -- It must be **unique** for a [tenant](../Multi-Tenancy.md). +- It is **unique** for a [tenant](../Multi-Tenancy.md). - All the children of the same OU have codes that **start with the parent OU's code**. - It's **fixed length** and based on the level of the OU in the tree, as shown in the sample. -- While the OU code is unique, it can be **changeable** if you move an OU. -- You must reference an OU by Id, not Code. +- While the OU code is unique, it can be **changed** if you move the related OU. + +Notice that you must reference an OU by Id, not Code, because the Code can be changed later. -### OrganizationUnit Manager +#### OrganizationUnit Manager -The **OrganizationUnitManager** class can be [injected](../Dependency-Injection.md) and used to manage OUs. Common use cases are: +The `OrganizationUnitManager` class can be [injected](../Dependency-Injection.md) and used to manage OUs. Common use cases are: - Create, Update or Delete an OU - Move an OU in the OU tree. - Getting information about the OU tree and its items. -#### Multi-Tenancy +### 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. + +You can inject and use `IdentitySecurityLogManager` or `ISecurityLogManager` to write security logs. It will create a log object by default and fill in some common values, such as `CreationTime`, `ClientIpAddress`, `BrowserInfo`, `current user/tenant`, etc. Of course, you can override them. + +```cs +await IdentitySecurityLogManager.SaveAsync(new IdentitySecurityLogContext() +{ + Identity = "IdentityServer"; + Action = "ChangePassword"; +}); +``` + +Configure `AbpSecurityLogOptions` to provide the application name (in case of you have multiple applications and want to distinguish the applications in the logs) for the log or disable this feature. + +```cs +Configure(options => +{ + options.ApplicationName = "AbpSecurityTest"; +}); +``` + +## Options + +`IdentityOptions` is the standard [options class](../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](../Module-Development-Basics.md) class. + +**Example: Set minimum required length of passwords** + +````csharp +Configure(options => +{ + options.Password.RequiredLength = 5; +}); +```` + +ABP takes these options one step further and allows you to change them on runtime by using the [setting system](../Settings.md). You can [inject](../Dependency-Injection.md) `ISettingManager` and use one of the `Set...` methods to change the option values for a user, a tenant or globally for all users. + +**Example: Change minimum required length of passwords for the current tenant** + +````csharp +public class MyService : ITransientDependency +{ + private readonly ISettingManager _settingManager; + + public MyService(ISettingManager settingManager) + { + _settingManager = settingManager; + } + + public async Task ChangeMinPasswordLength(int minLength) + { + await _settingManager.SetForCurrentTenantAsync( + IdentitySettingNames.Password.RequiredLength, + minLength.ToString() + ); + } +} +```` + +`IdentitySettingNames` class (in the `Volo.Abp.Identity.Settings` namespace) defines constants for the setting names. + +## Distributed Events + +This module defines the following ETOs (Event Transfer Objects) to allow you to subscribe to changes on the entities of the module; + +* `UserEto` is published on changes done on an `IdentityUser` entity. +* `IdentityRoleEto` is published on changes done on an `IdentityRole` entity. +* `IdentityClaimTypeEto` is published on changes done on an `IdentityClaimType` entity. +* `OrganizationUnitEto` is published on changes done on an `OrganizationUnit` entity. + +**Example: Get notified when a new user has been created** + +````csharp +public class MyHandler : + IDistributedEventHandler>, + ITransientDependency +{ + public async Task HandleEventAsync(EntityCreatedEto eventData) + { + UserEto user = eventData.Entity; + // TODO: ... + } +} +```` + +`UserEto` and `IdentityRoleEto` are configured to automatically publish the events. You should configure yourself for the others. See the [Distributed Event Bus document](../Distributed-Event-Bus.md) to learn details of the pre-defined events. + +> Subscribing to the distributed events is especially useful for distributed scenarios (like microservice architecture). If you are building a monolithic application, or listening events in the same process that runs the Identity Module, then subscribing to the [local events](../Local-Event-Bus.md) can be more efficient and easier. + +## Internals + +This section covers some internal details of the module that you don't need much, but may need to use in some cases. + +### Domain layer + +#### Aggregates + +##### User + +A user is generally a person logins to and uses the application. + +* `IdentityUser` (aggregate root): Represents a user in the system. + * `IdentityUserRole` (collection): Roles to the user. + * `IdentityUserClaim` (collection): Custom claims of the user. + * `IdentityUserLogin` (collection): External logins of the user. + * `IdentityUserToken` (collection): Tokens of the user (used by the Microsoft Identity services). + +##### Role + +A role is typically a group of permissions to assign to the users. + +* `IdentityRole` (aggregate root): Represents a role in the system. + * `IdentityRoleClaim` (collection): Custom claims of the role. + +##### Claim Type + +A claim type is a definition of a custom claim that can be assigned to other entities (like roles and users) in the system. + +* `IdentityClaimType` (aggregate root): Represents a claim type definition. It contains some properties (e.g. Required, Regex, Description, ValueType) to define the claim type and the validation rules. + +##### Identity Security Log + +A `IdentitySecurityLog` object represents an authentication related operation (like *login*) in the system. + +* `IdentitySecurityLog` (aggregate root): Represents a security log in the system. + +##### OrganizationUnit + +An Organization unit is a entity in a hierarchical structure. + +* ```OrganizationUnit``` (aggregate root): Represents an organization unit in the system. + * ```Roles``` (collection): Roles of the organization unit. + +#### Repositories + +Following custom repositories are defined for this module: + +* `IIdentityUserRepository` +* `IIdentityRoleRepository` +* `IIdentityClaimTypeRepository` +* ```IIdentitySecurityLogRepository``` +* ```IOrganizationUnitRepository``` + +#### Domain services + +##### User manager + +`IdentityUserManager` is used to manage users, their roles, claims, passwords, emails, etc. It is derived from Microsoft Identity's `UserManager` class where `T` is `IdentityUser`. + +##### Role manager + +`IdentityRoleManager` is used to manage roles and their claims. It is derived from Microsoft Identity's `RoleManager` class where `T` is `IdentityRole`. + +##### Claim type manager + +`IdenityClaimTypeManager` is used to perform some operations for the `IdentityClaimType` aggregate root. + +##### Organization unit manager + +```OrganizationUnitManager``` is used to perform some operations for the ```OrganizationUnit``` aggregate root. + +##### Security log manager + +```IdentitySecurityLogManager``` is used to save security logs. + +### Application Layer + +#### Application Services + +* `IdentityUserAppService` (implements `IIdentityUserAppService`): Implements the use cases of the user management UI. +* `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 framework. +* `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. + +### Database Providers + +This module provides [Entity Framework Core](../Entity-Framework-Core.md) and [MongoDB](../MongoDB.md) options for the database. + +#### Entity Framework Core + +[Volo.Abp.Identity.EntityFrameworkCore](https://www.nuget.org/packages/Volo.Abp.Identity.EntityFrameworkCore) NuGet package implements the EF Core integration. + +##### Database Tables + +* **AbpRoles** + * AbpRoleClaims +* **AbpUsers** + * AbpUserClaims + * AbpUserLogins + * AbpUserRoles + * AbpUserTokens +* **AbpClaimTypes** +* **AbpOrganizationUnits** + * AbpOrganizationUnitRoles + * AbpUserOrganizationUnits +* **AbpSecurityLogs** + +#### MongoDB + +[Volo.Abp.Identity.MongoDB](https://www.nuget.org/packages/Volo.Abp.Identity.MongoDB) NuGet package implements the MongoDB integration. + +##### Database Collections + +* **AbpRoles** +* **AbpUsers** +* **AbpClaimTypes** +* **AbpOrganizationUnits** +* **AbpSecurityLogs** + +#### Common Database Properties + +You can set the following properties of the `AbpIdentityDbProperties` class to change the database options: + +* `DbTablePrefix` (`Abp` by default) is the prefix for table/collection names. +* `DbSchema` (`null` by default) is the database schema. +* `ConnectionStringName` (`AbpIdentity` by default) is the [connection string](../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`). -The `OrganizationUnitManager` is designed to work for a **single tenant** at a time. It works for the **current tenant** by default. \ No newline at end of file diff --git a/docs/en/Modules/Permission-Management.md b/docs/en/Modules/Permission-Management.md index ad48b60171..ba4b34d8ed 100644 --- a/docs/en/Modules/Permission-Management.md +++ b/docs/en/Modules/Permission-Management.md @@ -1,5 +1,109 @@ # Permission Management Module -This module implements the `IPermissionStore` to store and manage feature values in a database. See the [Authorization document](../Authorization.md) to understand the authorization and permission systems first. +This module implements the `IPermissionStore` to store and manage permissions values in a database. -TODO \ No newline at end of file +> This document covers only the permission management module which persists permission values to a database. See the [Authorization document](../Authorization.md) to understand the authorization and permission systems. + +## How to Install + +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. + +### The Source Code + +The source code of this module can be accessed [here](https://github.com/abpframework/abp/tree/dev/modules/permission-management). The source code is licensed with [MIT](https://choosealicense.com/licenses/mit/), so you can freely use and customize it. + +## User Interface + +### Permission Management Dialog + +Permission management module provides a reusable dialog to manage permissions related to an object. For example, the [Identity Module](Identity.md) uses it to manage permissions of users and roles. The following image shows Identity Module's Role Management page: + +![permissions-module-open-dialog](../images/permissions-module-open-dialog.png) + +When you click *Actions* -> *Permissions* for a role, the permission management dialog is opened. An example screenshot from this dialog: + +![permissions-module-dialog](../images/permissions-module-dialog.png) + +In this dialog, you can grant permissions for the selected role. The tabs in the left side represents main permission groups and the right side contains the permissions defined in the selected group. + +## IPermissionManager + +`IPermissionManager` is the main service provided by this module. It is used to read and change the permission values. `IPermissionManager` is typically used by the *Feature Management Dialog*. However, you can inject it if you need to set a permission value. + +> If you just want to read/check permission values for the current user, use the `IAuthorizationService` or the `[Authorize]` attribute as explained in the [Authorization document](../Authorization.md). + +**Example: Grant permissions to roles and users using the `IPermissionManager` service** + +````csharp +public class MyService : ITransientDependency +{ + private readonly IPermissionManager _permissionManager; + + public MyService(IPermissionManager permissionManager) + { + _permissionManager = permissionManager; + } + + public async Task GrantRolePermissionDemoAsync( + string roleName, string permission) + { + await _permissionManager + .SetForRoleAsync(roleName, permission, true); + } + + public async Task GrantUserPermissionDemoAsync( + Guid userId, string roleName, string permission) + { + await _permissionManager + .SetForUserAsync(userId, permission, true); + } +} +```` + +## Permission Management Providers + +Permission Management Module is extensible, just like the [permission system](../Authorization.md). You can extend it by defining permission management providers. + +[Identity Module](Identity.md) defines the following permission management providers: + +* `UserPermissionManagementProvider`: Manages user-based permissions. +* `RolePermissionManagementProvider`: Manages role-based permissions. + +`IPermissionManager` uses these providers when you get/set permissions. You can define your own provider by implementing the `IPermissionManagementProvider` or inheriting from the `PermissionManagementProvider` base class. + +**Example:** + +````csharp +public class CustomPermissionManagementProvider : PermissionManagementProvider +{ + public override string Name => "Custom"; + + public CustomPermissionManagementProvider( + IPermissionGrantRepository permissionGrantRepository, + IGuidGenerator guidGenerator, + ICurrentTenant currentTenant) + : base( + permissionGrantRepository, + guidGenerator, + currentTenant) + { + } +} +```` + +`PermissionManagementProvider` base class makes the default implementation (using the `IPermissionGrantRepository`) for you. You can override base methods as you need. Every provider must have a unique name, which is `Custom` in this example (keep it short since it is saved to database for each feature value record). + +Once you create your provider class, you should register it using the `FeatureManagementOptions` [options class](../Options.md): + +````csharp +Configure(options => +{ + options.ManagementProviders.Add(); +}); +```` + +The order of the providers are important. Providers are executed in the reverse order. That means the `CustomPermissionManagementProvider` is executed first for this example. You can insert your provider in any order in the `Providers` list. + +## See Also + +* [Authorization](../Authorization.md) \ No newline at end of file diff --git a/docs/en/Modules/Setting-Management.md b/docs/en/Modules/Setting-Management.md index dff8da3f8e..9104daf8a6 100644 --- a/docs/en/Modules/Setting-Management.md +++ b/docs/en/Modules/Setting-Management.md @@ -83,4 +83,35 @@ Setting Management module is extensible, just like the [setting system](../Setti * `TenantSettingManagementProvider`: Gets or sets the setting value for a tenant. * `UserSettingManagementProvider`: Gets the setting value for a user. -`ISettingManager` uses the setting management providers on get/set methods. Typically, every setting management provider defines extension methods on the `ISettingManagement` service (like `SetForUserAsync` defined by the user setting management provider). \ No newline at end of file +`ISettingManager` uses the setting management providers on get/set methods. Typically, every setting management provider defines extension methods on the `ISettingManagement` service (like `SetForUserAsync` defined by the user setting management provider). + +If you want to create your own provider, implement the `ISettingManagementProvider` interface or inherit from the `SettingManagementProvider` base class: + +````csharp +public class CustomSettingProvider : SettingManagementProvider +{ + public override string Name => "Custom"; + + public CustomSettingProvider(ISettingManagementStore store) + : base(store) + { + } +} +```` + +`SettingManagementProvider` base class makes the default implementation (using the `ISettingManagementStore`) for you. You can override base methods as you need. Every provider must have a unique name, which is `Custom` in this example (keep it short since it is saved to database for each feature value record). + +Once you create your provider class, you should register it using the `SettingManagementOptions` [options class](../Options.md): + +````csharp +Configure(options => +{ + options.Providers.Add(); +}); +```` + +The order of the providers are important. Providers are executed in the reverse order. That means the `CustomSettingProvider` is executed first for this example. You can insert your provider in any order in the `Providers` list. + +## See Also + +* [Settings](../Settings.md) \ No newline at end of file diff --git a/docs/en/Modules/Tenant-Management.md b/docs/en/Modules/Tenant-Management.md index dca6ea3d1e..e12b6fc7a6 100644 --- a/docs/en/Modules/Tenant-Management.md +++ b/docs/en/Modules/Tenant-Management.md @@ -12,7 +12,7 @@ The [SaaS Module](https://commercial.abp.io/modules/Volo.Saas) is an alternative ## How to Install -This module comes as pre-installed (as [NuGet/NPM packages](NuGet/NPM packages)) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. +This module comes as pre-installed (as NuGet/NPM packages) when you [create a new solution](https://abp.io/get-started) with the ABP Framework. 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.md) command) to develop your custom module. ### The Source Code diff --git a/docs/en/UI/AspNetCore/Basic-Theme.md b/docs/en/UI/AspNetCore/Basic-Theme.md index 67977ffd4e..3c63eb6b6a 100644 --- a/docs/en/UI/AspNetCore/Basic-Theme.md +++ b/docs/en/UI/AspNetCore/Basic-Theme.md @@ -83,8 +83,8 @@ See the [User Interface Customization Guide](Customization-User-Interface.md) to ### Copy & Customize -You can download the [source code](https://github.com/abpframework/abp/tree/dev/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic) of the Basic Theme, copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements. +You can download the [source code](https://github.com/abpframework/abp/tree/rel-4.3/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic) of the Basic Theme, copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements. ## See Also -* [Theming](Theming.md) \ No newline at end of file +* [Theming](Theming.md) diff --git a/docs/en/UI/Blazor/Basic-Theme.md b/docs/en/UI/Blazor/Basic-Theme.md index 926d15cf11..d2947ecb17 100644 --- a/docs/en/UI/Blazor/Basic-Theme.md +++ b/docs/en/UI/Blazor/Basic-Theme.md @@ -50,8 +50,8 @@ See the [Customization / Overriding Components](Customization-Overriding-Compone ### Copy & Customize -You can download the [source code](https://github.com/abpframework/abp/tree/dev/framework/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme) of the Basic Theme, copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements. +You can download the [source code](https://github.com/abpframework/abp/tree/rel-4.3/framework/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme) of the Basic Theme, copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements. ## See Also -* [Theming](Theming.md) \ No newline at end of file +* [Theming](Theming.md) diff --git a/docs/en/images/account-module-forgot-password.png b/docs/en/images/account-module-forgot-password.png new file mode 100644 index 0000000000..92fce47a22 Binary files /dev/null and b/docs/en/images/account-module-forgot-password.png differ diff --git a/docs/en/images/account-module-login.png b/docs/en/images/account-module-login.png new file mode 100644 index 0000000000..abde22db57 Binary files /dev/null and b/docs/en/images/account-module-login.png differ diff --git a/docs/en/images/account-module-manage-account.png b/docs/en/images/account-module-manage-account.png new file mode 100644 index 0000000000..92a5f34d72 Binary files /dev/null and b/docs/en/images/account-module-manage-account.png differ diff --git a/docs/en/images/account-module-register.png b/docs/en/images/account-module-register.png new file mode 100644 index 0000000000..f2b9c0587a Binary files /dev/null and b/docs/en/images/account-module-register.png differ diff --git a/docs/en/images/features-module-opening.png b/docs/en/images/features-module-opening.png new file mode 100644 index 0000000000..bd99604cd7 Binary files /dev/null and b/docs/en/images/features-module-opening.png differ diff --git a/docs/en/images/identity-module-menu.png b/docs/en/images/identity-module-menu.png new file mode 100644 index 0000000000..8083e2f722 Binary files /dev/null and b/docs/en/images/identity-module-menu.png differ diff --git a/docs/en/images/identity-module-permissions.png b/docs/en/images/identity-module-permissions.png new file mode 100644 index 0000000000..24ef15e3b4 Binary files /dev/null and b/docs/en/images/identity-module-permissions.png differ diff --git a/docs/en/images/identity-module-roles.png b/docs/en/images/identity-module-roles.png new file mode 100644 index 0000000000..c8e2c9cde1 Binary files /dev/null and b/docs/en/images/identity-module-roles.png differ diff --git a/docs/en/images/identity-module-users.png b/docs/en/images/identity-module-users.png new file mode 100644 index 0000000000..7de6da77d4 Binary files /dev/null and b/docs/en/images/identity-module-users.png differ diff --git a/docs/en/images/permissions-module-dialog.png b/docs/en/images/permissions-module-dialog.png new file mode 100644 index 0000000000..6b190484a2 Binary files /dev/null and b/docs/en/images/permissions-module-dialog.png differ diff --git a/docs/en/images/permissions-module-open-dialog.png b/docs/en/images/permissions-module-open-dialog.png new file mode 100644 index 0000000000..46631fe126 Binary files /dev/null and b/docs/en/images/permissions-module-open-dialog.png differ