v0.0.1

nodriver-ai · Jul 22, 2021 · 9b95506 · 9b95506
1 parent 7b4dd3d
commit 9b95506
Show file tree

Hide file tree

Showing 9 changed files with 286 additions and 30 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,14 @@
 ## 0.0.1
 
-* TODO: Describe initial release.
+Intial release. Supported feauture:
+    * Platforms:
+        * Android
+        * Web
+    * Functionalities:
+        * B2C user flow support:
+            * Trigger any default or custom policy
+            * Tokens storage
+            * Sign out
+            * (External providers (e.g. Google) not tested!)
+
+
diff --git a/README.md b/README.md
@@ -1,15 +1,140 @@
 # flutter_azure_b2c
 
-A new flutter plugin project.
+A flutter library to handle the Azure B2C authentication protocol.
+This library is based on native implementation of MSAL for each taget platform
+and aims to provide a common interface to easily manage Azure AD B2C authentication
+process for flutter developer.
+
+There is a common interface that permits to handle the authentication and autorization
+process and it is entirely designed to work with the Azure B2C service. For each platform
+is then implemented a B2CProvider that permits to adapt the common interface to the selected
+device.
+
+
+Aim of this library is NOT to replicate the entire MSAL library in flutter and never
+will be. The entire capabilities of MSAL are not exposed. Furthermore, the library is
+not designed to work with any OAuth2 or OpenID provider. It may work or may not but it
+is not guarantieed. 
+
+Actual limitation:
+* Some platform still miss an implementation as there are out of our business scope
+at the moment. Maybe in the next months we will provide an implementation also for
+iOs but if you need it, contribute! ;)
+
+
+## Installation
+
+Add flutter_azure_b2c to your pubspec:
+```yaml
+    dependencies:
+        flutter_azure_b2c: any # or the latest version on Pub
+```
+
+### Android
+
+* Configure your app to use the INTERNET and ACCESS_NETWORK_STATE permission in the manifest file located in <project root>/android/app/src/main/AndroidManifest.xml:
+```xml
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
+    <uses-permission android:name="android.permission.INTERNET"/>
+```
+
+* Add also an intent filter in the manifest file to capture redirect from MSAL service:
+```xml
+    <!--Intent filter to capture System Browser or Authenticator calling back to our app after sign-in-->
+    <activity
+        android:name="com.microsoft.identity.client.BrowserTabActivity">
+        <intent-filter>
+            <action android:name="android.intent.action.VIEW" />
+            <category android:name="android.intent.category.DEFAULT" />
+            <category android:name="android.intent.category.BROWSABLE" />
+            <data android:scheme="msauth"
+                android:host="<YOUR_PACKAGE_NAME>"
+                android:path="<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>" />
+        </intent-filter>
+    </activity>
+```
+For more information see https://github.com/AzureAD/microsoft-authentication-library-for-android.
+
+* Prepare a JSON configuration file for AzureB2C initialization in <project root>/android/app/main/res/raw/ following this template:
+```json
+    {
+        "client_id" : "<application (client) id>",
+        "redirect_uri" : "msauth://<YOUR_PACKAGE_NAME>/<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>",
+        "account_mode" : "<MULTIPLE|SINGLE>",
+        "broker_redirect_uri_registered": false,
+        "authorities": [
+            {
+                "type": "B2C",
+                "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<sign_in_up_policy_name>/",
+                "default": true
+            },
+            {
+                "type": "B2C",
+                "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<other_policy e.g. reset_pass>/"
+            }
+        ],
+        "default_scopes": [
+            "https://<youractivedirectoryname>.onmicrosoft.com/<application (server) id>/<API name>"
+        ]
+    }
+```
+See https://docs.microsoft.com/en-us/azure/active-directory/develop/tutorial-v2-android for information about how to configure your B2C application and generate <YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>.
+
+### Web
+
+* Add CDN dependecy in your index.html file:
+```html
+  <script type="text/javascript" src="https://alcdn.msauth.net/browser/<MSAL_VERSION>/js/msal-browser.min.js"></script>
+```
+Web implementation depends from the package msal_js (for more information see https://pub.dev/packages/msal_js), depending on the version imported follow the package documentation in order to select the correct <MSAL_VERSION>.
+
+For more information about MSAL web see https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser#usage.
+
+
+* Prepare a JSON configuration file for AzureB2C initialization in <project root>/web/asset/ following this template:
+```json
+    {
+        "client_id" : "<application (client) id>",
+        "redirect_uri" : "<your app domain>",
+        "cache_location": "<localStorage|sessionStorage>",
+        "interaction_mode": "<popup|redirect>",
+        "authorities": [
+            {
+                "type": "B2C",
+                "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<sign_in_up_policy_name>/",
+                "default": true
+            },
+            {
+                "type": "B2C",
+                "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<other_policy e.g. reset_pass>/"
+            }
+        ],
+        "default_scopes": [
+            "https://<youractivedirectoryname>.onmicrosoft.com/<application (server) id>/<API name>"
+        ]
+    }
+```
+
+## Run the example
+
+In <root>/example/lib/main.dart there is a simple demonstration app. In order to test your setting you can follow these next steps:
+
+* Configure a B2C app following Microsoft documentation (see https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-overview).
+
+* Prepare a configuration file using previous templates:
+    * Android: 
+        * path: android/app/main/res/raw/
+    * Web:
+        * path: web/assets/
+
+* launch the application:
+    * Android: 
+        * flutter launch
+        * choose an android emulator or device
+    * Web:
+        * flutter launch -d chrome --web-port <port>
+        * Note: choose port number according to the redirect uri registered in the B2C app.
 
-## Getting Started
 
-This project is a starting point for a Flutter
-[plug-in package](https://flutter.dev/developing-packages/),
-a specialized package that includes platform-specific implementation code for
-Android and/or iOS.
 
-For help getting started with Flutter, view our
-[online documentation](https://flutter.dev/docs), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
 
diff --git a/doc/ExampleGettingStarted.md b/doc/ExampleGettingStarted.md
@@ -0,0 +1,66 @@
+# flutter_azure_b2c example
+
+Demonstrates how to use the flutter_azure_b2c plugin.
+
+## Getting Started
+
+* Configure a B2C app following Microsoft documentation.
+* Prepare a configuration file:
+    * Android: 
+        * path: android/app/main/res/raw/
+        * template:
+            ```json
+            {
+                "client_id" : "<application (client) id>",
+
+                "redirect_uri" : "msauth://<YOUR_PACKAGE_NAME>/<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>",
+                "account_mode" : "<MULTIPLE|SINGLE>",
+                "broker_redirect_uri_registered": false,
+                "authorities": [
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<sign_in_up_policy_name>/",
+                    "default": true
+                    },
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<other_policy e.g. reset_pass>/"
+                    }
+                ],
+                "default_scopes": [
+                    "https://<youractivedirectoryname>.onmicrosoft.com/<application (server) id>/<API name>"
+                ]
+            }
+            ```
+        * launch:
+            * flutter launch
+            * choose an android emulator or device
+    * Web:
+        * path: web/assets/
+        * template:
+            ```json
+            {
+                "client_id" : "<application (client) id>",
+                "redirect_uri" : "<your app domain>",
+                "cache_location": "<localStorage|sessionStorage>",
+                "interaction_mode": "<popup|redirect>",
+                "authorities": [
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<sign_in_up_policy_name>/",
+                    "default": true
+                    },
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<other_policy e.g. reset_pass>/"
+                    }
+                ],
+                "default_scopes": [
+                    "https://<youractivedirectoryname>.onmicrosoft.com/<application (server) id>/<API name>"
+                ]
+            }
+            ```
+        * launch:
+            * flutter launch -d chrome --web-port <port>
+            * Note: choose port number according to the redirect uri registered in the B2C app.
+
diff --git a/b2c_config_template_android.json → doc/b2c_config_template_android.json b/b2c_config_template_android.json → doc/b2c_config_template_android.json
diff --git a/b2c_config_template_web.json → doc/b2c_config_template_web.json b/b2c_config_template_web.json → doc/b2c_config_template_web.json
diff --git a/example/README.md b/example/README.md
@@ -1,16 +1,66 @@
-# msal_auth_example
+# flutter_azure_b2c example
 
-Demonstrates how to use the msal_auth plugin.
+Demonstrates how to use the flutter_azure_b2c plugin.
 
 ## Getting Started
 
-This project is a starting point for a Flutter application.
+* Configure a B2C app following Microsoft documentation.
+* Prepare a configuration file:
+    * Android: 
+        * path: android/app/main/res/raw/
+        * template:
+            ```json
+            {
+                "client_id" : "<application (client) id>",
+
+                "redirect_uri" : "msauth://<YOUR_PACKAGE_NAME>/<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>",
+                "account_mode" : "<MULTIPLE|SINGLE>",
+                "broker_redirect_uri_registered": false,
+                "authorities": [
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<sign_in_up_policy_name>/",
+                    "default": true
+                    },
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<other_policy e.g. reset_pass>/"
+                    }
+                ],
+                "default_scopes": [
+                    "https://<youractivedirectoryname>.onmicrosoft.com/<application (server) id>/<API name>"
+                ]
+            }
+            ```
+        * launch:
+            * flutter launch
+            * choose an android emulator or device
+    * Web:
+        * path: web/assets/
+        * template:
+            ```json
+            {
+                "client_id" : "<application (client) id>",
+                "redirect_uri" : "<your app domain>",
+                "cache_location": "<localStorage|sessionStorage>",
+                "interaction_mode": "<popup|redirect>",
+                "authorities": [
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<sign_in_up_policy_name>/",
+                    "default": true
+                    },
+                    {
+                    "type": "B2C",
+                    "authority_url": "https://<youractivedirectoryname>.b2clogin.com/<youractivedirectoryname>.onmicrosoft.com/<other_policy e.g. reset_pass>/"
+                    }
+                ],
+                "default_scopes": [
+                    "https://<youractivedirectoryname>.onmicrosoft.com/<application (server) id>/<API name>"
+                ]
+            }
+            ```
+        * launch:
+            * flutter launch -d chrome --web-port <port>
+            * Note: choose port number according to the redirect uri registered in the B2C app.
 
-A few resources to get you started if this is your first Flutter project:
-
-- [Lab: Write your first Flutter app](https://flutter.dev/docs/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://flutter.dev/docs/cookbook)
-
-For help getting started with Flutter, view our
-[online documentation](https://flutter.dev/docs), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
diff --git a/example/lib/main.dart b/example/lib/main.dart
@@ -23,11 +23,18 @@ class _MyAppState extends State<MyApp> {
   @override
   void initState() {
     super.initState();
+
+    // It is possible to register callbacks in order to handle return values
+    // from asynchronous calls to the plugin
     AzureB2C.registerCallback(B2COperationSource.INIT, (result) async {
       if (result.reason == B2COperationState.SUCCESS) {
         _configuration = await AzureB2C.getConfiguration();
       }
     });
+
+    // Important: Remeber to handle redirect states (if you want to support
+    // the web platform with redirect method) and init the AzureB2C plugin
+    // before the material app starts.
     AzureB2C.handleRedirectFuture().then((_) => AzureB2C.init("auth_config"));
   }
 
@@ -46,15 +53,12 @@ class _MyAppState extends State<MyApp> {
               children: [
                 TextButton(
                     onPressed: () async {
+                      // you can just perform calls to the AzureB2C plugin to
+                      // handle the B2C protocol (e.g. acquire, refresh tokens
+                      // or sign out).
                       var data = await AzureB2C.policyTriggerInteractive(
                           _configuration!.defaultAuthority.policyName,
-                          _configuration!.defaultScopes!
-                          // <String>[
-                          //   //you may ask user scopes here e.g.
-                          //   //https://<hostname>/<server:client_id>/<scope_name>
-                          //   "https://nodriverservices.onmicrosoft.com/9c26e9a7-4bcf-4fb0-9582-3552a70219fe/Irreo.APIv2.Access"
-                          // ]
-                          ,
+                          _configuration!.defaultScopes!,
                           null);
                       setState(() {
                         _retdata = data;

diff --git a/lib/flutter_azure_b2c.dart b/lib/flutter_azure_b2c.dart
@@ -40,7 +40,7 @@ typedef AzureB2CCallback = Future<void> Function(B2COperationResult);
 ///
 /// This static class permits to:
 ///   * Init a proper AzureB2C provider using a native MSAL implementation.
-///   * Trigger, interactively and silently, B2C policies (user-flows) (e.g.
+///   * Trigger, interactively or silently, B2C policies (user-flows) (e.g.
 ///   sing-up/sing-in users, reset password, or modify information)
 ///   * Sign-out users (i.e. erases completelly associated user's information,
 ///   id-token, ecc).

diff --git a/pubspec.yaml b/pubspec.yaml
@@ -1,5 +1,5 @@
 name: flutter_azure_b2c
-description: A new flutter plugin project.
+description: Azure AD B2C client library
 version: 0.0.1
 homepage: "https://github.com/nodriver-ai/flutter_azure_b2c"