.NET Reference

PropelAuth's .NET integration provides all the building blocks you need to add authentication to your .NET projects. The integration uses .NET's claims-based identity namespace to help you secure your backend.

Installation

dotnet add package PropelAuth

Initialize

AddPropelAuthAsync performs a one-time initialization of the library. It will verify your apiKey is correct and fetch the metadata needed to verify access tokens in GetUser.

In serverless environments, it's beneficial to skip the fetch, in which case you can pass in publicKey instead of having the library fetch it. You can find your verifier key in the Backend Integration page in your PropelAuth dashboard.

using System.Security.Claims;
using PropelAuth;
using PropelAuth.Models;

var builder = WebApplication.CreateBuilder(args);

await builder.Services.AddPropelAuthAsync(new PropelAuthOptions(
    apiKey: "YOUR_API_KEY",
    authUrl: "YOUR_AUTH_URL"
));

Protect API Routes

The PropelAuth .NET library provides a User Class to validate the access token and provide the user's information if it is valid. To get the User Class, use the GetUser() method on the ClaimsPrincipal Class.

If the access token is not valid, the user's properties will be set to null. If that's the case, you can use .NET's Results Class to return a 401 Unauthorized error.

app.MapGet("/", (ClaimsPrincipal claimsPrincipal) =>
{
    var user = claimsPrincipal.GetUser();
    if (user == null)
    {
        return Results.Unauthorized();
    }
    return Results.Ok($"Hello user with ID {user.userId}");
});

Authorization / Organizations

You can also verify which organizations the user is in, and which roles and permissions they have in each organization.

Check Org Membership

Verify that the request was made by a valid user and that the user is a member of the specified organization.

app.MapGet("/api/org/{orgId}", (ClaimsPrincipal claimsPrincipal, string orgId) =>
{
    var user = claimsPrincipal.GetUser();
    if (user == null)
    {
        return Results.Unauthorized();
    }
    var org = user.GetOrg(orgId);
    if (org == null)
    {
        return Results.Forbid();
    }
    return Results.Ok($"You are in {org.orgName}");
});

Check Org Membership and Role

Similar to checking org membership, but will also verify that the user has a specific Role in the organization.

A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member.

app.MapGet("/api/org/{orgId}", (ClaimsPrincipal claimsPrincipal, string orgId) =>
{
    var user = claimsPrincipal.GetUser();
    if (user == null)
    {
        return Results.Unauthorized();
    }
    var org = user.GetOrg(orgId);
    if (org != null && org.IsRole("Admin"))
    {
        return Results.Ok($"You are in {org.orgName}");
    }
    return Results.Forbid();
});

Check Org Membership and Permission

Similar to checking org membership, but will also verify that the user has the specified permission in the organization.

Permissions are arbitrary strings associated with a role. For example, can_view_billing, ProductA::CanCreate, and ReadOnly are all valid permissions. You can create these permissions in the PropelAuth dashboard.

app.MapGet("/api/org/{orgId}", (ClaimsPrincipal claimsPrincipal, string orgId) =>
{
    var user = claimsPrincipal.GetUser();
    if (user == null)
    {
        return Results.Unauthorized();
    }
    var org = user.GetOrg(orgId);
    if (org != null && org.HasPermission("can_view_billing"))
    {
        return Results.Ok($"You are allowed to view billing information for org {org.orgName}");
    }
    return Results.Forbid();
});

User Class

The User Class contains information about the user that made the request. It also contains additional methods such as GetOrgs() and HasPermission(). You must first retrieve the ClaimsPrincipal Class and then convert it to a User Class by doing the following:

app.MapGet("/", (ClaimsPrincipal claimsPrincipal) =>
{
    var user = claimsPrincipal.GetUser();
});

OrgMemberInfo Class

The OrgMemberInfo Class contains information about the user's membership in an organization.