search

oidcproxydotnet / OidcProxy.Net

An extendible framework for .NET to implement the BFF Security Pattern (a.k.a. Token Handler Pattern) in Single Page Applications
GNU Lesser General Public License v3.0
104 stars 19 forks source link
aspnetcore authentication framework oauth2 openid spa

readme

OidcProxy.Net

Nuget Version Twitter

Table of contents

  1. What is OidcProxy.Net?
  2. Getting started with OidcProxy.Net
  3. DIY: Setting up a proxy from scratch
  4. OidcProxy.Net <3 Docker
  5. OidcProxy.Net <3 Kubernetes
  6. Features
  7. Why we built it

What is OidcProxy.Net?

The OidcProxy is an identity-aware reverse proxy. It is a framework that's designed to be used with SPA-based web applications. It authenticates users and it manages their sessions. It is designed to enhance security by keeping the access_token and the refresh_token hidden from the browser while still allowing the proxy itself to handle and use these tokens. It includes them in downstream requests. This approach helps mitigate potential security risks associated with token exposure.

OidcProxy.Net in a nutshell

Token Visibility and Security Measures:

Token Handling by OidcProxy:

Authorization Code with PKCE Confidential Client Grant:

Getting started with OidcProxy.Net

To get started, configure your identity provider. Create a Client that uses the Authorization Code grant with PKCE. It must provide refresh tokens too. This client will have a client_id and a client_secret. Use those to scaffold a boilerplate project:

# Download and install the template pack first
dotnet new install OidcProxy.Net.Templates

# Scaffold the proxy
dotnet new OidcProxy.Net --backend "https://api.myapp.com"
    --idp "https://idp.myapp.com"
    --clientId xyz
    --clientSecret abc

# Run it
dotnet run

Check out our demos too:

Setting up a proxy from scratch

dotnet new web
dotnet add package OidcProxy.Net.OpenIdConnect

Program.cs:

using OidcProxy.Net.ModuleInitializers;
using OidcProxy.Net.OpenIdConnect;

var builder = WebApplication.CreateBuilder(args);

var config = builder.Configuration
    .GetSection("OidcProxy")
    .Get<OidcProxyConfig>();

builder.Services.AddOidcProxy(config);

// Or, in case of an identity provider that uses Json Web Encryption:
// var key = new SymmetricSecurityKey(
//     Convert.FromBase64String("DRjd/GnduI3Efzen9V9BvbNUfc/VKgXltV7Kbk9sMkY=")
// );
// 
// builder.Services.AddOidcProxy(config, o => o.UseEncryptionKey(new SymmetricKey(key)));

var app = builder.Build();

app.UseOidcProxy();

app.Run();

appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "OidcProxy": {
    "LandingPage": "/hello",
    "Oidc": {
      "ClientId": "clientid",
      "ClientSecret": "secret",
      "Authority": "https://login.yoursite.com/"
    },
    "ReverseProxy": {
      "Routes": {
        "api": {
          "ClusterId": "api",
          "Match": {
            "Path": "/api/{*any}"
          }
        }
      },
      "Clusters": {
        "api": {
          "Destinations": {
            "api/node1": {
              "Address": "http://localhost:8080/"
            }
          }
        }
      }
    }
  }
}

OidcProxy.Net <3 Docker

OidcProxy.Net was developed to be used in cloud environments. This is why it has mainly been designed to work well in containerised environments.

OidcProxy.Net <3 Kubernetes

OidcProxy.Net was designed to work well in container platforms. It's been designed to work well when scaled both horizontally as vertically. To scale the proxy vertically, use Redis as a back-bone.

Features

OidcClient.Net has the following features:

How it works

The OidcProxy does not just forward traffic to down-stream services, it adds the Authentication header to the forwarded requests too. This is illustrated in the following diagram:

The user also uses the proxy to initiate the authentication procedure. That's done by navigating to a special endpoint: the /.auth/login endpoint.

This process is visualised in the following diagram:

Why we built it

The development of our product was driven by our clients’ need for a straightforward authentication gateway. Existing market options introduced complexities in terms of pricing and licensing, or proved to be overly intricate for beginners to comprehend and utilize effectively.

Consequently, organizations are forced to make a trade-off between maintainability and security. In today’s automated society, this compromise is unacceptable.

Hence, our mission is to offer an affordable, developer-friendly, secure, identity-aware BFF Framework that can be implemented by anyone.

Feedback

We need your feedback. Like any other software product, it is impossible to be successful without user-feedback. Please take a moment of your time to fill out this form: https://forms.gle/a6uuwFSLSAod52MH9