Webový ověřovací program

Článek
05/14/2024

Tento článek popisuje, jak můžete rozhraní používat v rozhraní .NET Multi-Platform App UI (.NET MAUI IWebAuthenticator ). Toto rozhraní umožňuje spustit toky ověřování založené na prohlížeči, které naslouchají zpětnému volání na konkrétní adresu URL zaregistrovanou v aplikaci.

Výchozí implementace IWebAuthenticator rozhraní je k dispozici prostřednictvím WebAuthenticator.Default vlastnosti. Rozhraní IWebAuthenticator i WebAuthenticator třída jsou obsaženy v Microsoft.Maui.Authentication oboru názvů.

Přehled

Mnoho aplikací vyžaduje přidání ověřování uživatelů, což často znamená, že uživatelům umožníte přihlásit se ke svému stávajícímu účtu Microsoft, Facebook, Google nebo Apple Sign In.

Tip

Microsoft Authentication Library (MSAL) poskytuje vynikající řešení pro přidání ověřování do vaší aplikace.

Pokud vás zajímá použití vlastní webové služby k ověřování, je možné použít WebAuthenticator k implementaci funkcí na straně klienta.

Proč používat back-end serveru

Mnoho zprostředkovatelů ověřování se přesunulo jenom na nabídku explicitních nebo dvounohých toků ověřování, aby se zajistilo lepší zabezpečení. To znamená, že k dokončení ověřovacího toku budete potřebovat tajný klíč klienta od zprostředkovatele. Mobilní aplikace bohužel nejsou skvělým místem pro ukládání tajných kódů a čehokoli uloženého v kódu, binárních souborech mobilní aplikace nebo jinak, je považováno za nezabezpečené.

Osvědčeným postupem je použít webový back-end jako střední vrstvu mezi mobilní aplikací a poskytovatelem ověřování.

Důležité

Důrazně doporučujeme používat starší knihovny ověřování jen pro mobilní zařízení a vzory, které v toku ověřování nevyužívají webový back-end, protože jejich vlastní nedostatek zabezpečení pro ukládání tajných kódů klientů.

Začínáme

Pro přístup k funkcím WebAuthenticator se vyžaduje následující nastavení specifické pro platformu.

Android vyžaduje nastavení filtru záměru pro zpracování identifikátoru URI zpětného volání. Toho se dosahuje děděním z WebAuthenticatorCallbackActivity třídy:

using Android.App;
using Android.Content.PM;

namespace YourNameSpace;

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Android.Content.Intent.ActionView },
              Categories = new[] { Android.Content.Intent.CategoryDefault, Android.Content.Intent.CategoryBrowsable },
              DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticationCallbackActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "myapp";

}

Pokud je cílová verze androidu vašeho projektu nastavená na Android 11 (R API 30) nebo vyšší, musíte aktualizovat manifest Androidu pomocí dotazů, které používají požadavky na viditelnost balíčku Androidu.

V souboru Platformy/ Android/AndroidManifest.xml přidejte do uzlu následující queries/intent uzlymanifest:

<queries>
  <intent>
    <action android:name="android.support.customtabs.action.CustomTabsService" />
  </intent>
</queries>

Přidejte vzor URI zpětného volání vaší aplikace do souborů Platforms/iOS/Info.plist a Platforms/MacCatalyst/Info.plist :

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>My App</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
    </dict>
</array>

Upozornění

V tuto chvíli WebAuthenticator nefunguje ve Windows. Další informace najdete v tématu Problém GitHubu č. 2702.

Pro WinUI 3 budete muset deklarovat svůj protokol URI zpětného volání v souboru Package.appxmanifest :

<Applications>
    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="MyApp.App">
        <Extensions>
            <uap:Extension Category="windows.protocol">
            <uap:Protocol Name="myapp">
                <uap:DisplayName>My App</uap:DisplayName>
            </uap:Protocol>
            </uap:Extension>
        </Extensions>
    </Application>
</Applications>

Použití webAuthenticatoru

Rozhraní API se skládá hlavně z jedné metody, AuthenticateAsynckterá přebírá dva parametry:

Adresa URL použitá ke spuštění toku webového prohlížeče.
Očekává se, že identifikátor URI toku nakonec zavolá zpět, který je zaregistrovaný ve vaší aplikaci.

Výsledkem je "WebAuthenticatorResult, který zahrnuje všechny parametry dotazu parsované z identifikátoru URI zpětného volání:

try
{
    WebAuthenticatorResult authResult = await WebAuthenticator.Default.AuthenticateAsync(
        new Uri("https://mysite.com/mobileauth/Microsoft"),
        new Uri("myapp://"));

    string accessToken = authResult?.AccessToken;

    // Do something with the token
}
catch (TaskCanceledException e)
{
    // Use stopped auth
}

Rozhraní WebAuthenticator API se postará o spuštění adresy URL v prohlížeči a čekání na přijetí zpětného volání:

Typický tok ověřování webu

Pokud uživatel tok v libovolném okamžiku zruší, dojde k TaskCanceledException vyvolání.

Relace privátního ověřování

iOS 13 zavedl dočasné rozhraní API webového prohlížeče, které vývojářům umožňuje spustit relaci ověřování jako soukromou. Vývojáři tak můžou požádat, aby mezi relacemi ověřování nebyly k dispozici žádné sdílené soubory cookie nebo údaje o procházení a pokaždé se jedná o novou relaci přihlášení. To je k dispozici prostřednictvím parametru WebAuthenticatorOptions předaného metodě AuthenticateAsync :

try
{
    WebAuthenticatorResult authResult = await WebAuthenticator.Default.AuthenticateAsync(
        new WebAuthenticatorOptions()
        {
            Url = new Uri("https://mysite.com/mobileauth/Microsoft"),
            CallbackUrl = new Uri("myapp://"),
            PrefersEphemeralWebBrowserSession = true
        });

    string accessToken = authResult?.AccessToken;

    // Do something with the token
}
catch (TaskCanceledException e)
{
    // Use stopped auth
}

Rozdíly mezi platformami

Tato část popisuje rozdíly specifické pro platformu s rozhraním API pro ověřování webu.

Vlastní karty se používají, kdykoli je k dispozici, jinak se systémový prohlížeč používá jako záložní.

Podle pokynů společnosti Apple, pokud vaše aplikace Apple používá k ověření některou službu pro přihlášení k sociální sadě, musí také nabídnout možnost přihlášení Apple. Pokud chcete do svých aplikací přidat Přihlášení Apple, musíte k aplikaci přidat přihlášení s oprávněním Apple. Tento nárok je definován pomocí com.apple.developer.applesignin klíče typu ArrayString:

<key>com.apple.developer.applesignin</key>
<array>
  <string>Default</string>
</array>

Další informace najdete v tématu Přihlášení pomocí oprávnění Apple na developer.apple.com.

Pro iOS 13 a vyšší volejte metodu AppleSignInAuthenticator.AuthenticateAsync . Používá se nativní rozhraní API pro přihlášení Apple, aby uživatelé získali na těchto zařízeních co nejlepší prostředí. Můžete například napsat sdílený kód pro použití správného rozhraní API za běhu:

var scheme = "..."; // Apple, Microsoft, Google, Facebook, etc.
var authUrlRoot = "https://mysite.com/mobileauth/";
WebAuthenticatorResult result = null;

if (scheme.Equals("Apple")
    && DeviceInfo.Platform == DevicePlatform.iOS
    && DeviceInfo.Version.Major >= 13)
{
    // Use Native Apple Sign In API's
    result = await AppleSignInAuthenticator.AuthenticateAsync();
}
else
{
    // Web Authentication flow
    var authUrl = new Uri($"{authUrlRoot}{scheme}");
    var callbackUrl = new Uri("myapp://");

    result = await WebAuthenticator.Default.AuthenticateAsync(authUrl, callbackUrl);
}

var authToken = string.Empty;

if (result.Properties.TryGetValue("name", out string name) && !string.IsNullOrEmpty(name))
    authToken += $"Name: {name}{Environment.NewLine}";

if (result.Properties.TryGetValue("email", out string email) && !string.IsNullOrEmpty(email))
    authToken += $"Email: {email}{Environment.NewLine}";

// Note that Apple Sign In has an IdToken and not an AccessToken
authToken += result?.AccessToken ?? result?.IdToken;

Tip

U zařízení s iOSem 13 se spustí tok ověřování webu, který se dá použít také k povolení přihlášení Apple na zařízeních s Androidem a Windows. Na simulátoru iOS se můžete přihlásit ke svému účtu iCloud a otestovat přihlášení Apple.

back-end základního serveru ASP.NET

Rozhraní API je možné použít WebAuthenticator s jakoukoli webovou back-endovou službou. Pokud ji chcete použít s ASP.NET základní aplikací, nakonfigurujte webovou aplikaci pomocí následujících kroků:

Nastavte externí poskytovatele sociálního ověřování ve webové aplikaci ASP.NET Core.
Nastavte ve volání .AddAuthentication() výchozí schéma CookieAuthenticationDefaults.AuthenticationScheme ověřování.
Používejte .AddCookie()v Startup.cs.AddAuthentication() hovoru.
Musí být nakonfigurováni .SaveTokens = true;všichni poskytovatelé .

services.AddAuthentication(o =>
    {
        o.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddFacebook(fb =>
    {
        fb.AppId = Configuration["FacebookAppId"];
        fb.AppSecret = Configuration["FacebookAppSecret"];
        fb.SaveTokens = true;
    });

Tip

Pokud chcete zahrnout Přihlášení Apple, můžete použít AspNet.Security.OAuth.Apple balíček NuGet. Můžete zobrazit úplnou ukázku Startup.cs.

Přidání vlastního mobilního kontroleru ověřování

S tokem mobilního ověřování obvykle spustíte tok přímo poskytovateli, který uživatel zvolil. Například kliknutím na tlačítko Microsoft na přihlašovací obrazovce aplikace. Je také důležité vrátit do aplikace relevantní informace na konkrétním identifikátoru URI zpětného volání, aby se ukončil tok ověřování.

K dosažení tohoto cíle použijte vlastní kontroler rozhraní API:

[Route("mobileauth")]
[ApiController]
public class AuthController : ControllerBase
{
    const string callbackScheme = "myapp";

    [HttpGet("{scheme}")] // eg: Microsoft, Facebook, Apple, etc
    public async Task Get([FromRoute]string scheme)
    {
        // 1. Initiate authentication flow with the scheme (provider)
        // 2. When the provider calls back to this URL
        //    a. Parse out the result
        //    b. Build the app callback URL
        //    c. Redirect back to the app
    }
}

Účelem tohoto kontroleru je odvodit schéma (zprostředkovatele), které aplikace požaduje, a spustit tok ověřování u poskytovatele sociálních sítí. Když poskytovatel zavolá zpět do webového back-endu, kontroler parsuje výsledek a přesměruje na identifikátor URI zpětného volání aplikace s parametry.

Někdy můžete chtít vrátit data, jako je například návrat poskytovatele access_token do aplikace, které můžete provést prostřednictvím parametrů dotazu URI zpětného volání. Nebo můžete chtít na serveru vytvořit vlastní identitu a předat do aplikace vlastní token. Co a jak to uděláte, je na vás!

Podívejte se na úplnou ukázku kontroleru.

Poznámka:

Výše uvedený příklad ukazuje, jak vrátit přístupový token z poskytovatele ověřování třetí strany (tj. OAuth). Pokud chcete získat token, který můžete použít k autorizaci webových požadavků na samotný webový back-end, měli byste ve webové aplikaci vytvořit vlastní token a vrátit ho. Přehled ověřování ASP.NET Core obsahuje další informace o pokročilých scénářích ověřování v ASP.NET Core.

Sdílet prostřednictvím