Unopinionated
- Easy to add to an existing application
- We don't care how you store your users
- No dependency on ASP.NET Core Identity or a database
- More power, means a little bit more work to set up, but still pretty straight forward
Social login providers
- GitHub
- Microsoft
How to set up
For an example of Noggin Auth in action, the source code for this site is available on GitHub.
The important steps are:
1) Install the NuGet package
dotnet add package Noggin.NetCoreAuth
2) Implement ILoginHandler
This is the step that requires most thought and the one that gives you the most power and freedom. Noggin.NetCoreAuth.Providers.ILoginHandler has two methods. One is called if the user successfully authenticates with their chosen social login provider, the other is called if they fail. We send you the information we've been able to glean about them from the provider, but you need to log them in (or not) to your site and save anything you need to.
Once you're done you can return a view or redirect the user to a page of your choice.
Task<IActionResult> SuccessfulLoginFrom(string provider, UserInformation user, HttpContext httpContext); Task<IActionResult> FailedLoginFrom(string provider, AuthenticationFailInformation failInfo, HttpContext httpContext);
See SampleLoginHandler in the sample site for an example of one. The important part is that we don't have any opinion on how to store your user, or even if you need to. We just tell you who they are.
3) Add some bits to Program.cs
- Register Noggin Auth, tell it what type your implementation of
ILoginHandleris and pass it your configuration so it can get settings fromappsettings.json. - Add session. Noggin Auth uses it to remember details between sending the user to the login provider and the provider sending them back.
- Register the authentication routes. These can be changed in appsettings.
using Noggin.NetCoreAuth.Config;
var builder = WebApplication.CreateBuilder(args);
// Point Noggin Auth at your login handler
builder.Services.AddNogginNetCoreAuth<YourLoginHandler>(builder.Configuration);
// Noggin Auth requires session to persist details between the first and second call to login providers
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromMinutes(25);
options.Cookie.HttpOnly = true;
options.Cookie.Name = ".What.ever.you.want.to.call.your.cookie";
});
builder.Services.AddControllersWithViews();
// ...
var app = builder.Build();
app.UseRouting();
app.UseSession();
// Order here is important (authorization must be after authentication as it needs an authenticated user to check)
app.UseAuthentication();
app.UseAuthorization();
app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
// Register the Noggin Auth login and callback routes
app.MapNogginNetAuthRoutes(app.Services);
app.Run();
using Noggin.NetCoreAuth.Config;
public void ConfigureServices(IServiceCollection services)
{
// Point Noggin Auth at your login handler
services.AddNogginNetCoreAuth<YourLoginHandler>(Configuration);
// Noggin Auth requires session to persist details between the first and second call to login providers
services.AddDistributedMemoryCache();
services.AddSession(options =>
{
options.IdleTimeout = TimeSpan.FromMinutes(25);
options.Cookie.HttpOnly = true;
options.Cookie.Name = ".What.ever.you.want.to.call.your.cookie";
});
services.AddControllersWithViews();
// ...
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// ...
app.UseRouting();
app.UseSession();
// Order here is important (authorization must be after authentication as it needs an authenticated user to check)
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
// Register the Noggin Auth login and callback routes
endpoints.MapNogginNetAuthRoutes(app.ApplicationServices);
});
}
4) Add provider settings to appsettings.json
This is where you say which providers you want to use and fill in your developer credentials. You need to register an app with each provider you want to use:
- Facebook Developer Site
- GitHub Developer Settings
- Google API Credentials
- Microsoft Entra App Registrations
When you register, give the provider your callback URL. With the settings below, the GitHub one would be https://your-site/auth/github/callback.
Add a NogginNetAuth section to your appsettings like this:
"NogginNetAuth": {
"Providers": [
{
"Name": "Facebook",
"Api": {
"PublicKey": "...",
"PrivateKey": "..."
}
},
{
"Name": "GitHub",
"Api": {
"PublicKey": "...",
"PrivateKey": "..."
}
},
{
"Name": "Google",
"Api": {
"PublicKey": "...",
"PrivateKey": "..."
}
},
{
"Name": "Microsoft",
"Api": {
"PublicKey": "...",
"PrivateKey": "..."
}
}
],
"DefaultRedirectTemplate": "auth/{provider}",
"DefaultCallbackTemplate": "auth/{provider}/callback"
}
PublicKey is the client ID (or app ID) and PrivateKey is the client secret. Don't commit your secrets. Keep them in user secrets when developing and in environment variables or a secret store when deployed.
If you leave out the default templates, the routes are auth/redirect/{provider} and auth/callback/{provider}. Each provider can also have these optional settings:
RedirectTemplateandCallbackTemplate: override the default routes for this provider.CallbackUrlHost: the host (and port) to use in the callback URL, e.g."coreauth.nogginbox.co.uk". Use this if your site is behind a reverse proxy, where the host can't be detected.CallbackIsHttps:trueorfalseto always use HTTPS or HTTP in the callback URL. If not set, it's the same as the request.
5) Add a login button to your site
So you can use the Noggin Auth tag helpers, add the following to Views/_ViewImports.cshtml:
@addTagHelper *, Noggin.NetCoreAuth
Once this is included all you need to do is add:
<auth-link provider="github">GitHub</auth-link>
This will render an <a> tag with a link to the correct place to kick off authentication. You can set provider to be any of your configured providers. Any other attributes, such as class, are added to the link.
6) Use HTTPS
Most providers will only send users back to an HTTPS callback URL (localhost is usually allowed for development), and if your users log in to your site you should be using HTTPS anyway. If your site is behind a reverse proxy that handles HTTPS, set CallbackIsHttps and CallbackUrlHost so the callback URL is right.