https://github.com/aserto-dev/aserto-dotnet
Aserto dotnet SDK
https://github.com/aserto-dev/aserto-dotnet
aspnetcore authorization authorization-middleware dotnet
Last synced: about 1 month ago
JSON representation
Aserto dotnet SDK
- Host: GitHub
- URL: https://github.com/aserto-dev/aserto-dotnet
- Owner: aserto-dev
- Created: 2021-07-12T17:44:03.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-07T13:46:08.000Z (about 2 months ago)
- Last Synced: 2025-04-07T14:39:23.895Z (about 2 months ago)
- Topics: aspnetcore, authorization, authorization-middleware, dotnet
- Language: C#
- Homepage: https://docs.aserto.com/docs/software-development-kits/dotnetcore
- Size: 1.9 MB
- Stars: 4
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# .NET Client library for Aserto
[](https://github.com/aserto-dev/aserto-dotnet/actions/workflows/ci.yaml) [](https://coveralls.io/github/aserto-dev/aserto-dotnet?branch=main) [](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/)[](https://codeclimate.com/github/aserto-dev/aserto-dotnet/maintainability)
Aserto.Clients is a library that allows .NET applications to use an Aserto Authorizer and Directory Client.
## Installation
[Aserto.Clients](https://www.nuget.org/packages/Aserto.Clients/) is provided as a NuGet package.
It can be installed:
* Using Package Manager:
```powershell
Install-Package Aserto.Clients
```
* Using .NET CLI
```sh
dotnet add package Aserto.Clients
```
## Authorizer Client
A new Authorizer Client can be created as follows:
```csharp
//Initialize using constructor
AsertoAuthorizerOptions authzOpts = new AsertoAuthorizerOptions();
// Set connection details
authzOpts.AuthorizerApiKey = ConfigurationManager.AppSettings["Authorizer.API.Key"];
authzOpts.TenantID = ConfigurationManager.AppSettings["Authorizer.TenantID"];
authzOpts.ServiceUrl = ConfigurationManager.AppSettings["Authorizer.ServiceURL"];
authzOpts.Insecure = Convert.ToBoolean(ConfigurationManager.AppSettings["Authorizer.Insecure"]);
var authorizerOptions = Options.Create(authzOpts);
var client = new AuthorizerAPIClient(authorizerOptions, new NullLoggerFactory());
```
Example call:
```csharp
var result = client.ListPoliciesAsync(new ListPoliciesRequest() { PolicyInstance = new PolicyInstance(){
Name="policy-todo",
InstanceLabel="policy-todo"
}
```
## Directory Client
A new Directory Client can be created as follows:
```csharp
var logggerFactory = new NullLoggerFactory();
// Initialize options using consttructor.
var options = new AsertoDirectoryOptions("url_and_port_to_directory_service", "directory_api_key", "directory_tenant_id", false);
// Intialize optons reading the appsettings.json file.
var options = new AsertoDirectoryOptions();
Configuration.GetSection("AsertoDirectory").Bind(options);
var directoryClient = new Directory(options, logggerFactory);
```
you'll need to provide the directory service URL, an API key and the Tenant ID.
The client can be configure to use SSL connection as insecure by providing `options.Insecure = true;`.
Example call to the directory client:
```csharp
public async Task GetObject()
{
//...
var directoryClient = new Directory(options, logggerFactory);
// Get an object.
var getObjectResp = await directoryClient.GetObjectAsync("object_key","object_type");
// Get the identities for a user.
var getRelationsResp = await directoryAPI.GetRelationsAsync(subjectType: "user", subjectKey: "userID",relationName: "identifier", relationObjectType: "identity", pageSize: 10);
//...
}
```
## Examples
* [Aserto Authorizer Client CLI](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/AuthorizerClientExample)
* [Directory Client CLI](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/DirectoryClientExampleCLI)
# .NET Middleware library for Aserto
[](https://github.com/aserto-dev/aserto-dotnet/actions/workflows/ci.yaml) [](https://coveralls.io/github/aserto-dev/aserto-dotnet?branch=main) [](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/)[](https://codeclimate.com/github/aserto-dev/aserto-dotnet/maintainability)
Aserto.AspNetCore.Middleware is a middleware that allows .NET Asp applications to use Topaz Authorizer as the Authorization provider.
## Prerequisit* [.NET SDK](https://dotnet.microsoft.com/download)
## Installation
[Aserto.AspNetCore.Middleware](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/) is provided as a NuGet package.
[Aserto.Middleware] (https://www.nuget.org/packages/Aserto.Middleware/) is the provided NuGet package that can be used with .Net Framework.
It can be installed:
* Using Package Manager:
```powershell
Install-Package Aserto.AspNetCore.Middleware
```
or
```powershell
Install-Package Aserto.Middleware
```
* Using .NET CLI
```sh
dotnet add package Aserto.AspNetCore.Middleware
```
or
```sh
dotnet add package Aserto.Middleware
```
## Configuration
The following configuration settings are required for Aserto.AspNetCore middleware. You can add them to your `appsettings.json`:
```json
"Aserto": {
"PolicyRoot": "YOUR_POLICY_ROOT",
}
"AsertoDirectory": {
"DirectoryTenantID": "DIRECTORY_TENANT_ID",
}
```
The middleware accepts the following optional parameters:
***Aserto section***
| Parameter name | Default value | Description |
| -------------- | ------------- | ----------- |
| Enabled | true | Enables or disables Aserto Authorization |
| ServiceUrl | "https://localhost:8282" | Sets the URL for the authorizer endpoint. |
| Decision | "allowed" | The decision that will be used by the middleware when creating an authorizer request. |
| AuthorizerApiKey | "" | The authorizer API Key |
| TenantID | "" | The Aserto Tenant ID |
| Insecure | false | Indicates whether insecure service connections are allowed when using SSL |
| PolicyName | "" | The Aserto policy name |
| PolicyInstanceLabel | "" | The label of the active policy runtime |
***AsertoDirectory section***
| Parameter name | Default value | Description |
| -------------- | ------------- | ----------- |
| DirectoryInsecure | false | Indicates whether insecure directory service connections are allowed when using SSL |
| DirectoryTenantID | "" | The Aserto Tenant ID of the directory service |
| DirectoryServiceUrl | "https://localhost:9292" | Sets the URL for the directory endpoint. |
| DirectoryApiKey | "" | The directory API Key |
## Usage for Aserto.AspNetCore.Middleware
To configure Aserto Authorization, the Aserto Authorization Service needs to be added to the `ConfigureServices` method in `Startup.cs`
```csharp
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
//..
// Adds the Aserto Authorization service
services.AddAsertoAuthorization(options => Configuration.GetSection("Aserto").Bind(options));
//..
}
```
To use the Authorization, you can now define an Authorization policy with the `AsertoDecisionRequirement` using the following code snippet
```csharp
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
//..
services.AddAuthorization(options =>
{
options.AddPolicy("Aserto", policy => policy.Requirements.Add(new AsertoDecisionRequirement()));
});
//..
}
```
To protect your endpoints using Aserto authorization, you need to apply the `[Authorize("Aserto")]` attribute to them.
Using the following code snippet, you can set Aserto authorization as the default Authorization policy. This will enable Aserto Authorization without having to explicitly specify the policy name in the `[Authorize]` attribute.
```csharp
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
//..
// Use Aserto authorization as the default authorization policy.
services.AddAuthorization(options =>
{
// User is authenticated via a cookie.
var policy = new AuthorizationPolicyBuilder(CookieAuthenticationDefaults.AuthenticationScheme);
policy.AddRequirements(new AsertoDecisionRequirement());
options.DefaultPolicy = policy.Build();
});
//..
}
```
### Identity
To determine the identity of the user, the middleware checks the following Claim types:
| Name | Description | URI |
| ---- |------------ |---- |
| E-Mail Address | The e-mail address of the user | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
| Name | The unique name of the user | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
| Name Identifier | The SAML name identifier of the user | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
These can be overwritten by passing other claim types to the `AsertoDecisionRequirement`:
```csharp
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
//..
services.AddAuthorization(options =>
{
options.AddPolicy("Aserto", policy =>
policy.Requirements.Add(new AsertoDecisionRequirement(new List
{
"mytype1",
"mytype2"
})));
});
//..
}
```
## URL path to policy mapping
By default, when computing the policy path, the middleware:
* converts all slashes to dots
* converts any character that is not alpha, digit, dot or underscore to underscore
* converts uppercase characters in the URL path to lowercases
This behavior can be overwritten by providing a custom function to the `PolicyPathMapper` AsertoAuthorization option:
```csharp
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
//..
// Adds the Aserto Authorization service
services.AddAsertoAuthorization(options =>
{
Configuration.GetSection("Aserto").Bind(options));
options.PolicyPathMapper = (policyRoot, httpRequest) =>
{
return "custom.policy.path";
};
}
//..
}
```
## Resource Mapper
A resource can be any structured data that the authorization policy uses to evaluate decisions. By default, middleware add to the resource context all the route parameters that start with `:`.
Resource data can be overwritten by providing a custom function to the `ResourceMapper` AsertoAuthorization option
```csharp
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
//..
// Adds the Aserto Authorization service
services.AddAsertoAuthorization(options =>
{
options.ResourceMapper = (policyRoot, httpRequest) =>
{
Struct result = new Struct();
result.Fields["asset"] = Value.ForString("megaSeeds");
return result;
};
Configuration.GetSection("Aserto").Bind(options);
});
//..
}
```
## Directory Client
A new Directory Client can be creating as follows:
```csharp
var logggerFactory = new NullLoggerFactory();
// Initialize options using consttructor.
var options = new AsertoDirectoryOptions("url_and_port_to_directory_service", "directory_api_key", "directory_tenant_id", false);
// Intialize optons reading the appsettings.json file.
var options = new AsertoDirectoryOptions();
Configuration.GetSection("AsertoDirectory").Bind(options);
var directoryClient = new Directory(options, logggerFactory);
```
you'll need to provide the directory service URL, an API key and the Tenant ID.
The client can be configure to use SSL connection as insecure by providing `options.Insecure = true;`.
Example call to the directory client:
```csharp
public async Task GetObject()
{
//...
var directoryClient = new Directory(options, logggerFactory);
// Get an object.
var getObjectResp = await directoryClient.GetObjectAsync("object_key","object_type");
// Get the identities for a user.
var getRelationsResp = await directoryAPI.GetRelationsAsync(subjectType: "user", subjectKey: "userID",relationName: "identifier", relationObjectType: "identity", pageSize: 10);
//...
}
```
## Building & testing
**_Note:_** We recommend using Windows to build and contribute to this project because of the dotnet framework projects present in this solution (Aserto.Middleware, WebAPI and MvCApp examples). If you want to build this project on Linux or macOS, please make sure to remove these projects from the solution, then you can build using the [.Net Core SDK](https://dotnet.microsoft.com/download):
```sh
dotnet build .\aserto-dotnet.sln
```
`dotnet` CLI can be used to run the tests from the project:
```sh
dotnet test .\aserto-dotnet.sln
```
## Examples
* [Auth0 authentication and Aserto authorization](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/Auth0)
* [Duende Identity server for authentication and Aserto authorization](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/Duende)