Documentation for Resource Based Authorization #24679
Conversation
Replaces all references to 'authorization.md' with 'authorization/index.md' across documentation files to reflect the new file structure. This ensures all internal links to the authorization documentation remain valid after the file was moved and renamed.
EngincanV
changed the title
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the resource-based authorization feature in ABP Framework, addressing issue #24297. The changes restructure the authorization documentation and add detailed guides for implementing fine-grained, per-resource access control.
Changes:
- Adds new resource-based authorization documentation explaining how to define, check, and manage permissions for specific resource instances
- Restructures authorization documentation from a single file to a folder structure (authorization.md → authorization/index.md)
- Updates the Permission Management Module documentation to cover resource permission management UI components and services
- Updates ~30 documentation files across the repository to fix broken links following the authorization documentation restructuring
- Adds IKeyedObject interface documentation to the entities guide, explaining its role in resource-based authorization
Reviewed changes
Copilot reviewed 39 out of 40 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/en/framework/fundamentals/authorization/resource-based-authorization.md | New comprehensive guide for resource-based authorization including definitions, usage examples, and integration with Permission Management Module |
| docs/en/framework/fundamentals/authorization/index.md | Updated main authorization document with references to resource-based authorization and restructured relative paths |
| docs/en/framework/architecture/domain-driven-design/entities.md | Added IKeyedObject interface documentation explaining its usage in resource authorization scenarios |
| docs/en/modules/permission-management.md | Extended with resource permission management sections including UI integration examples for MVC/Blazor/Angular, IResourcePermissionManager service, and cleanup guidelines |
| docs/en/docs-nav.json | Updated navigation structure to include resource-based authorization as a sub-item under authorization |
| docs/en/framework/ui/angular/account-module.md | Updated authorization link (contains incorrect path) |
| docs/en/framework/ui/blazor/navigation-menu.md | Updated authorization link (contains incorrect path) |
| docs/en/ui-themes/lepton-x-lite/angular.md | Updated authorization link to new structure |
| docs/en/tutorials/book-store/part-08.md | Updated authorization link to new structure |
| docs/en/tutorials/book-store/part-05.md | Updated authorization link to new structure |
| docs/en/solution-templates/single-layer-web-application/solution-structure.md | Updated authorization link to new structure |
| docs/en/solution-templates/single-layer-web-application/overview.md | Updated authorization link to new structure |
| docs/en/solution-templates/microservice/permission-management.md | Updated authorization link to new structure |
| docs/en/solution-templates/microservice/overview.md | Updated authorization link to new structure |
| docs/en/solution-templates/layered-web-application/overview.md | Updated authorization link to new structure |
| docs/en/modules/openiddict.md | Updated authorization link to new structure |
| docs/en/modules/openiddict-pro.md | Updated authorization link to new structure |
| docs/en/modules/identity.md | Updated authorization link to new structure |
| docs/en/modules/identity-pro.md | Updated authorization link to new structure |
| docs/en/index.md | Updated authorization link to new structure |
| docs/en/framework/ui/mvc-razor-pages/* (6 files) | Updated authorization links to new structure |
| docs/en/framework/ui/blazor/* (3 files) | Updated authorization links to new structure |
| docs/en/framework/ui/angular/* (2 files) | Updated authorization links to new structure |
| docs/en/framework/infrastructure/* (2 files) | Updated authorization links to new structure |
| docs/en/framework/fundamentals/* (3 files) | Updated authorization links and added resource-based authorization references |
| docs/en/framework/architecture/* (2 files) | Updated authorization links to new structure |
| docs/en/framework/api-development/standard-apis/configuration.md | Updated authorization link to new structure |
| docs/en/deployment/configuring-production.md | Updated authorization link to new structure |
| ````csharp | ||
| public async Task DeleteDocumentAsync(Guid id) | ||
| { | ||
| // Delete the document | ||
| await _documentRepository.DeleteAsync(id); | ||
|
|
||
| // Clean up all permissions for this resource | ||
| await _resourcePermissionManager.DeleteAsync( | ||
| resourceName: "MyApp.Document", | ||
| resourceKey: id.ToString(), | ||
| providerName: "U", | ||
| providerKey: null // Deletes for all users | ||
| ); | ||
|
|
||
| await _resourcePermissionManager.DeleteAsync( | ||
| resourceName: "MyApp.Document", | ||
| resourceKey: id.ToString(), | ||
| providerName: "R", | ||
| providerKey: null // Deletes for all roles | ||
| ); | ||
| } | ||
| ```` |
There was a problem hiding this comment.
The cleanup example shows calling DeleteAsync twice with different provider names. Consider mentioning that there may also be Client provider permissions that need cleanup, or clarify that this example only shows User and Role cleanup for simplicity. Additionally, consider noting that calling DeleteAsync with providerKey null will delete all permissions for that provider and resource, which could be done in a loop if there are multiple providers to clean up.
| Implementing resource-based authorization involves three main steps: | ||
|
|
||
| 1. **Define** resource permissions in your `PermissionDefinitionProvider` | ||
| 2. **Check** permissions using `IResourcePermissionChecker` |
There was a problem hiding this comment.
The step 2 description mentions using IResourcePermissionChecker, but the subsequent code examples primarily demonstrate using IAuthorizationService. While both approaches are valid, this creates a potential inconsistency. Consider updating step 2 to mention both IAuthorizationService (for simpler use cases) and IResourcePermissionChecker (for advanced scenarios), or clarify that IAuthorizationService is the recommended approach with IResourcePermissionChecker available for advanced use cases.
| 2. **Check** permissions using `IResourcePermissionChecker` | |
| 2. **Check** permissions using `IAuthorizationService` (recommended for most scenarios) or `IResourcePermissionChecker` for advanced use cases |
| var book = await _bookRepository.GetAsync(id); | ||
|
|
||
| // Check if the current user can view this specific book | ||
| var isGranted = await AuthorizationService.IsGrantedAsync(book, BookStorePermissions.Books.Resources.View); // AuthorizationService is a property of the ApplicationService class and will be automatically injected. |
There was a problem hiding this comment.
The comment on line 151 is quite long and appears directly after the code. Consider moving this explanatory comment to a separate line before the method call, or converting it to a block comment above the line for better readability.
| var book = await _bookRepository.GetAsync(id); | ||
|
|
||
| // Check if the current user can edit this specific book | ||
| var isGranted = await AuthorizationService.IsGrantedAsync(book, BookStorePermissions.Books.Resources.Edit); // AuthorizationService is a property of the ApplicationService class and will be automatically injected. |
There was a problem hiding this comment.
Similar to line 151, this inline comment is quite long. Consider moving it to a separate line or block comment above for better code readability.
Description
Resolves #24297
authorization.mdtoauthorization/index.md(the URLs are not broken) - @hikalkan I can revert that if you want-authorization/resource-based-authorization.mdand explained the featurepermission-management.md,authorization/index.mdandentities.mddocuments and mentioned the new feature.Checklist