How Noggin Auth works

Noggin Auth uses the OAuth 2.0 authorization code flow. Your site never sees the user's password. The provider checks who they are, then gives your site a one-time code that it swaps for the user's details. The diagram shows one login, using GitHub as the example provider.

Noggin Auth login flow A sequence diagram between the browser, your site and the login provider. The numbered steps are described in the list below the diagram. Browser Your site with Noggin Auth Login provider 1. GET /auth/github (login link) GenerateStartRequestUrl new secret saved in session 2. Redirect to provider (state) 3. Authorise URL: client_id, redirect_uri, state User logs in and approves 4. Redirect to callback: code, state 5. GET /auth/github/callback AuthenticateUser state matches session? then get the code 6. Code + client secret RetrieveAccessToken 7. Access token 8. Get user (access token) RetrieveUserInformationAsync 9. User details ILoginHandler SuccessfulLoginFrom 10. Your response Redirect through the browser Direct from your site to the provider

Step by step

  1. The user clicks a login link made by the <auth-link> tag helper. It points at your site's redirect route, e.g. /auth/github.
  2. NogginNetCoreAuthController.RedirectToProvider calls Provider.GenerateStartRequestUrl. This creates a random secret (32 bytes) and the provider's authorise URL, with the secret as its state. The controller saves the secret in the user's session and redirects the browser to the provider.
  3. The browser goes to the provider with your app's public client_id, the redirect_uri to come back to, and the state.
  4. The user logs in to the provider (if they aren't already) and agrees to share their details. The provider redirects the browser to your callback URL with a one-time code and the same state.
  5. NogginNetCoreAuthController.ProviderCallback reads the secret from the session and removes it, so it can only be used once. It calls Provider.AuthenticateUser, which checks the returned state matches the secret, then reads the code.
  6. Your site sends the code and your app's client secret directly to the provider (RetrieveAccessToken).
  7. The provider returns an access token.
  8. Your site uses the token to ask the provider's API for the user's details (RetrieveUserInformationAsync).
  9. The provider returns them, and Noggin Auth puts them in a UserInformation object.
  10. Noggin Auth calls your ILoginHandler.SuccessfulLoginFrom. You log the user in however you like, and return a response, usually a redirect.

Keeping the login secure

  • The state stops login CSRF. Without it, an attacker could start a login with their own account and trick someone else's browser into finishing it, logging that person in as the attacker, or linking the attacker's account to theirs. Noggin Auth only accepts a callback if its state matches the secret in that browser's session. The comparison is constant-time, and the secret is removed after one use.
  • Secrets stay on your server. The browser only ever carries the public client_id, the state and the one-time code. The client secret and access token are only sent between your site and the provider (the solid lines in the diagram).
  • The code is useless on its own. It can only be swapped for a token together with your client secret, and only once.
  • Every provider does the same checks. The steps are run by the Provider base class. Each provider only supplies its own URLs and API calls, so none of them can skip the state check.

When a login fails

If anything goes wrong after the user comes back, Noggin Auth calls your ILoginHandler.FailedLoginFrom instead, with an AuthenticationFailInformation that has a Reason and, usually, the Exception. This happens when:

  • the state is missing or doesn't match, for example the session expired or the login wasn't started in this browser
  • the provider sent back an error instead of a code, for example the user cancelled
  • a call to the provider's token or user API failed
  • the provider didn't return a user ID

Configuration problems, like a provider with no API keys, aren't login failures. They throw a NogginNetCoreConfigException so you notice them straight away.

This sample site logs the reason and shows the user a friendly message.

Where to find it in the code

Code What it does
AuthLinkTagHelper Renders the login links
NogginNetCoreAuthController Handles the redirect and callback routes, and keeps the secret in session
Provider Runs the login steps for every provider, including the state check
FacebookProvider, GitHubProvider, GoogleProvider, MicrosoftProvider Each provider's authorise URL, token request and user API call
ILoginHandler Yours: decides what a successful or failed login means for your site (link is to the sample's)