Add quickstart for MAUI

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.
+:::
+
+
+<!-- markdownlint-disable MD002 MD041 -->
+
+<%= 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
+  <Applications>
+    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="$targetentrypoint$">
+      <Extensions>
+        <uap:Extension Category="windows.protocol">
+          <uap:Protocol Name="myapp"/>
+        </uap:Extension>
+      </Extensions>
+    </Application>
+  </Applications>
+  ```
+- 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;
+}
+```

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

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<string, string>();
+        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 = "";
+    }
+}
+```

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: [email protected]
+  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"