{"id":22787351,"url":"https://github.com/aserto-dev/aserto-dotnet","last_synced_at":"2025-07-07T03:09:18.632Z","repository":{"id":38340050,"uuid":"385333797","full_name":"aserto-dev/aserto-dotnet","owner":"aserto-dev","description":"Aserto dotnet SDK","archived":false,"fork":false,"pushed_at":"2025-04-11T08:56:15.000Z","size":2002,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-11T11:47:48.039Z","etag":null,"topics":["aspnetcore","authorization","authorization-middleware","dotnet"],"latest_commit_sha":null,"homepage":"https://docs.aserto.com/docs/software-development-kits/dotnetcore","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aserto-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-12T17:44:03.000Z","updated_at":"2025-04-11T07:02:32.000Z","dependencies_parsed_at":"2024-07-22T10:12:20.887Z","dependency_job_id":"0d11a0e7-ce31-4ea3-bcd3-aaac514363c5","html_url":"https://github.com/aserto-dev/aserto-dotnet","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/aserto-dev/aserto-dotnet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-dotnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-dotnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-dotnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-dotnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aserto-dev","download_url":"https://codeload.github.com/aserto-dev/aserto-dotnet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-dotnet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264005190,"owners_count":23542830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aspnetcore","authorization","authorization-middleware","dotnet"],"created_at":"2024-12-12T00:54:21.498Z","updated_at":"2025-07-07T03:09:18.608Z","avatar_url":"https://github.com/aserto-dev.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# .NET Client library for Aserto\n\n[![ci](https://github.com/aserto-dev/aserto-dotnet/actions/workflows/ci.yaml/badge.svg)](https://github.com/aserto-dev/aserto-dotnet/actions/workflows/ci.yaml) [![Coverage Status](https://coveralls.io/repos/github/aserto-dev/aserto-dotnet/badge.svg?branch=main\u0026t=1UzNg5)](https://coveralls.io/github/aserto-dev/aserto-dotnet?branch=main) [![NuGet version](https://img.shields.io/nuget/v/Aserto.AspNetCore.Middleware?style=flat)](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/)[![Maintainability](https://api.codeclimate.com/v1/badges/8d946af86d3dbd10956b/maintainability)](https://codeclimate.com/github/aserto-dev/aserto-dotnet/maintainability)\n\nAserto.Clients is a library that allows .NET applications to use an Aserto Authorizer and Directory Client.\n\n## Installation\n[Aserto.Clients](https://www.nuget.org/packages/Aserto.Clients/) is provided as a NuGet package. \n\nIt can be installed:\n* Using Package Manager:\n```powershell\nInstall-Package Aserto.Clients\n```\n\n * Using .NET CLI\n```sh\ndotnet add package Aserto.Clients\n```\n\n## Authorizer Client\nA new Authorizer Client can be created as follows:\n```csharp\n   //Initialize using constructor\n   AsertoAuthorizerOptions authzOpts = new AsertoAuthorizerOptions();\n\n   // Set connection details\n   authzOpts.AuthorizerApiKey = ConfigurationManager.AppSettings[\"Authorizer.API.Key\"];            \n   authzOpts.TenantID = ConfigurationManager.AppSettings[\"Authorizer.TenantID\"];\n   authzOpts.ServiceUrl = ConfigurationManager.AppSettings[\"Authorizer.ServiceURL\"];\n   authzOpts.Insecure = Convert.ToBoolean(ConfigurationManager.AppSettings[\"Authorizer.Insecure\"]);\n                       \n   var authorizerOptions = Options.Create(authzOpts);\n   var client = new AuthorizerAPIClient(authorizerOptions, new NullLoggerFactory());\n```\n\nExample call:\n```csharp\n var result = client.ListPoliciesAsync(new ListPoliciesRequest() { PolicyInstance = new PolicyInstance(){\n                Name=\"policy-todo\",\n                InstanceLabel=\"policy-todo\"\n            }\n```\n\n## Directory Client\nA new Directory Client can be created as follows:\n```csharp\n\n   var logggerFactory = new NullLoggerFactory();\n   // Initialize options using consttructor.\n   var options = new AsertoDirectoryOptions(\"url_and_port_to_directory_service\", \"directory_api_key\", \"directory_tenant_id\", false);\n\n   // Intialize optons reading the appsettings.json file.\n   var options = new AsertoDirectoryOptions();\n   Configuration.GetSection(\"AsertoDirectory\").Bind(options);\n\n   var directoryClient = new Directory(options, logggerFactory);\n\n```\nyou'll need to provide the directory service URL, an API key and the Tenant ID.\nThe client can be configure to use SSL connection as insecure by providing `options.Insecure = true;`.\n\nExample call to the directory client:\n```csharp\n\n   public async Task GetObject()\n   {\n      //...\n\n      var directoryClient = new Directory(options, logggerFactory);\n\n      // Get an object.\n      var getObjectResp = await directoryClient.GetObjectAsync(\"object_key\",\"object_type\");\n\n      // Get the identities for a user.\n      var getRelationsResp = await directoryAPI.GetRelationsAsync(subjectType: \"user\", subjectKey: \"userID\",relationName: \"identifier\", relationObjectType: \"identity\", pageSize: 10);\n\n      //...\n   }\n\n```\n\n## Examples\n\n* [Aserto Authorizer Client CLI](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/AuthorizerClientExample)\n* [Directory Client CLI](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/DirectoryClientExampleCLI)\n\n# .NET Middleware library for Aserto\n\n[![ci](https://github.com/aserto-dev/aserto-dotnet/actions/workflows/ci.yaml/badge.svg)](https://github.com/aserto-dev/aserto-dotnet/actions/workflows/ci.yaml) [![Coverage Status](https://coveralls.io/repos/github/aserto-dev/aserto-dotnet/badge.svg?branch=main\u0026t=1UzNg5)](https://coveralls.io/github/aserto-dev/aserto-dotnet?branch=main) [![NuGet version](https://img.shields.io/nuget/v/Aserto.AspNetCore.Middleware?style=flat)](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/)[![Maintainability](https://api.codeclimate.com/v1/badges/8d946af86d3dbd10956b/maintainability)](https://codeclimate.com/github/aserto-dev/aserto-dotnet/maintainability)\n\nAserto.AspNetCore.Middleware is a middleware that allows .NET Asp applications to use Topaz Authorizer as the Authorization provider.\n\n## Prerequisit* [.NET SDK](https://dotnet.microsoft.com/download)\n\n## Installation\n[Aserto.AspNetCore.Middleware](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/) is provided as a NuGet package. \n[Aserto.Middleware] (https://www.nuget.org/packages/Aserto.Middleware/) is the provided NuGet package that can be used with .Net Framework. \n\nIt can be installed:\n* Using Package Manager:\n```powershell\nInstall-Package Aserto.AspNetCore.Middleware\n```\nor \n```powershell\nInstall-Package Aserto.Middleware\n```\n\n * Using .NET CLI\n```sh\ndotnet add package Aserto.AspNetCore.Middleware\n``` \nor \n```sh\ndotnet add package Aserto.Middleware\n```\n\n## Configuration\nThe following configuration settings are required for Aserto.AspNetCore middleware. You can add them to your `appsettings.json`:\n```json\n\"Aserto\": {\n    \"PolicyRoot\": \"YOUR_POLICY_ROOT\",\n}\n\"AsertoDirectory\": {\n   \"DirectoryTenantID\": \"DIRECTORY_TENANT_ID\",\n}\n```\n\nThe middleware accepts the following optional parameters:\n\n***Aserto section***\n\n| Parameter name | Default value | Description |\n| -------------- | ------------- | ----------- |\n| Enabled | true | Enables or disables Aserto Authorization |\n| ServiceUrl | \"https://localhost:8282\" | Sets the URL for the authorizer endpoint. |\n| Decision | \"allowed\" | The decision that will be used by the middleware when creating an authorizer request. |\n| AuthorizerApiKey | \"\" | The authorizer API Key |\n| TenantID | \"\" | The Aserto Tenant ID |\n| Insecure | false | Indicates whether insecure service connections are allowed when using SSL |\n| PolicyName | \"\" | The Aserto policy name |\n| PolicyInstanceLabel | \"\" | The label of the active policy runtime |\n\n***AsertoDirectory section***\n\n| Parameter name | Default value | Description |\n| -------------- | ------------- | ----------- |\n| DirectoryInsecure | false | Indicates whether insecure directory service connections are allowed when using SSL |\n| DirectoryTenantID | \"\" | The Aserto Tenant ID of the directory service |\n| DirectoryServiceUrl | \"https://localhost:9292\" | Sets the URL for the directory endpoint. |\n| DirectoryApiKey | \"\" | The directory API Key |\n\n\n## Usage for Aserto.AspNetCore.Middleware\nTo configure Aserto Authorization, the Aserto Authorization Service needs to be added to the `ConfigureServices` method in `Startup.cs`\n\n```csharp\n// Startup.cs\n\npublic void ConfigureServices(IServiceCollection services)\n{\n   //..\n\n   // Adds the Aserto Authorization service\n   services.AddAsertoAuthorization(options =\u003e Configuration.GetSection(\"Aserto\").Bind(options));\n \n   //..  \n}\n\n```\n\nTo use the Authorization, you can now define an Authorization policy with the `AsertoDecisionRequirement` using the following code snippet\n```csharp\n// Startup.cs\n\npublic void ConfigureServices(IServiceCollection services)\n{\n   //..\n\n   services.AddAuthorization(options =\u003e\n   {\n       options.AddPolicy(\"Aserto\", policy =\u003e policy.Requirements.Add(new AsertoDecisionRequirement()));\n   });\n\n   //..\n}\n```\nTo protect your endpoints using Aserto authorization, you need to apply the `[Authorize(\"Aserto\")]` attribute to them.\n\nUsing 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.\n\n```csharp\n// Startup.cs\n\npublic void ConfigureServices(IServiceCollection services)\n{\n   //..\n\n\n   // Use Aserto authorization as the default authorization policy.\n   services.AddAuthorization(options =\u003e\n   {\n       // User is authenticated via a cookie.\n       var policy = new AuthorizationPolicyBuilder(CookieAuthenticationDefaults.AuthenticationScheme);\n       policy.AddRequirements(new AsertoDecisionRequirement());\n       options.DefaultPolicy = policy.Build();\n   });\n   \n   //..\n}\n```\n\n\n### Identity\nTo determine the identity of the user, the middleware checks the following Claim types:\n\n| Name | Description | URI |\n| ---- |------------ |---- |\n| E-Mail Address | The e-mail address of the user | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |\n| Name | The unique name of the user | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |\n| Name Identifier | The SAML name identifier of the user | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |\n\nThese can be overwritten by passing other claim types to the `AsertoDecisionRequirement`:\n\n```csharp\n// Startup.cs\n\npublic void ConfigureServices(IServiceCollection services)\n{\n   //..\n\n   services.AddAuthorization(options =\u003e\n   {\n      options.AddPolicy(\"Aserto\", policy =\u003e \n         policy.Requirements.Add(new AsertoDecisionRequirement(new List\u003cstring\u003e \n         { \n            \"mytype1\", \n            \"mytype2\" \n         })));\n   });\n\n   //..\n}\n```\n\n## URL path to policy mapping\nBy default, when computing the policy path, the middleware:\n* converts all slashes to dots\n* converts any character that is not alpha, digit, dot or underscore to underscore\n* converts uppercase characters in the URL path to lowercases\n\nThis behavior can be overwritten by providing a custom function to the `PolicyPathMapper` AsertoAuthorization option:\n```csharp\n// Startup.cs\n\npublic void ConfigureServices(IServiceCollection services)\n{\n   //..\n\n   // Adds the Aserto Authorization service\n   services.AddAsertoAuthorization(options =\u003e\n   {\n      Configuration.GetSection(\"Aserto\").Bind(options));\n      options.PolicyPathMapper = (policyRoot, httpRequest) =\u003e\n      {\n          return \"custom.policy.path\";\n      };\n   }\n   //..  \n}\n\n```\n\n## Resource Mapper\nA 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 `:`.\n\nResource data can be overwritten by providing a custom function to the `ResourceMapper` AsertoAuthorization option\n\n```csharp\n// Startup.cs\n\npublic void ConfigureServices(IServiceCollection services)\n{\n   //..\n\n   // Adds the Aserto Authorization service\n   services.AddAsertoAuthorization(options =\u003e\n     {\n       options.ResourceMapper = (policyRoot, httpRequest) =\u003e\n       {\n         Struct result = new Struct();\n         result.Fields[\"asset\"] = Value.ForString(\"megaSeeds\");\n\n         return result;\n       };\n       Configuration.GetSection(\"Aserto\").Bind(options);\n   });\n   //..  \n}\n\n```\n\n## Directory Client\nA new Directory Client can be creating as follows:\n```csharp\n\n   var logggerFactory = new NullLoggerFactory();\n   // Initialize options using consttructor.\n   var options = new AsertoDirectoryOptions(\"url_and_port_to_directory_service\", \"directory_api_key\", \"directory_tenant_id\", false);\n\n   // Intialize optons reading the appsettings.json file.\n   var options = new AsertoDirectoryOptions();\n   Configuration.GetSection(\"AsertoDirectory\").Bind(options);\n\n   var directoryClient = new Directory(options, logggerFactory);\n\n```\nyou'll need to provide the directory service URL, an API key and the Tenant ID.\nThe client can be configure to use SSL connection as insecure by providing `options.Insecure = true;`.\n\nExample call to the directory client:\n```csharp\n\n   public async Task GetObject()\n   {\n      //...\n\n      var directoryClient = new Directory(options, logggerFactory);\n\n      // Get an object.\n      var getObjectResp = await directoryClient.GetObjectAsync(\"object_key\",\"object_type\");\n\n      // Get the identities for a user.\n      var getRelationsResp = await directoryAPI.GetRelationsAsync(subjectType: \"user\", subjectKey: \"userID\",relationName: \"identifier\", relationObjectType: \"identity\", pageSize: 10);\n\n      //...\n   }\n\n```\n\n\n## Building \u0026 testing\n\n **_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):\n\n```sh\ndotnet build .\\aserto-dotnet.sln\n```\n\n`dotnet` CLI can be used to run the tests from the project:\n```sh\ndotnet test .\\aserto-dotnet.sln\n```\n\n## Examples\n\n* [Auth0 authentication and Aserto authorization](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/Auth0)\n* [Duende Identity server for authentication and Aserto authorization](https://github.com/aserto-dev/aserto-dotnet/tree/main/examples/Duende)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserto-dev%2Faserto-dotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faserto-dev%2Faserto-dotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserto-dev%2Faserto-dotnet/lists"}