Fga.Net.AspNetCore 0.8.0-alpha

.NET 6.0
This is a prerelease version of Fga.Net.AspNetCore.
dotnet add package Fga.Net.AspNetCore --version 0.8.0-alpha
NuGet\Install-Package Fga.Net.AspNetCore -Version 0.8.0-alpha
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Fga.Net.AspNetCore" Version="0.8.0-alpha" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Fga.Net.AspNetCore --version 0.8.0-alpha
#r "nuget: Fga.Net.AspNetCore, 0.8.0-alpha"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Fga.Net.AspNetCore as a Cake Addin
#addin nuget:?package=Fga.Net.AspNetCore&version=0.8.0-alpha&prerelease

// Install Fga.Net.AspNetCore as a Cake Tool
#tool nuget:?package=Fga.Net.AspNetCore&version=0.8.0-alpha&prerelease

OpenFGA & Auth0 FGA for ASP.NET Core + Worker Services

Nuget (with prereleases) Nuget (with prereleases)

Note: This project is in its early stages and will have breaking changes as FGA matures.

Packages

Fga.Net.DependencyInjection: Provides dependency injection/configuration extensions for OpenFga.Sdk

Fga.Net.AspNetCore: Additionally includes Authorization middleware to support FGA checks as part of a request's lifecycle.

Getting Started

This package is compatible with the OSS OpenFGA as well as the managed Auth0 FGA service.

Please ensure you have a basic understanding of how FGA works before continuing: OpenFGA Docs or Auth0 FGA Docs

ASP.NET Core Setup

This tutorial assumes you have authentication setup within your project, such as JWT bearer authentication via Auth0.

Install Fga.Net.AspNetCore from Nuget before continuing.

Auth0 FGA

Ensure you have a Store ID, Client ID, and Client Secret ready from How to get your API keys.

  1. Add your StoreId, ClientId and ClientSecret to your application configuration, ideally via the dotnet secrets manager.
  2. Add the following code to your ASP.NET Core services configuration:
builder.Services.AddOpenFgaClient(x =>
{
    x.WithAuth0FgaDefaults(builder.Configuration["Auth0Fga:ClientId"], builder.Configuration["Auth0Fga:ClientSecret"]);

    x.StoreId = builder.Configuration["Auth0Fga:StoreId"];
});

builder.Services.AddOpenFgaMiddleware();

The WithAuth0FgaDefaults extension will configure the relevant OpenFGA client settings to work with Auth0 FGA's US environment.

OpenFGA

OpenFGA configuration is very similar to the SDK Setup Guide

  1. Add the FGA ApiScheme, ApiHost & StoreId to your application configuration.
  2. Add the following code to your ASP.NET Core configuration:
builder.Services.AddOpenFgaClient(x =>
{
    x.ApiScheme = builder.Configuration["Fga:ApiScheme"];
    x.ApiHost = builder.Configuration["Fga:ApiHost"];
    x.StoreId = builder.Configuration["Fga:StoreId"];
});

builder.Services.AddOpenFgaMiddleware();

Authorization Policy Setup

We'll need to setup our authorization policy like so:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(FgaAuthorizationDefaults.PolicyKey, 
        p => p
            .RequireAuthenticatedUser()
            .AddFgaRequirement());
});

Built-in Attributes

Fga.Net.AspNetCore ships with a number of attributes that should cover the most common authorization sources for FGA checks:

  • FgaHeaderObjectAttribute - Computes the Object via a value in the requests header
  • FgaPropertyObjectAttribute - Computes the Object via a root-level property on the requests JSON body
  • FgaQueryObjectAttribute - Computes the Object via a value in the query string
  • FgaRouteObjectAttribute - Computes the Object via a value in the routes path

These attributes can be used in both minimal APIs & in your controller(s):

    // Traditional Controllers
    [ApiController]
    [Route("[controller]")]
    [Authorize(FgaAuthorizationDefaults.PolicyKey)]
    public class DocumentController : ControllerBase
    {  
        [HttpGet("view/{documentId}")]
        [FgaRouteObject("read", "document", "documentId")]
        public string GetByConvention(string documentId)
        {
            return documentId;
        }
    }

    // Minimal APIs
    app.MapGet("/viewminimal/{documentId}", (string documentId) => Task.FromResult(documentId))
        .RequireAuthorization(FgaAuthorizationDefaults.PolicyKey)
        .WithMetadata(new FgaRouteObjectAttribute("read", "document", "documentId"));

If you want to use the built-in attributes, you need to configure how the user's identity is resolved from the ClaimsPrincipal. The example below uses the Name, which should be suitable for most people (given the claim is mapped correctly).

builder.Services.AddOpenFgaMiddleware(config =>
{
    config.UserIdentityResolver = principal => principal.Identity!.Name!;
    //If you're using DSL v1.1 it requires the user type to be included
    //config.UserIdentityResolver = principal => $"user:{principal.Identity!.Name!}";
});

Custom Attributes

If your requirements are more bespoke than can be covered by the built-in attributes, then you may want to implement your own. To do this, inherit from either FgaBaseObjectAttribute, which uses the configuration's user resolver, or from FgaAttribute which is the root attribute and permits you to implement a custom user source.

For example, an equivalent to the How To Integrate Within A Framework tutorial would be:

public class ComputedRelationshipAttribute : FgaAttribute
{
    private readonly string _prefix;
    private readonly string _routeValue;
    public EntityAuthorizationAttribute(string prefix, string routeValue)
    {
        _prefix = prefix;
        _routeValue = routeValue;
    }

    public override ValueTask<string> GetUser(HttpContext context) 
        => ValueTask.FromResult(context.User.Identity!.Name!);

    public override ValueTask<string> GetRelation(HttpContext context) 
        => ValueTask.FromResult(context.Request.Method switch 
        {
            "GET" => "viewer",
            "POST" => "writer",
            _ => "owner"
        });

    public override ValueTask<string> GetObject(HttpContext context) 
        => ValueTask.FromResult(FormatObject(_type, context.GetRouteValue(_routeValue)!.ToString()!));
}

If you need to manually perform checks, inject the Auth0FgaApi as required.

An additional pre-made attribute that allows all tuple values to be hardcoded strings ships with the package (FgaStringAttribute). This attribute is useful for testing and debug purposes, but should not be used in a real application.

Worker Service / Generic Host Setup

Fga.Net.DependencyInjection ships with the AddOpenFgaClient service collection extension that handles all required wire-up.

To get started:

  1. Install Fga.Net.DependencyInjection
  2. Add your StoreId, ClientId and ClientSecret Auth0 FGA configuration OR ApiScheme, ApiHost & StoreId OpenFGA configuration to your application configuration, ideally via the dotnet secrets manager.
  3. Register the authorization client:
var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddOpenFgaClient(config =>
        {
            // Auth0 FGA
            config.WithAuth0FgaDefaults(context.Configuration["Auth0Fga:ClientId"], context.Configuration["Auth0Fga:ClientSecret"]);
            config.StoreId = context.Configuration["Auth0Fga:StoreId"];

            // OpenFGA
            config.ApiScheme = context.Configuration["Fga:ApiScheme"];
            config.ApiHost = context.Configuration["Fga:ApiHost"];
            config.StoreId = context.Configuration["Fga:StoreId"];
        });

        services.AddHostedService<MyBackgroundWorker>();
    })
    .Build();

await host.RunAsync();
  1. Request the client in your services:
public class MyBackgroundWorker : BackgroundService
{
    private readonly Auth0FgaApi _authorizationClient;

    public MyBackgroundWorker(Auth0FgaApi authorizationClient)
    {
        _authorizationClient = authorizationClient;
    }

    protected override Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Do work with the client
    }
}

Standalone client setup

See the OpenFGA.Sdk docs

Disclaimer

I am not affiliated with nor represent Auth0 or OpenFGA. All support queries regarding the underlying service should go to the Auth0 Labs Discord.

Product Versions
.NET net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.8.0-alpha 64 1/3/2023
0.7.0-alpha 486 10/1/2022
0.6.0-alpha 69 9/1/2022
0.5.0-alpha 71 6/18/2022
0.4.0-alpha 88 4/17/2022
0.3.0-alpha 87 2/13/2022
0.2.0-alpha 102 12/20/2021
0.1.1-alpha 100 12/20/2021
0.1.0-alpha 91 12/20/2021