TFE.Umbraco.AccessRestriction is a IP access restriction manager for Umbraco. The package features a dashboard and editor that lets users manage whitelisted IP addresses from within the Umbraco backoffice. IPs can be added with a description and have both a creation and modified date and user.
| License: | Umbraco: | Target Framework: |
|---|---|---|
| MIT License | Umbraco 17 | .NET 10 |
The Umbraco 17.1.0 version of this package is only available via NuGet. To install the package, you can use either .NET CLI:
dotnet add package TFE.Umbraco.AccessRestriction --version 17.1.0or the older NuGet Package Manager:
NuGet\Install-Package TFE.Umbraco.AccessRestriction --version 17.1.0Before the Umbraco middleware, add the IPAccessRestrictionMiddleware: to Program.cs or Startup.cs in previous versions:
app.UseMiddleware<IPAccessRestrictionMiddleware>();Add the necessary usings to Program.cs (or Startup.cs):
using TFE.Umbraco.AccessRestriction.Middleware;Add these settings to appsettings.json
"TFE.Umbraco.AccessRestriction": {
"Disable": true,
"HttpStatusCode": 403,
"HttpResponseMessage": "",
"LogBlockedIP": false,
"LocalHost": "127.0.0.1",
"ExcludePaths": ["/umbraco", "/App_Plugins", "/api/keepalive/ping"],
"IncludePaths": [],
"IsCloudFlare": false,
"CustomHeader": "",
"Whitelist": ["127.0.0.1"],
"Blacklist": [],
"ShowConfigIpsInBackoffice": true
}Either use "ExcludePaths" or "IncludePaths" to direct the IP blocker.
When installed on a cloud environment make sure to add your the cloud IP Addresses. Replace the following ExcludePaths property in appsettings.json :
"ExcludePaths": ["/umbraco", "/App_Plugins", "/api/keepalive/ping", "/umbraco-signin-oidc", "/sb"],Set to true when using Cloudflare
"IsCloudFlare": true,If a proxy is being used, set the value of the 'CustomHeader' field to 'header' with the IP address used by the proxy.
"CustomHeader": "",There are three different ways to whitelist an IP address, through the dashboard interface, by adding the IP address to WhitelistedIps.txt or by adding the IP address to the WhiteList setting in the appsettings. All methods can be used simultaneously and separately.
"WhiteList": ["192.168.1.1", "192.168.1.2", "192.168.1.3", "::1", "192.168.1.4"],Add WhitelistedIps.txt to the root of your Umbraco project.
IP Addresses must be line separated and to add a comment use the #.
192.168.1.1
192.168.1.2 #John
192.168.1.3
::1
192.168.1.4 #HankIf ShowConfigIpsInBackoffice is set to true (by default) it will show the IP adresses from the appsettings.json or the WhitelistedIps.txt in the dashboard.
To block an IP address, add it to the BlackList setting in the appsettings.
"BlackList": ["192.168.1.1", "192.168.1.2", "192.168.1.3", "::1", "192.168.1.4"],The blacklist always takes precedence over all other settings.
If an IP address is present in the blacklist, it will always be blocked, even if:
- the path is listed in
ExcludePaths - the IP address is present in the whitelist
- Global dashboard for listing all whitelisted IP addresses.
- Package handles IP addresses added manually by a user with admin rights and IP addresses added to the WhitelistedIps.txt or appsettings.json.
- LogBlockedIP enables you to see all blocked IP addresses in the Umbraco log.
- Use _ as wildcard to add a range of IP addresses e.g. "192.168.1._"
- Include or exclude paths from being blocked.
A few settings have been changed in v17.1.0:
- IncludePaths and ExcludePaths have been changed from string to array:
"ExcludePaths": ["/umbraco", "/App_Plugins", "/api/keepalive/ping"],
"IncludePaths": [],- 'You don't have permission to access / on this server' is no longer shown when a request is blocked. The server's default 403 page is used instead. The following settings have been added to change this behaviour:
"HttpStatusCode": 403,
"HttpResponseMessage": "You don't have permission to access / on this server",If you've made changes to the frontend (e.g., using Vite or Lit), it's important to build the frontend assets before packing the NuGet package. This ensures that all the necessary files are correctly included in the package.
Before you pack the NuGet package, you need to build the frontend assets:
-
Navigate to the
TFE.Umbraco.AccessRestriction/clientdirectory of your project where the frontend files are located. -
Run the following command to build the frontend:
npm run build
This command compiles the frontend files, optimizes them for production, and places them in
TFE.Umbraco.AccessRestriction/src/wwwroot.
Once the frontend is built, you can proceed to create the NuGet package:
-
Open a terminal in
TFE.Umbraco.AccessRestriction/src. -
Run the following .NET CLI command to pack the NuGet package:
dotnet pack --configuration Release
This command creates a
.nupkgfile in thebin/Releasedirectory of your project. This file is the NuGet package that you can distribute.
After packing, you can publish your NuGet package to NuGet.org or any other NuGet server you use:
-
Use the following command to push the package to NuGet.org:
dotnet nuget push bin/Release/TFE.Umbraco.AccessRestriction.<version>.nupkg --api-key <Your_NuGet_API_Key> --source https://api.nuget.org/v3/index.json
Replace
<version>with the version number of your package, and<Your_NuGet_API_Key>with your actual NuGet API key.
npm run build: Builds the frontend assets.dotnet pack --configuration Release: Creates the NuGet package.dotnet nuget push: Publishes the package to NuGet.org.
By following these steps, you ensure that any frontend changes are properly included in the NuGet package, providing a seamless experience for users who install your package.
To raise a new bug, create an issue on the GitHub repository. To fix a bug or add new features, fork the repository and send a pull request with your changes. Feel free to add ideas to the repository's issues list if you would like to discuss anything related to the library.
This project is maintained by Henri Hessels and contributors. If you have any questions about the project please raise a issue on GitHub.
Thanks to the following people for their contributions:
- Ernst Jan Feenstra
- Timo Schraa