ODataAuthorization 1.2.1

OData WebApi Authorization extensions

This library is a fork of the Microsoft.AspNetCore.OData.Authorization library, which is available at:

• https://github.com/OData/WebApiAuthorization

This fork adds support for .NET 6 and ASP.NET Core OData 8. It uses the permissions defined in the capability annotations of the OData model to apply authorization policies to an OData service based on Microsoft.AspNetCore.OData.

It has been renamed to ODataAuthorization to avoid being mistaken as an official Microsoft package.

Usage

In your Startup.cs file:

using Microsoft.AspNetCore.OData.Authorization

public void ConfigureServices(IServiceCollection services)
{
    // odata authorization services
    services.AddOData()
        .AddODataAuthorization(options => {
            // you need to register an authentication scheme/handler
            // This works similar to services.AddAuthentication
            options.ConfigureAuthentication("DefaultAuthScheme").AddScheme(/* ... */)
        });

    service.AddRouting();
}

Sample applications

• ODataAuthorizationSample: Simple API with permission restrictions and OData authorization middleware set up with a custom authentication handler
• CookieAuthenticationSample: Basic API with permissions restrictions and a cookie-based authentication handler

How to specify permission scopes?

By default, the library will try extract permissions from the authenticated user's claims. Specifically, it will look for claims with the key Scope. If your app is storing user scopes differently (e.g. using a different key), you can provider a scope finder delegate that returns a list of scopes from the current user:

services.AddODataAuthorization(options => {
    options.ScopeFinder = (context) => {
        var scopesClaim = context.User?.FindFirst("Permissions");
        return Task.FromResult(scopes.Value.Split(" ").AsEnumerable());
    };

    options.ConfigureAuthentication().AddJWTAuthenticationScheme();
})

For a complete working example, check the sample application.

How permissions are applied

On each request, the library extracts from the model the permissions restrictions that should apply to the route being accessed and creates an authorization policy based on those permissions. Deeper down the request pipeline, the AspNetCore filter-based authorization system will call the OData authorization handler to verify whether the current user's permissions match the ones required by the policy.

Note: If there are not permission restrictions defined for an some target (entity set/singleton/operation) in the model, then endpoints to that target will be authorized by default regardless of the user's permissions.

Example permission scopes

For the following examples, let's assume that we are working with an OData model that has the following scopes defined:

CRUD operations on entity sets and singleton

For CRUD operations on entity sets and singleton, the permissions of the corresponding insert/update/delete/read restrictions are applied.

Note, in the case of Customers(1), permissions will be extracted from two places if available. Permissions will be extracted from both ReadRestrictions as well as the ReadByKeyRestrictions property of the ReadRestrictions. If the user has any of the permissions defined in either the ReadRestrictions or ReadByKeyRestrictions, then access will be granted.

For example, if the model defines permission scopes Customers.Read in the ReadRestrictions, and Customers.ReadByKey in the ReadByKeyRestrictions, then access to the GET Customers(1) endpoint will be granted to uers with either the Customers.Read or Customers.ReadByKey permissions.

Function and Action calls

The OperationRestricitons of the function or action are applied. For function and action imports, the OperationRestrictions of the underlying function/action are applied.

Note: If functions are overloaded, the operation restrictions of the specific overload being called will apply.

Operations on properties

The ReadRestrictions or UpdateRestrictions of the entity or singleton whose property are being accessed are applied.

Operations on navigation property links

These apply the ReadRestrictions and UpdateRestrictions of the entity/singleton that contains the navigation property where the link is read/added/removed/modified.

Navigation properties

If the endpoint accesses a navigation properties and nested paths in general, the authorization middleware will check whether the user has permissions to access each segment of the path.

Given the endpoint GET Customers(1)/Orders, the middleware will check whether the user has read access to Customers(1) and then read access to Orders. The permissions that are checked for reading Customers(1) are extracted from the ReadRestrictions (including ReadByKeyRestrictions) of the Customers entity set. The permissions checked for Orders are extracted from both the ReadRestrictions of Orders and the ReadRestrictions of the NavigationRestrictions of Customers that apply to the Orders property (NS.EntityContainer.Customers/{key}/Orders path).

Assuming the model defines the scopes Customers.Read, Customers.ReadByKey, CustomersOrders.Read and Orders.Read, the required scopes to read the endpoint would be:

(Customers.Read OR Customers.ReadByKey) AND (CustomerOrders.Read OR Orders.Read)

Note that a POST, PUT, PATCH or DELETE access to a navigation property is considered an update access to the entity that the navigation property belongs to.

Limitations

• Only supports AspNetCore APIs using endpoing routing, i.e. AspNetCore 3.1
• Does not support RestrictedProperties
• Permissions are extracted from the model on each request, no caching is performed. It's not clear whether it's guaranteed that the model will not change after startup.