diff --git a/articles/quickstart/native/maui/01-login.md b/articles/quickstart/native/maui/01-login.md new file mode 100755 index 0000000000..1035224879 --- /dev/null +++ b/articles/quickstart/native/maui/01-login.md @@ -0,0 +1,159 @@ +--- +title: Add login to your MAUI application +default: true +description: This tutorial demonstrates how to add user login with Auth0 to a .NET MAUI application. +budicon: 448 +topics: + - quickstarts + - native + - xamarin + - dotnet + - android + - ios +github: + path: Sample +contentType: tutorial +useCase: quickstart +--- + +::: note +The MAUI SDK supports Android, iOS, macOS and Windows. For platform specific configuration, continue reading. +::: + + + + +<%= include('../_includes/_getting_started') %> + +<%= include('../../../_includes/_callback_url') %> + +Callback URLs are the URLs that Auth0 invokes after the authentication process. Auth0 routes your application back to this URL and appends additional parameters to it, including an access code which will be exchanged for an ID Token, Access Token, and Refresh Token. + +Since callback URLs can be manipulated, you will need to add your application's URL to your application's *Allowed Callback URLs* for security. This will enable Auth0 to recognize these URLs as valid. If omitted, authentication will not be successful. + +::: note +When following along with this quickstart, configure `myapp://callback` as the *Allowed Callback URLs*. +::: + +<%= include('../../../_includes/_logout_url') %> + +::: note +When following along with this quickstart, configure `myapp://callback` as the *Allowed Logout URLs*. +::: + +## Install the Auth0 SDK + +Auth0 provides a [MAUI](https://www.nuget.org/packages/Auth0.OidcClient.MAUI/) SDK to simplify the process of implementing Auth0 authentication in MAUI applications. + +Use the NuGet Package Manager (Tools -> Library Package Manager -> Package Manager Console) to install the `Auth0.OidcClient.MAUI` package. + +Alternatively, you can use the Nuget Package Manager Console (`Install-Package`) or the `dotnet` CLI (`dotnet add`). + +```ps +Install-Package Auth0.OidcClient.MAUI +``` +``` +dotnet add Auth0.OidcClient.MAUI +``` + +## Platform specific configuration + +In order to use the SDK with Android and Windows, you need some platform specific configuration. + +### Android +Create a new Activity that extends `WebAuthenticatorCallbackActivity`: + +```csharp +[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)] +[IntentFilter(new[] { Intent.ActionView }, + Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable }, + DataScheme = CALLBACK_SCHEME)] +public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity +{ + const string CALLBACK_SCHEME = "myapp"; +} +``` + +The above activity will ensure the application can handle the `myapp://callback` URL when Auth0 redirects back to the Android application after logging in. + +### Windows +To support Windows, the SDK relies on [WinUIEx](https://github.com/dotMorten/WinUIEx), a community-built package to provide a WebAuthenticator that supports Windows. + +To make sure it can properly reactivate your application after being redirected back go Auth0, you need to do two things: + +- Add the corresponding protocol to the `Package.appxmanifest`. In this case, this is set to `myapp`, but you can change this to whatever you like (ensure to update all relevant Auth0 URLs as well). + ```xml + + + + + + + + + + ``` +- Call `WinUIEx.WebAuthenticator.CheckOAuthRedirectionActivation()` in the Windows specific App.xaml.cs file. + ```csharp + public App() + { + if (WinUIEx.WebAuthenticator.CheckOAuthRedirectionActivation()) + return; + + this.InitializeComponent(); + } + ``` + +## Instantiate the Auth0Client + +To integrate Auth0 into your application, instantiate an instance of the `Auth0Client` class, passing an instance of `Auth0ClientOptions` that contains your Auth0 Domain, Client ID and the required Scopes. +Additionally, you also need to configure the `RedirectUri` and `PostLogoutRedirectUri` to ensure Auth0 can redirect back to the application using the URL(s) configured. + +```csharp +using Auth0.OidcClient; + +var client = new Auth0Client(new Auth0ClientOptions +{ + Domain = "${account.namespace}", + ClientId = "${account.namespace}", + RedirectUri = "myapp://callback", + PostLogoutRedirectUri = "myapp://callback", + Scope = "openid profile email" +}); +``` + +By default, the SDK will leverage Chrome Custom Tabs for Android, ASWebAuthenticationSession for iOS and macOS and use your system's default browser on Windows. + +## Add Login to Your Application + +Now that you have configured your Auth0 Application and the Auth0 SDK, you need to set up login for your project. To do this, you will use the SDK’s `LoginAsync()` method to create a login button that redirects users to the Auth0 Universal Login page. + +```csharp +var loginResult = await client.LoginAsync(); +``` + +If there isn't any error, you can access the `User`, `IdentityToken`, `AccessToken` and `RefreshToken` on the `LoginResult` returned from `LoginAsync()`. + +## Add Logout to Your Application + +Users who log in to your project will also need a way to log out. Create a logout button using the SDK’s `LogoutAsync()` method. When users log out, they will be redirected to your Auth0 logout endpoint, which will then immediately redirect them back to the logout URL you set up earlier in this quickstart. + +```csharp +await client.LogoutAsync(); +``` + +## Show User Profile Information + +Now that your users can log in and log out, you will likely want to be able to retrieve the [profile information](https://auth0.com/docs/users/concepts/overview-user-profile) associated with authenticated users. For example, you may want to be able to display a logged-in user’s name or profile picture in your project. + +The Auth0 SDK for MAUI provides user information through the `LoginResult.User` property. + +```csharp +if (loginResult.IsError == false) +{ + var user = loginResult.User; + var name = user.FindFirst(c => c.Type == "name")?.Value; + var email = user.FindFirst(c => c.Type == "email")?.Value; + var picture = user.FindFirst(c => c.Type == "picture")?.Value; +} +``` \ No newline at end of file diff --git a/articles/quickstart/native/maui/download.md b/articles/quickstart/native/maui/download.md new file mode 100644 index 0000000000..65c7470855 --- /dev/null +++ b/articles/quickstart/native/maui/download.md @@ -0,0 +1,22 @@ +To run the sample first set the **Allowed Callback URLs** in the [Application Settings](${manage_url}/#/applications/${account.clientId}/settings): + + ```text +myapp://callback + ``` + +Set the **Allowed Logout URLs** in the [Application Settings](${manage_url}/#/applications/${account.clientId}/settings): + + ```text +myapp://callback + ``` + +Then, to run it **on Windows**: + +1) Open the Auth0MauiApp.sln in [Visual Studio 2022](https://www.visualstudio.com/vs/). +2) Click the **Start** button (the green play button), ensure to select your target device. +You can also start the application using the **Debug | Start Debugging** option from the main menu. + +To run it on **macOS**: + +1) Open the Auth0MauiApp.sln in [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). +2) Click the **Start** button (the play button), ensure to select your target device. You can also start the application using the **Run | Start Debugging** option from the application menu diff --git a/articles/quickstart/native/maui/files/main-page.md b/articles/quickstart/native/maui/files/main-page.md new file mode 100644 index 0000000000..34276d7b6d --- /dev/null +++ b/articles/quickstart/native/maui/files/main-page.md @@ -0,0 +1,69 @@ +--- +name: MainPage.xaml.cs +language: csharp +--- + +```csharp +public partial class MainPage : ContentPage +{ + Auth0Client client = new Auth0Client(new Auth0ClientOptions + { + Domain = "${account.namespace}" + ClientId = "${account.clientId}", + RedirectUri = "myapp://callback", + PostLogoutRedirectUri = "myapp://callback", + Scope = "openid profile email" + }); + + public MainPage() + { + InitializeComponent(); + } + + private async void OnLoginClicked(object sender, EventArgs e) + { + var extraParameters = new Dictionary(); + var audience = ""; // FILL WITH AUDIENCE AS NEEDED + + if (!string.IsNullOrEmpty(audience)) + extraParameters.Add("audience", audience); + + var result = await client.LoginAsync(extraParameters); + + DisplayResult(result); + } + + private async void OnLogoutClicked(object sender, EventArgs e) + { + BrowserResultType browserResult = await client.LogoutAsync(); + + if (browserResult != BrowserResultType.Success) + { + ErrorLabel.Text = browserResult.ToString(); + return; + } + + LogoutBtn.IsVisible = false; + LoginBtn.IsVisible = true; + + HelloLabel.Text = $"Hello, World!"; + ErrorLabel.Text = ""; + } + + private void DisplayResult(LoginResult loginResult) + { + if (loginResult.IsError) + { + ErrorLabel.Text = loginResult.Error; + return; + } + + LogoutBtn.IsVisible = true; + LoginBtn.IsVisible = false; + + + HelloLabel.Text = $"Hello, {loginResult.User.Identity.Name}"; + ErrorLabel.Text = ""; + } +} +``` \ No newline at end of file diff --git a/articles/quickstart/native/maui/index.yml b/articles/quickstart/native/maui/index.yml new file mode 100755 index 0000000000..f0dc62f629 --- /dev/null +++ b/articles/quickstart/native/maui/index.yml @@ -0,0 +1,49 @@ +title: MAUI +# TODO remove 'image' once new QS page is live. Then only use 'logo'. +image: /media/platforms/xamarin.png +logo: dotnet-platform +author: + name: Frederik Prijck + email: frederik.prijck@okta.com + community: false +language: + - C# +framework: + - maui +hybrid: false +topics: + - quickstart +contentType: tutorial +useCase: quickstart +seo_alias: maui +default_article: 01-login +hidden_articles: + - interactive +articles: + - 01-login +show_steps: true +github: + org: auth0-samples + repo: auth0-maui-samples +sdk: + name: auth0-oidc-client-net + url: https://github.com/auth0/auth0-oidc-client-net + logo: dotnet +requirements: + - Visual Studio 2022+ or Visual Studio for Mac + - .NET6+ +next_steps: + - path: 01-login + list: + - text: Configure other identity providers + icon: 345 + href: "/identityproviders" + - text: Enable multifactor authentication + icon: 345 + href: "/multifactor-authentication" + - text: Learn about attack protection + icon: 345 + href: "/attack-protection" + - text: Learn about rules + icon: 345 + href: "/rules" diff --git a/articles/quickstart/native/maui/interactive.md b/articles/quickstart/native/maui/interactive.md new file mode 100644 index 0000000000..288eef6bc9 --- /dev/null +++ b/articles/quickstart/native/maui/interactive.md @@ -0,0 +1,215 @@ +--- +title: Add login to your .NET MAUI application +default: true +description: This tutorial demonstrates how to add user login with Auth0 to a .NET MAUI application. +budicon: 448 +topics: + - quickstarts + - native + - maui + - dotnet + - android + - ios + - windows +github: + path: Sample +contentType: tutorial +useCase: quickstart +interactive: true +files: + - files/main-page +--- + +# Add Login to a MAUI application + +Auth0 allows you to add authentication to almost any application type quickly. This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in any .NET MAUI application using the Auth0 SDKs for [MAUI](https://www.nuget.org/packages/Auth0.OidcClient.MAUI/). + +::: note +The MAUI SDK supports Android, iOS, macOS and Windows. For platform specific configuration, continue reading. +::: + +<%= include('../../_includes/_configure_auth0_interactive', { + callback: 'myapp://callback', + returnTo: 'myapp://callback' +}) %> + +## Install the Auth0 SDK + +Auth0 provides a [MAUI](https://www.nuget.org/packages/Auth0.OidcClient.MAUI/) SDK to simplify the process of implementing Auth0 authentication in MAUI applications. + +Use the NuGet Package Manager (Tools -> Library Package Manager -> Package Manager Console) to install the `Auth0.OidcClient.MAUI` package. + +Alternatively, you can use the Nuget Package Manager Console (`Install-Package`) or the `dotnet` CLI (`dotnet add`). + +```ps +Install-Package Auth0.OidcClient.MAUI +``` +``` +dotnet add Auth0.OidcClient.MAUI +``` + +## Platform specific configuration + +In order to use the SDK with Android and Windows, you need some platform specific configuration. + +### Android +Create a new Activity that extends `WebAuthenticatorCallbackActivity`: + +```csharp +[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)] +[IntentFilter(new[] { Intent.ActionView }, + Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable }, + DataScheme = CALLBACK_SCHEME)] +public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity +{ + const string CALLBACK_SCHEME = "myapp"; +} +``` + +The above activity will ensure the application can handle the `myapp://callback` URL when Auth0 redirects back to the Android application after logging in. + +### Windows +To support Windows, the SDK relies on [WinUIEx](https://github.com/dotMorten/WinUIEx), a community-built package to provide a WebAuthenticator that supports Windows. + +To make sure it can properly reactivate your application after being redirected back go Auth0, you need to do two things: + +- Add the corresponding protocol to the `Package.appxmanifest`. In this case, this is set to `myapp`, but you can change this to whatever you like (ensure to update all relevant Auth0 URLs as well). + ```xml + + + + + + + + + + ``` +- Call `WinUIEx.WebAuthenticator.CheckOAuthRedirectionActivation()` in the Windows specific App.xaml.cs file. + ```csharp + public App() + { + if (WinUIEx.WebAuthenticator.CheckOAuthRedirectionActivation()) + return; + + this.InitializeComponent(); + } + ``` + +## Instantiate the Auth0Client {{{ data-action="code" data-code="MainPage.xaml.cs#3-8" }}} + +To integrate Auth0 into your application, instantiate an instance of the `Auth0Client` class, passing an instance of `Auth0ClientOptions` that contains your Auth0 Domain, Client ID and the required Scopes. +Additionally, you also need to configure the `RedirectUri` and `PostLogoutRedirectUri` to ensure Auth0 can redirect back to the application using the URL(s) configured. + +```csharp +using Auth0.OidcClient; + +var client = new Auth0Client(new Auth0ClientOptions +{ + Domain = "${account.namespace}", + ClientId = "${account.namespace}", + RedirectUri = "myapp://callback", + PostLogoutRedirectUri = "myapp://callback", + Scope = "openid profile email" +}); +``` + +By default, the SDK will leverage Chrome Custom Tabs for Android, ASWebAuthenticationSession for iOS and macOS and use your system's default browser on Windows. + +::::checkpoint + +:::checkpoint-default + +Your `Auth0Client` should now be properly instantiated. Run your application to verify that: +- the `Auth0Client` is instantiated correctly in the `MainPage`. +- your application is not throwing any errors related to Auth0 + +::: + +:::checkpoint-failure +Sorry about that. Here are a couple things to double-check: +* make sure the correct application is selected +* did you save after entering your URLs? +* make sure the domain and client ID are imported correctly + +Still having issues? Check out our [documentation](https://auth0.com/docs) or visit our [community page](https://community.auth0.com) to get more help. + +::: +:::: + +## Add Login to Your Application {{{ data-action="code" data-code="MainPage.xaml.cs#25" }}} + +Now that you have configured your Auth0 Application and the Auth0 SDK, you need to set up login for your project. To do this, you will use the SDK’s `LoginAsync()` method to create a login button that redirects users to the Auth0 Universal Login page. + +```csharp +var loginResult = await client.LoginAsync(); +``` + +If there isn't any error, you can access the `User`, `IdentityToken`, `AccessToken` and `RefreshToken` on the `LoginResult` returned from `LoginAsync()`. + +::::checkpoint + +:::checkpoint-default + +You should now be able to log in or sign up using a username and password. + +Click the login button and verify that: +* your application redirects you to the Auth0 Universal Login page +* you can log in or sign up +* Auth0 redirects you to your application. + +::: + +:::checkpoint-failure +Sorry about that. Here's something to double-check: +* you called `LoginAsync` as expected + +Still having issues? Check out our [documentation](https://auth0.com/docs) or visit our [community page](https://community.auth0.com) to get more help. + +::: +:::: + +## Add Logout to Your Application {{{ data-action="code" data-code="MainPage.xaml.cs#32" }}} + +Users who log in to your project will also need a way to log out. Create a logout button using the SDK’s `LogoutAsync()` method. When users log out, they will be redirected to your Auth0 logout endpoint, which will then immediately redirect them back to the logout URL you set up earlier in this quickstart. + +```csharp +await client.LogoutAsync(); +``` + +::::checkpoint + +:::checkpoint-default + +Run your application and click the logout button, verify that: +* your application redirects you to the address you specified as one of the Allowed Logout URLs in your Application Settings +* you are no longer logged in to your application + +::: + +:::checkpoint-failure +Sorry about that. Here are a couple things to double-check: +* you configured the correct Logout URL +* you called `LogoutAsync` as expected. + +Still having issues? Check out our [documentation](https://auth0.com/docs) or visit our [community page](https://community.auth0.com) to get more help. + +::: + +:::: + +## Show User Profile Information + +Now that your users can log in and log out, you will likely want to be able to retrieve the [profile information](https://auth0.com/docs/users/concepts/overview-user-profile) associated with authenticated users. For example, you may want to be able to display a logged-in user’s name or profile picture in your project. + +The Auth0 SDK for MAUI provides user information through the `LoginResult.User` property. + +```csharp +if (loginResult.IsError == false) +{ + var user = loginResult.User; + var name = user.FindFirst(c => c.Type == "name")?.Value; + var email = user.FindFirst(c => c.Type == "email")?.Value; + var picture = user.FindFirst(c => c.Type == "picture")?.Value; +} +``` \ No newline at end of file