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.