OAuth2 1.1.0

OAuth2

OAuth2 is a library for user authentication using third-party services (OAuth/OAuth2 protocol) such as Google, Facebook and so on.

Standard Flow

1. Generate a login URL and render a page with it
2. Define a callback endpoint that the third-party service redirects to after successful authentication
3. Retrieve user info on callback from the third-party service

Installation

Install the OAuth2 NuGet package:

dotnet add package OAuth2

Usage (ASP.NET Core Minimal API)

Install OAuth2 in an ASP.NET Core web project. Configure Google:ClientId and Google:ClientSecret using user secrets or a secret store, and register https://localhost:5001/auth/google/callback with Google. Run the app on https://localhost:5001 with a trusted development certificate.

This example shows the basic flow only. Before using it for authentication, generate an unpredictable, single-use state, bind it to the initiating browser session, pass it to GetLoginLinkUriAsync(state), and validate it before exchanging the code. The library does not validate state, manage sessions, or validate ID tokens; use an established authentication handler or correlation store for those responsibilities. See Google's authorization-code flow.

using System.Collections.Specialized;
using OAuth2.Client.Impl;
using OAuth2.Configuration;
using OAuth2.Infrastructure;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

GoogleClient CreateGoogleClient() => new(new RequestFactory(), new ClientConfiguration
{
    ClientId = app.Configuration["Google:ClientId"]!,
    ClientSecret = app.Configuration["Google:ClientSecret"]!,
    RedirectUri = "https://localhost:5001/auth/google/callback",
    Scope = "openid profile email"
});

app.MapGet("/auth/google", async () =>
{
    var loginUri = await CreateGoogleClient().GetLoginLinkUriAsync();
    return Results.Redirect(loginUri);
});

app.MapGet("/auth/google/callback", async (HttpContext context) =>
{
    var code = context.Request.Query["code"].ToString();
    if (string.IsNullOrEmpty(code))
        return Results.BadRequest("Missing authorization code.");

    var userInfo = await CreateGoogleClient().GetUserInfoAsync(
        new NameValueCollection { { "code", code } });
    return Results.Ok(userInfo);
});

app.Run();

Open /auth/google to start. Create a client per authentication flow; do not share an instance concurrently. Use ProviderName and Id to look up a linked account, and follow the email-verification guidance before trusting an email address.

HTTP transport and timeouts

RequestFactory shares its HTTP transport across authentication flows. Each call to CreateClient returns a separate RestClient; headers, authenticators, and timeouts stay on that client. Disposing it leaves the shared transport available. On Windows, Linux, and macOS with .NET 10 or .NET 11, pooled connections expire after two minutes so new connections can refresh DNS. Mobile, browser, and netstandard2.0 builds retain their platform handler. Outside the browser, handler cookies are disabled so they do not cross authentication flows. RestSharp still handles explicit request cookies and same-origin redirects.

The default transport rejects redirects to another scheme, host, or port before RestSharp can forward an OAuth form body or token-bearing query string. A provider that requires a redirect to another origin must use its documented endpoint directly or an application-owned IRequestFactory with an explicit redirect policy. Browser redirect behavior also depends on the browser's fetch implementation and CORS policy.

Custom IRequestFactory implementations retain ownership of the clients and handlers they supply. Use an application-managed transport for custom DNS, proxy, certificate, or connection-lifetime requirements.

Set RequestOptions.Timeout when constructing RequestFactory to change the response timeout. A request's RestRequest.Timeout takes precedence; otherwise the factory value applies, or RestSharp's 100-second default when neither is set. The shared HttpClient has no separate timeout because RestSharp enforces these limits and caller cancellation. An infinite HTTP transport timeout does not make requests unlimited by default.

Email verification

UserInfo.EmailVerified is nullable: true and false preserve the provider's assertion; null means unknown or not mapped. Verification methods differ between providers. The following clients populate it:

Google, LinkedIn, Salesforce, Uber, and Yahoo accept only JSON booleans for verification; missing, null, or other types become null. GitHub retains its existing typed email parser and primary/verified/first-email selection order. Verification belongs to the selected address, not another address in the response.

Google also maps a string hd to UserInfo.ProviderData["hd"]. Interpret this key only for ProviderName == "Google". It is not a domain inferred from the email address or a universal tenant identifier. Other clients leave ProviderData null; raw responses and tokens are not copied into it.

Look up a previously linked account by ProviderName and UserInfo.Id, not its email address. Email is mutable contact data and can be reassigned; successful OAuth authentication does not guarantee that the provider has verified the mailbox. For Google, UserInfo.Id contains sub, which stays the same when an email address changes. Update the contact email without changing that external-account key.

Use EmailVerified is true when checking the provider's assertion; neither false nor null establishes verification. Even true alone does not authorize linking to an existing local account. Google can retain a verification assertion for an external email address after mailbox ownership changes. Apply an explicit linking policy using Google's email-authority guidance. To restrict Google Workspace access, compare the returned hd claim with your allowed domain; an email suffix or the mere presence of hd is insufficient.

Older UserInfo JSON deserializes with both new properties set to null. Default System.Text.Json serialization adds EmailVerified and ProviderData, including null values. Check consumers that require an exact JSON schema; naming and null-value settings remain under your application's control.

Supported Services

Provider status and documentation checks do not establish that an authenticated login works. Tests cover requests and documented response shapes with synthetic values. Applications still need registered credentials, granted scopes, and any provider approval.

Provider compatibility and upgrades

These clients accept current responses and retain their existing legacy parser cases. Configured scopes are passed through unchanged; the library does not add permissions.

• Asana: requests and reads gid, with a fallback to legacy id. Asana guarantees existing ID values do not change. UserInfo.Id already stores strings, so existing account keys remain the same. The user endpoint requires users:read for scoped applications.
• ExactOnline: authorization uses /api/oauth2/auth; profile requests still use /api/v1/current/Me, now with JSON requested explicitly. The parser reads UserID, FirstName, LastName, Email, and PictureUrl from the OData response. The old parser expected unrelated root fields and did not map this response. Applications that supplied custom profile responses retain that parser path. The built-in client still targets the Netherlands host.
• DigitalOcean: /v1/oauth remains the current OAuth 2.0 route. The client uses info.uuid for the authenticating user, as DigitalOcean's own client does. It does not use team_uuid as the user ID. A legacy root uid still takes precedence when supplied. ProviderName is now correctly set to DigitalOcean. Applications with stored numeric IDs or a null provider name need an explicit account-link check; this library cannot infer a numeric-ID-to-UUID mapping. Do not link those accounts by email alone.
• Uber: profile requests now use /v3/me, with sub mapped to UserInfo.Id and the current name and verification claims mapped. The old parser left Id null. Uber requires application approval and the profile scope for profile fields. Existing applications that linked accounts using another key must establish the new subject through a trusted account-link flow.
• Yahoo: profile requests now use /openid/v1/userinfo; the OAuth 2.0 authorization and token endpoints remain unchanged. Configure Scope = "openid profile email" for names and email. Yahoo's migration guide maps the old guid to sub. The client uses that subject for both UserInfo.Id and UserProfileGUID, including when the token omits deprecated xoauth_yahoo_guid. If both values are supplied, they must match. Missing claims remain unknown, and profile image sizes are preserved.

These provider requirements apply only to applications that use the affected client. They do not block deployments that use other providers. A real sign-in and account-link check is still required before enabling a newly configured provider in production.

Google retains its existing /oauth2/v3/userinfo route. Google's current OIDC discovery advertises https://openidconnect.googleapis.com/v1/userinfo; API path version numbers are distinct from OAuth protocol versions. Exposing the existing email_verified and hd claims does not require an endpoint migration.

Removed providers (Instagram, Xing): These providers' APIs have been retired or shut down. The client classes have been removed.

• Instagram: Basic Display API shut down Dec 4, 2024. There is no consumer OAuth replacement — the remaining Instagram APIs are business/creator-only. Announcement
• Xing: OAuth 1.0a REST API discontinued. dev.xing.com only hosts plugins.

Renamed providers: TwitterClient → XClient (Twitter rebranded to X). The old class name is preserved as an obsolete derived class that produces a compiler error directing users to the new name.

Legacy (Working): WindowsLiveClient — Microsoft officially retired the Live SDK in Nov 2018 but the endpoints continue to function in production. Confirmed working in Exceptionless. For new integrations, use MicrosoftClient (Microsoft Identity Platform v2.0 + Graph). User IDs differ between the two platforms.

Deprecated providers:

• Foursquare: v2 consumer OAuth API deprecated. The replacement Places API v3 uses API keys, not OAuth.
• VSTS (Azure DevOps): Azure DevOps OAuth stopped accepting new app registrations in April 2025 and is scheduled for full retirement in 2026. Use MicrosoftClient with Microsoft Entra ID OAuth instead

Goals

• Simplicity in usage — even a newcomer can call a couple of methods and receive the expected result
• Well-documented, testable, and tested code
• Flexible, transparent, and easily understandable design
• Support for both fine-grained control and simple plug-and-play usage

Dependencies

• RestSharp

Contributors

• Constantin Titarenko (started development, defined library structure, released initial version)
• Blake Niemyjski (helped a lot to maintain the project, currently (since 2015) — top maintainer)
• Andriy Somak (helped with improvements on configuration and extending the list of supported services)
• Sascha Kiefer (simplified extending the library with own provider implementations, added GitHub client)
• Krisztián Pócza (added LinkedIn (OAuth 2) client)
• Jamie Houston (added a Todoist client)
• Sasidhar Kasturi (added Uber, Spotify, Yahoo)
• Jamie Dalton (added Visual Studio Team Services)

Acknowledgements

Many thanks to JetBrains company for providing free OSS licenses for ReSharper and dotCover - these tools allow us to work on this project with pleasure!

Also we glad to have opportunity to use free Teamcity CI server provided by Codebetter.com and JetBrains - many thanks for supporting OSS!

OAuth2 optimization would never be so simple without YourKit .NET profiler! We appreciate kind support of open source projects by YourKit LLC - the creator of innovative and intelligent tools for profiling .NET YourKit .NET Profiler and Java applications YourKit Java Profiler.

License

The MIT License (MIT) Copyright (c) 2012-2013 Constantin Titarenko, Andrew Semack and others

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.