搜尋套件、儲存庫與 APP 分類

flutter_web_auth 封面
套件詳情v0.6.0

flutter_web_auth

用於透過 Web 服務驗證使用者的 Flutter 插件。

AndroidiOSWebmacOS
近 30 天下載
5170
喜歡數
223
Pub 分數
130

安裝套件

flutter pub add flutter_web_auth

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

一個 Flutter 外掛程式,讓使用者能透過安全的內建瀏覽器與網路服務進行驗證。該外掛程式透過開啟網頁檢視器進行登入並安全處理重新導向,簡化 OAuth2 及類似驗證流程。此外掛程式設計用於跨 Android、iOS、Web 與 macOS 平台運作,確保一致的使用者體驗。支援深度連結與回呼處理,非常適合整合 Google、Facebook 或自訂 OAuth2 伺服器等第三方身分提供者。

適用情境

  • OAuth2 認證
  • 使用社交提供者登入
  • 安全的基於Web的登入
  • 與自定義身分伺服器整合
  • 單點登入工作流程

主要特色

  • 跨平台支援
  • 應用內瀏覽器整合
  • 重定向 URL 處理
  • 深度連結支援
  • 安全令牌獲取

適合對象

  • 需要 OAuth2 登入的應用
  • 使用第三方驗證服務的開發人員
  • 針對多個平台的專案
  • 需要安全Web認證的應用程式
  • 建構單點登入功能的團隊

使用建議

  • 需要正確設置重定向 URI
  • 移動設備上可能需要自定義URL方案
  • 依賴於特定平台的瀏覽器行為
  • 需要對令牌進行安全處理
  • 僅限基於Web的認證流程

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

Web Auth for Flutter

A Flutter plugin for authenticating a user with a web service, even if the web service is run by a third party. Most commonly used with OAuth2, but can be used with any web flow that can redirect to a custom scheme.

In the background, this plugin uses ASWebAuthenticationSession on iOS 12+ and macOS 10.15+, SFAuthenticationSession on iOS 11, Chrome Custom Tabs on Android and opens a new window on Web. You can build it with iOS 8+, but it is currently only supported by iOS 11 or higher.

iOS Android
iOS Android
macOS
macOS

Usage

To authenticate against your own custom site:

import 'package:flutter_web_auth/flutter_web_auth.dart';

// Present the dialog to the user
final result = await FlutterWebAuth.authenticate(url: "https://my-custom-app.com/connect", callbackUrlScheme: "my-custom-app");

// Extract token from resulting url
final token = Uri.parse(result).queryParameters['token']

To authenticate the user using Google's OAuth2:

import 'package:flutter_web_auth/flutter_web_auth.dart';

import 'dart:convert' show jsonDecode;
import 'package:http/http.dart' as http;

// App specific variables
final googleClientId = 'XXXXXXXXXXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com';
final callbackUrlScheme = 'com.googleusercontent.apps.XXXXXXXXXXXX-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Construct the url
final url = Uri.https('accounts.google.com', '/o/oauth2/v2/auth', {
  'response_type': 'code',
  'client_id': googleClientId,
  'redirect_uri': '$callbackUrlScheme:/',
  'scope': 'email',
});

// Present the dialog to the user
final result = await FlutterWebAuth.authenticate(url: url.toString(), callbackUrlScheme: callbackUrlScheme);

// Extract code from resulting url
final code = Uri.parse(result).queryParameters['code'];

// Construct an Uri to Google's oauth2 endpoint
final url = Uri.https('www.googleapis.com', 'oauth2/v4/token');

// Use this code to get an access token
final response = await http.post(url, body: {
  'client_id': googleClientId,
  'redirect_uri': '$callbackUrlScheme:/',
  'grant_type': 'authorization_code',
  'code': code,
});

// Get the access token from the response
final accessToken = jsonDecode(response.body)['access_token'] as String;

Note: To use multiple scopes with Google, you need to encode them as a single string, separated by spaces. For example, scope: 'email https://www.googleapis.com/auth/userinfo.profile'. Here is a list of all supported scopes.

Setup

Setup works as for any Flutter plugin, expect the Android and Web caveats outlined below:

Android

In order to capture the callback url, the following activity needs to be added to your AndroidManifest.xml. Be sure to relpace YOUR_CALLBACK_URL_SCHEME_HERE with your actual callback url scheme.

<manifest>
  <application>

    <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
      <intent-filter android:label="flutter_web_auth">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="YOUR_CALLBACK_URL_SCHEME_HERE" />
      </intent-filter>
    </activity>

  </application>
</manifest>
Web

On the Web platform an endpoint needs to be created that captures the callback URL and sends it to the application using the JavaScript postMessage() method. In the ./web folder of the project, create an HTML file with the name e.g. auth.html with content:

<!DOCTYPE html>
<title>Authentication complete</title>
<p>Authentication is complete. If this does not happen automatically, please
close the window.
<script>
  window.opener.postMessage({
    'flutter-web-auth': window.location.href
  }, window.location.origin);
  window.close();
</script>

Redirection URL passed to the authentication service must be the same as the URL on which the application is running (schema, host, port if necessary) and the path must point to created HTML file, /auth.html in this case. The callbackUrlScheme parameter of the authenticate() method does not take into account, so it is possible to use a schema for native platforms in the code.

For the Sign in with Apple in web_message response mode, postMessage from https://appleid.apple.com is also captured, and the authorization object is returned as a URL fragment encoded as a query string (for compatibility with other providers).

Troubleshooting

When you use this package for the first time, there are some problems you may have. These are some of the common solutions

Troubleshooting callbackUrlScheme
  • callbackUrlScheme must be a valid schema string or else this wont work.
  • A valid RFC 3986 URL scheme must consist of "a letter and followed by any combination of letters, digits, plus ("+"), period ("."), or hyphen ("-")."
  • scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
  • This means you can not use underscore "_", space " " or uppercase "ABCDEF...". You can not also start with a number. See RFC3986#page-17
  • examples of VALID callbackUrlScheme are callback-scheme, another.scheme, examplescheme
  • examples of INVALID callbackUrlScheme are callback_scheme,1another.scheme, exampleScheme
Troubleshooting Flutter App
  • You have to tell the FlutterWebAuth.authenticate function what your callbackUrlScheme is.

  • Example if your callbackUrlScheme is valid-callback-scheme, your dart code will look like

    import 'package:flutter_web_auth/flutter_web_auth.dart';
    
    // Present the dialog to the user
    final result = await FlutterWebAuth.authenticate(url: "https://my-custom-app.com/connect", callbackUrlScheme: "valid-callback-scheme");
    
Troubleshooting Android
  • You are required to update your AndroidManifest.xml to include the com.linusu.flutter_web_auth.CallbackActivity activity something like

    <manifest>
      <application>
    
        <!-- add the com.linusu.flutter_web_auth.CallbackActivity activity -->
        <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
          <intent-filter android:label="flutter_web_auth">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="YOUR_CALLBACK_URL_SCHEME_HERE" />
          </intent-filter>
        </activity>
    
      </application>
    </manifest>
    
  • Example of valid AndroidManifest.xml with VALID callbackUrlScheme. in the example below valid-callback-scheme is our callbackUrlScheme

    <manifest>
      <application>
    
        <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
          <intent-filter android:label="flutter_web_auth">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="valid-callback-scheme" />
          </intent-filter>
        </activity>
    
      </application>
    </manifest>
    
  • If you are targeting S+ (version 31 and above) you need to provide an explicit value for android:exported. If you followed earlier installation instructions this was not included. Make sure that you add android:exported="true" to the com.linusu.flutter_web_auth.CallbackActivity activity in your AndroidManifest.xml file.

    - <activity android:name="com.linusu.flutter_web_auth.CallbackActivity">
    + <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" android:exported="true">
    
Troubleshooting OAuth redirects
  • Your OAuth Provider must redirect to the valid callbackUrlScheme + ://. This mean if your callbackUrlScheme is validscheme, your OAuth Provider must redirect to validscheme://
  • Example with php
    <?php
    
    header("Location: validscheme://?data1=value1&data2=value2");
    
Troubleshooting HTML redirects
  • If you are using HTML hyperlinks, it must be a valid callbackUrlScheme + ://. This mean if your callbackUrlScheme is customappname, your html hyperlink should be customappname://

  • example with HTML

    <a href="customappname://?data1=value1&data2=value2">Go Back to App</a>
    
Troubleshooting passing data to app
  • You can pass data back to your app by adding GET query parameters. This means by adding name=value type of data after your callbackUrlScheme + :// + ?

  • example to pass access-token to your app a valid url for that could be

    my-callback-schema://?access-token=jdu9292s
    
  • You can pass multipe data by concatenating with &

    my-callback-schema://?data1=value1&data2=value2
    
  • example to pass access-token and user_id to your app a valid url for that could be

    my-callback-schema://?access-token=jdu9292s&user_id=23
    
  • You can get the data in your app by using Uri.parse(result).queryParameters

    // Present the dialog to the user
    final result = await FlutterWebAuth.authenticate(url: "https://my-custom-app.com/connect", callbackUrlScheme: "valid-callback-scheme");
    // Extract token from resulting url
    String accessToken = Uri.parse(result).queryParameters['access-token'];
    String userId = Uri.parse(result).queryParameters['user_id'];
    
Cannot open keyboard on iOS

This seems to be a bug in ASWebAuthenticationSession, and no work around have been found. Please see issue #120 for more info.

Error on macOS if Chrome is default browser

This seems to be a bug in ASWebAuthenticationSession, and no work around have been found. Please see issue #136 for more info.

所屬分類

原始碼儲存庫

使用此套件的專案