From 9b955067ae461dca80ebc2c6292badb1d1e15d95 Mon Sep 17 00:00:00 2001 From: Luca Calacci Date: Thu, 22 Jul 2021 18:42:51 +0200 Subject: [PATCH] v0.0.1 --- CHANGELOG.md | 13 +- README.md | 143 ++++++++++++++++-- doc/ExampleGettingStarted.md | 66 ++++++++ .../b2c_config_template_android.json | 0 .../b2c_config_template_web.json | 0 example/README.md | 72 +++++++-- example/lib/main.dart | 18 ++- lib/flutter_azure_b2c.dart | 2 +- pubspec.yaml | 2 +- 9 files changed, 286 insertions(+), 30 deletions(-) create mode 100644 doc/ExampleGettingStarted.md rename b2c_config_template_android.json => doc/b2c_config_template_android.json (100%) rename b2c_config_template_web.json => doc/b2c_config_template_web.json (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 41cc7d8..dc2619e 100644 --- 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 index e4e81be..fec5abc 100644 --- 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 /android/app/src/main/AndroidManifest.xml: +```xml + + +``` + +* Add also an intent filter in the manifest file to capture redirect from MSAL service: +```xml + + + + + + + + + +``` +For more information see https://github.com/AzureAD/microsoft-authentication-library-for-android. + +* Prepare a JSON configuration file for AzureB2C initialization in /android/app/main/res/raw/ following this template: +```json + { + "client_id" : "", + "redirect_uri" : "msauth:///", + "account_mode" : "", + "broker_redirect_uri_registered": false, + "authorities": [ + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//", + "default": true + }, + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//" + } + ], + "default_scopes": [ + "https://.onmicrosoft.com//" + ] + } +``` +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 . + +### Web + +* Add CDN dependecy in your index.html file: +```html + +``` +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 . + +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 /web/asset/ following this template: +```json + { + "client_id" : "", + "redirect_uri" : "", + "cache_location": "", + "interaction_mode": "", + "authorities": [ + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//", + "default": true + }, + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//" + } + ], + "default_scopes": [ + "https://.onmicrosoft.com//" + ] + } +``` + +## Run the example + +In /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 + * 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 new file mode 100644 index 0000000..14a3f3e --- /dev/null +++ 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" : "", + + "redirect_uri" : "msauth:///", + "account_mode" : "", + "broker_redirect_uri_registered": false, + "authorities": [ + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//", + "default": true + }, + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//" + } + ], + "default_scopes": [ + "https://.onmicrosoft.com//" + ] + } + ``` + * launch: + * flutter launch + * choose an android emulator or device + * Web: + * path: web/assets/ + * template: + ```json + { + "client_id" : "", + "redirect_uri" : "", + "cache_location": "", + "interaction_mode": "", + "authorities": [ + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//", + "default": true + }, + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//" + } + ], + "default_scopes": [ + "https://.onmicrosoft.com//" + ] + } + ``` + * launch: + * flutter launch -d chrome --web-port + * Note: choose port number according to the redirect uri registered in the B2C app. + diff --git a/b2c_config_template_android.json b/doc/b2c_config_template_android.json similarity index 100% rename from b2c_config_template_android.json rename to doc/b2c_config_template_android.json diff --git a/b2c_config_template_web.json b/doc/b2c_config_template_web.json similarity index 100% rename from b2c_config_template_web.json rename to doc/b2c_config_template_web.json diff --git a/example/README.md b/example/README.md index 4f1cf7f..14a3f3e 100644 --- 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" : "", + + "redirect_uri" : "msauth:///", + "account_mode" : "", + "broker_redirect_uri_registered": false, + "authorities": [ + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//", + "default": true + }, + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//" + } + ], + "default_scopes": [ + "https://.onmicrosoft.com//" + ] + } + ``` + * launch: + * flutter launch + * choose an android emulator or device + * Web: + * path: web/assets/ + * template: + ```json + { + "client_id" : "", + "redirect_uri" : "", + "cache_location": "", + "interaction_mode": "", + "authorities": [ + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//", + "default": true + }, + { + "type": "B2C", + "authority_url": "https://.b2clogin.com/.onmicrosoft.com//" + } + ], + "default_scopes": [ + "https://.onmicrosoft.com//" + ] + } + ``` + * launch: + * flutter launch -d chrome --web-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 index 43e7dfc..394e128 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -23,11 +23,18 @@ class _MyAppState extends State { @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 { 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! - // [ - // //you may ask user scopes here e.g. - // //https://// - // "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 index f30ed38..7efc5c6 100644 --- a/lib/flutter_azure_b2c.dart +++ b/lib/flutter_azure_b2c.dart @@ -40,7 +40,7 @@ typedef AzureB2CCallback = Future 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 index 64bcbe1..9e60474 100644 --- 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"