Merge pull request #143 from aserto-dev/update-aserto-dotnet-docs

Update aserto-dotnet sdk documentation

docs/software-development-kits/dotnet/clients.mdx

@@ -0,0 +1,37 @@
+---
+sidebar_label: Aserto Clients
+title: Aserto SDKs - ASP.NET Clients - Installation and setup
+description: Aserto SDKs - ASP.NET Clients - Installing and using the ASP.NET Clients
+---
+
+# ASP.NET Clients
+
+Aserto package containing the Aserto Authorizer and Aserto Directory Clients.
+
+## Overview
+
+This package allows .NET Standard 2.0 applications to interact with the Aserto Authorizer and Directory APIs.
+
+## 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
+
+```cmd
+dotnet add package Aserto.Clients
+```
+
+## Usage 
+
+In the [aserto-dotnet repository examples](https://github.com/aserto-dev/aserto-dotnet/tree/aserto_clients/examples) there are two CLI example applications that use the Aserto Clients package to interact with an Aserto Authorizer API and a Directory API respectively.
+
+You can use [Topaz](https://www.topaz.sh/) to spin up a local instance that exposes the APIs and provided the necessary configuration information in the example's *app.config* files to test and get familiar with the package and the APIs.

docs/software-development-kits/dotnet/asp-core-mvc.mdx → docs/software-development-kits/dotnet/dotnetcore.mdx

@@ -1,9 +1,123 @@
 ---
 sidebar_label: ASP.NET Core
-title: Topaz SDKs - ASP.NET Core middleware - MVC app
-description: Topaz SDKs - ASP.NET Core middleware - Setting an MVC app with Topaz Authentication
+title: Aserto SDKs - ASP.NET Core Aserto middleware - Installation and setup
+description: Aserto SDKs - ASP.NET Core Aserto middleware - Installing and using the ASP.NET Core Aserto middleware
 ---
 
+# ASP.NET Core Middleware
+
+Aserto Authorization middleware for ASP.NET core.
+
+## Overview
+
+This package allows ASP.NET applications to use Aserto as the Authorization provider.
+
+## Installation
+
+[Aserto.AspNetCore.Middleware](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/) is provided as a NuGet package.
+
+It can be installed:
+
+- Using Package Manager:
+
+```powershell
+Install-Package Aserto.AspNetCore.Middleware
+```
+
+- Using .NET CLI
+
+```cmd
+dotnet add package Aserto.AspNetCore.Middleware
+```
+
+## Configuration
+
+The following configuration settings are required for Aserto.AspNetCore middleware to run with Topaz. You can add them to your `appsettings.json`:
+
+```json
+// appsettings.json
+
+"Aserto": {
+    "ServiceUrl": "https://localhost:8282"
+    "PolicyName": "YOUR_POLICY_NAME",    
+    "PolicyRoot": "YOUR_POLICY_ROOT"
+}
+```
+
+These settings can be retrieved from the [Policy Settings](https://console.aserto.com/ui/policies) page of your Aserto account.
+
+The middleware accepts the following optional parameters:
+
+| Parameter name | Default value                             | Description                                                                           |
+| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| Enabled        | true                                      | Enables or disables Aserto Authorization.                                             |
+| ServiceUrl     | `https://authorizer.prod.aserto.com:8443` | Sets the URL for the authorizer endpoint.                                             |
+| Decision       | "allowed"                                 | The decision that will be used by the middleware when creating an authorizer request. |
+
+### 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<string>
+        {
+            "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";
+      };
+   });
+
+   //..
+}
+```
+
 ## Topaz Authorization on a ASP.NET Core MVC application
 
 **Creating and setting up the project**
@@ -324,14 +438,12 @@ To enable Topaz authorization, you need to add a dependency to the Aserto dotnet
 $dotnetmvc/src/QuickstartMVC$ dotnet add package Aserto.AspNetCore.Middleware
 ```
 
-Configure the Authorizer API Key, Tenant ID, Policy root and Policy ID in the `appsettings.json`:
+Configure the Policy root in the `appsettings.json`:
 
 ```json
 "Topaz": {
-    "AuthorizerApiKey": "YOUR_AUTHORIZER_API_KEY",
-    "TenantID": "YOUR_ASERTO_TENANT_ID",
-    "PolicyName": "YOUR_POLICY_NAME",
-    "PolicyInstanceLabel": "YOUR_POLICY_INSTANCE_ID"
+    "ServiceUrl": "https://localhost:8282",
+    "PolicyName": "YOUR_POLICY_NAME",    
 }
 ```
 
@@ -485,4 +597,4 @@ using Microsoft.AspNetCore.Authorization;
         }
 
 //..
-```
+```

docs/software-development-kits/dotnet/dotnetcorecheck.mdx

@@ -0,0 +1,80 @@
+---
+sidebar_label: ASP.NET Core Check
+title: Aserto SDKs - ASP.NET Core Check Middleware - Installation and setup
+description: Aserto SDKs - ASP.NET Core Check Middleware - Installing and using the ASP.NET Core Check Middleware
+---
+
+# ASP.NET Core Check Middleware (ReBAC)
+In addition to the pattern described by the Aserto Middleware, in which each route is authorized by its own policy module, the check middleware can be used to implement Relation-Based Access Control (rebac) in which authorization decisions are made by checking if a given subject has the necessary permission or relation to the object being accessed.
+
+This is achieved using the `Check` attribute of the `CheckMiddleware`.
+
+A check call needs three pieces of information:
+    - The type and key of the object.
+    - The name of the relation or permission to look for.
+    - The type and key of the subject. When omitted, the subject is derived from the middleware's Identity with type "user".
+
+## Installation
+
+[Aserto.AspNetCore.Middleware](https://www.nuget.org/packages/Aserto.AspNetCore.Middleware/) is provided as a NuGet package.
+
+It can be installed:
+
+- Using Package Manager:
+
+```powershell
+Install-Package Aserto.AspNetCore.Middleware
+```
+
+- Using .NET CLI
+
+```cmd
+dotnet add package Aserto.AspNetCore.Middleware
+```
+
+## Configuration
+
+The following configuration settings are required for Aserto.AspNetCore middleware to run with Topaz. You can add them to your `appsettings.json`:
+
+```json
+// appsettings.json
+
+"Aserto": {
+    "ServiceUrl": "https://localhost:8282",
+    "PolicyName": "YOUR_POLICY_NAME",    
+    "PolicyRoot": "YOUR_POLICY_ROOT"
+}
+```
+
+These settings can be retrieved from the [Policy Settings](https://console.aserto.com/ui/policies) page of your Aserto account.
+
+The middleware accepts the following optional parameters:
+
+| Parameter name | Default value                             | Description                                                                           |
+| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| Enabled        | true                                      | Enables or disables Aserto Authorization.                                             |
+| ServiceUrl     | `https://authorizer.prod.aserto.com:8443` | Sets the URL for the authorizer endpoint.                                             |
+| Decision       | "allowed"                                 | The decision that will be used by the middleware when creating an authorizer request. |
+
+## Usage 
+
+To use the check middleware in the `Startup.cs` you will need to add the check options and allow the service to add the check authorization:
+```
+            CheckOptions checkOptions = new CheckOptions();
+            Configuration.GetSection("Aserto").Bind(checkOptions.BaseOptions);
+            // Adding the check middleware
+            services.AddAsertoCheckAuthorization(checkOptions,
+            authorizerConfig =>
+            {
+                Configuration.GetSection("Aserto").Bind(authorizerConfig);
+            });
+```
+
+After the initialization in your controllers you can attach the check attribute to a method as show in the example bellow:
+```
+        [HttpPost]        
+        [Check(objectID: "resource-creators", objectType: "resource-creator", relation: "member")]
+
+```        
+
+The [todo-dotnet-v2](https://github.com/aserto-demo/todo-dotnet-v2/tree/main) example highlights the usage of the ASP.NET Core Aserto middleware next to the ASP.NET Core Check Middleware. 

docs/software-development-kits/dotnet/middleware.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_label: ASP.NET Framework
+title: Aserto SDKs - ASP.NET middleware - Installation and setup
+description: Aserto SDKs - ASP.NET middleware - Installing and using the ASP.NET middleware
+---
+
+# ASP.NET Middleware
+
+Aserto Authorization middleware for ASP.NET Framework v4.8
+
+## Overview
+
+This package allows ASP.NET Framework compatible applications to use Aserto as the Authorization provider.
+
+## Installation
+
+[Aserto.Middleware](https://www.nuget.org/packages/Aserto.Middleware/) is provided as a NuGet package.
+
+It can be installed:
+
+- Using Package Manager:
+
+```powershell
+Install-Package Aserto.Middleware
+```
+
+- Using .NET CLI
+
+```cmd
+dotnet add package Aserto.Middleware
+```
+
+## Usage
+
+In the [aserto-dotnet repository examples](https://github.com/aserto-dev/aserto-dotnet/tree/aserto_clients/examples) there's a WebAPI example built on .NET Framework v4.8 that showcases how to use the Aserto Middleware for authorization.