Table of Contents

Migrating from Version 2.x to 3.0

Auth0-OIDC-Client-NET has been updated to move forward with the latest in best practices, browser compatibility and the latest runtimes.

Should I migrate to v3?

Everyone should migrate to v3. All previous versions are deprecated.

For some developers, this upgrade will not be breaking. If you do not see compiler errors when taking a dependency on v3 then you should skip to the section Other Considerations.

Breaking Changes

There are a number of potential breaking changes in this release depending on how you use the library and what .NET SDK you use.

Minimum Runtime

v3 of this library targets only .NET Standard 2.0 and drops support for .NET Standard 1.4 and .NET Framework 4.5.2.

This only affects WPF, WinForms and UWP. Android and iOS are not affected. If you get compiler errors trying to upgrade then you will need to upgrade the SDK target of your application as follows:

  • WPF to .NET Framework 4.6.2
  • WinForms to .NET Framework 4.6.2
  • UWP to uap10.0.16299 (Windows 10 Fall Creators Update)

IAuth0Client Interface

If you are implementing the IAuth0Client interface you will need to reflect the latest changes to the signature. Each Async method now takes an optional CancellationToken. Also, method overloads for LogoutAsync and RefreshTokenAsync were combined.

If you use the Auth0Client class directly you will not need to make any changes. The compiler will be able to utilize the defaults provided for the new parameters.

PlatformWebView Class Removal

This class is now removed across all platforms. To use default Browser behavior simply leave the Browser property of Auth0ClientOptions uninitialized.

Other Considerations

Android

It is now recommended you pass this as the second argument to the Auth0Client constructor when creating it from your Activity. This allows Auth0Client to automatically read the IntentFilter on your Activity and determine the correct callback uri to use. Additionally it allows the ChromeCustomTab and SystemBrowser integrations to avoid needing to request the NewTask ActivityFlag.

Windows

The Microsoft Edge browser is now the default for WPF, WinForms and UWP applications. Where it is not available it will fall back to Internet Explorer. This resolves some problems with some IDPs where large warnings about Interner Explorer not being supported appear (such as GitHub.com).

If you need to use Internet Explorer for some reason create a new instance of WebBrowserBrowser and assign it to the Browser property of your Auth0ClientOptions, e.g.

var options = new Auth0ClientOptions {
  Browser = new WebBrowserBrowser()
}

Windows UWP and Windows Authentication

If you wish to support Windows Authentication it is necessary to use the WebAuthenticationBrokerBrowser and pass true to the constructor, e.g.

var options = new Auth0ClientOptions {
  Browser = new WebAuthenticationBrokerBrowser(true)
}

Scopes

Request scopes now includes email by default. Additionally while you can change the Scope property on the Auth0ClientOptions all endpoints will always be called with openid present in order to ensure OpenID Connect compliance.

ClientSecret Deprecation

The ClientSecret property of Auth0ClientOptions has been deprecated and will be removed in a future release. It is highly inadvisable to use Client Secrets inside non-confidential clients. The purpose of this library is to target desktop and mobile applications which by their nature should be considered non-confidential.