Getting started with Balea in ASP.NET Core¶
In this article, we are going to see how easy it is to use Balea in your ASP.NET Core application using the NuGet packages provided by Xabaril.
> In samples/WebApp you’ll find a complete Balea example in ASP.NET Core.
Setup¶
To install Balea open a console window and type the following command using the .NET Core CLI:
dotnet package add Balea.Configuration.Store
or using Powershell or Package Manager:
Install-Package Balea.Configuration.Store
or install via NuGet.
In the ConfigureServices method of Startup.cs, register the Balea services:
services
.AddBalea()
.AddConfigurationStore(Configuration);
AddBalea
method allows you to register the set of services that Balea needs to work. The AddConfigurationStore
method registers the configuration store to use, in this case, based on the default configuration system of ASP.NET Core
By default Balea use a configuration section called Balea but you can change if you want:
services
.AddBalea()
.AddConfigurationStore(Configuration, key: "your key");
Defining applications¶
Applications allow you to manage authorization in multiple different software projects. Each application has its own unique roles and delegations. If you have a simple scenario where you only have one application, Balea give you a default application name called “default”:
{
"Balea": {
"applications": [
{
"name": "default"
}
]
}
}
Or you can create as many applications as you want:
{
"Balea": {
"applications": [
{
"name": "hr"
},
{
"name": "erp"
}
]
}
}
And you could specify which application do you want to use:
services
.AddBalea(options => options.SetApplicationName("hr"))
.AddConfigurationStore(Configuration);
Defining roles¶
Define roles is a straightforward proccess. Name the role, add a description, enable it and add permissions:
{
"Balea": {
"applications": [
{
"name": "default",
"roles": [
{
"name": "teacher",
"description": "Teacher role",
"enabled": true,
"permissions": [
"grades.edit",
"grades.view"
]
}
}
]
}
}
Additionaly, roles coming from authentication system can be mapped to the application roles:
{
"Balea": {
"applications": [
{
"name": "default",
"roles": [
{
"name": "student",
"description": "Student role",
"enabled": true,
"permissions": [
"grades.view"
],
"mappings": [
"customer"
]
}
}
]
}
}
Using roles in our controller and actions¶
By default, Balea automatically maps roles and permissions to the user’s claims. This is mainly useful if you want to use the standard claims API or the [Authorize]
attribute. For example:
[Authorize(Roles = "custodian")]
public IActionResult OpenDoor()
{
return View();
}
Or using the standard claims API:
public IActionResult OpenDoor()
{
if (User.IsInRole("custodian"))
{
return View();
}
return Forbid();
}
Using permissions in ASP.NET Core authorization policies¶
Also, Balea automatically maps permissions to ASP.NET Core authorization policies. You’ll need to decorate your controllers/actions like this:
[Authorize(Policy = "grades.view")]
public IActionResult ViewGrades()
{
return View();
}
Testing the authorization¶
If you run the example samples/WebApp you could see that Balea creates on the fly a new ClaimsIdentity
with all the information from the authorization store for the user:
