- What is OidcProxy.Net?
- Getting started with OidcProxy.Net
- DIY: Setting up a proxy from scratch
- OidcProxy.Net <3 Docker
- OidcProxy.Net <3 Kubernetes
- Features
- Why we built it
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.
- The OidcProxy serves as an identity-aware proxy.
- Authentication initiates a session on the OidcProxy.
- End-users authenticate through an Open ID Connect Identity Provider.
- The requests forwarded by the OidcProxy include
access_tokens
in the requests to backend services. - The OidcProxy is a Nuget package that can be included in .net 8 projects.
- The OidcProxy is designed to be a confidential client. This makes it possible to require a
client_secret
to obtain tokens which means it is impossible for unknown computers to obtain tokens in any way. - The
access_token
,id_token
, andrefresh_token
are not visible to the browser. This enhances security by preventing these sensitive tokens from being exposed to potential attackers via the browser.
- While the tokens are not visible to the browser, the OidcProxy itself does have access to these tokens.
- The OidcProxy adds an
Authorization=Bearer [ACCESS_TOKEN]
header to each downstream request.
- The OidcProxy enables the implementation of the OAuth2 Authorization Code Grant with Confidential Client Grant.
- This reduces the risk of impersonation.
- This reduces the attack surface because, in this scenario, an attacker who does not have access to the webserver cannot be issued any tokens.
- /.auth/me endpoint responds with
401
instead of404
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:
- Demo: Setting up OidcProxy.Net as an identity-aware reverse proxy, using Docker, Kubernetes, Auth0, with Angular and one .NET API.
- Demo: Setting up OidcProxy.Net as an identity-aware reverse proxy, using IdentityServer, Angular, and one .NET API
- Demo: Setting up OidcProxy.Net as an identity-aware reverse proxy, using Azure EntraId, Angular, and one .NET API
- Demo: Setting up OidcProxy.Net as a host for an Angular SPA and as a reverse proxy for one ASP.NET Api with Auth0 as Identity Provider
- Demo: Setting up OidcProxy.Net as a host for an Angular SPA and as a reverse proxy for one ASP.NET Api with OpenIddict as Identity Provider (WIP)
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.UseJweKey(new EncryptionKey(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 was developed to be used in cloud environments. This is why it has mainly been designed to work well in containerised environments.
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.
OidcClient.Net has the following features:
- By requiring minimal configuration, OidcProxy.Net enables authentication through the following Identity Providers:
- Leveraging YARP, OidcProxy.Net allows for sophisticated routing configurations, enabling users to define rules for directing incoming requests to the appropriate backend services.
- The proxy can run in single instance mode or in disributed mode. In distributed mode, the proxy uses Redis as a backbone.
- Authentication is integrated into the ASP.NET Core pipeline. This allows for the usage of the
Authorization
attribute, Policies, and many other ASP.NET Identity feature - The proxy has been built following SOLID principles. This allows developers to extend the basic functionality to tailor it to their needs.
- OidcProxy.Net can easily included in
- .NET Web Projects
- .NET Web API Projects
- .NET Angular projects
- .NET React projects
- The proxy is designed for Docker, but native execution is also supported.
- Authenticate users with JWT and JWE.
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:
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.
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