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

  • Facebook
  • GitHub
  • Google
  • 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
  2. Implement ILoginHandler
  3. Add some bits to Program.cs
  4. Add provider settings to appsettings.json
  5. Add a login button to your site
  6. Use HTTPS

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 ILoginHandler is and pass it your configuration so it can get settings from appsettings.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();

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:

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:

  • RedirectTemplate and CallbackTemplate: 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: true or false to 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.