documentation updates.

CHANGELOG.md

@@ -10,4 +10,20 @@
 
 ## 0.1.0
 
-* beta release
+* beta release
+
+## 0.1.1
+
+* bug fixes
+
+## 0.1.2
+
+* bug fixes
+
+## 0.1.3
+
+* update dependencies
+
+## 0.1.4
+
+* New documentation on setting up Azure delegated permissions

README.md

@@ -7,15 +7,14 @@ The plugin wraps the Android and iOS MSAL libraries from Microsoft.  MSAL Mobile
 ## Project Requirements
 
 * Flutter version greater than 1.12
-* Android minimum SDK Version of 19
 * iOS version of at least 11.0
 
 # Installation
 
 Add the following to your pubspec.yaml
 ```yaml
 dependencies:
-  msal_mobile: ^0.0.1
+  msal_mobile: ^0.1.4
 ```
 
 # Azure Setup
@@ -30,6 +29,8 @@ To authenticate with MSAL you will need to setup a new app registration in Azure
 5. Choose an option for **Supported account types** depending on your target user.
 6. Leave the selection empty for **Platform configuration (Optional)**. We will work on platform configuration in the following steps.
 7. Click **Register** to create the app registration.
+8. Go to **Certificates & secrets** in the app registration menu for the newly created app registration.
+9. In the **Client secrets** section, click the **New client secret** button.  Give your secret a description and expiration term.
 
 ## Configure the app registration for Android
 1. From the blade of the new app registration, select **Authentication**.
@@ -58,6 +59,36 @@ To authenticate with MSAL you will need to setup a new app registration in Azure
 6. Click the **Configure** button to finish setting up the iOS app in Azure.
 7. The **iOS / macOS** platform should now be listed as a platform in the app registration authentication blade.  Azure also generated a redirect URI for the platform.  This will be needed to configure MSAL Mobile, so copy it and set it aside for now.
 
+## Create an app registration for your app's backend (optional)
+By creating an app registration for your app's backend, you can use the token generated by MSAL Mobile to authenticate with your backend services.  This is not required to use the MSAL Mobile plugin but is being documented here because it can help to create a well rounded authentication solution for your entire project.  Follow these steps to set this up:
+
+1. Login to the Azure portal and navigate to Azure Active Directory.
+2. From the main menu in Azure Active Directory, select **App regisrations**.
+3. In the App registrations blade, click **New registration**.
+4. Give your app registration a name... anything works.
+5. Choose an option for **Supported account types** depending on your target user.
+6. Leave the selection empty for **Platform configuration (Optional)**.
+7. Click **Register** to create the app registration.
+8. Go to **Expose an API** in the app registration menu of the newly created app registration.
+9. In the **Scopes defined by this API** section, click the **Add a scope** button.
+10. Create the scope
+    * Give your scope a name.  Something like `user_impersonation`.
+    * Allow **Admins and users** to consent to the scope.
+    * Provide admin and user consent display names and descriptions.  These are the values that will be shown to your users when they are asked to consent to the permission by Microsoft's login flow.
+11. The new scope should now be listed under the **Scopes defined by this API** section.  Take note of the full scope name listed.  It should look something like this `api://[app-registration-client-id-guid]/user_impersonation`.  This is the scope name that MSAL will need.
+12. In the **Authorized client applications** section, click the **Add a client application** button.  This will essentially tell Azure Active Directory that access to this app registration can be granted by way of authenticating with the app registration that you created in the previous section.
+13. In the **Add a client application** blade, enter the client ID/application ID of the client app registration you created in the previous section, select the new `user_impersonation` scope you created earlier in this section and click **Add application**
+
+Now you can setup your backend to use this new app registration to authenticate its users.  When you generate your tokens from MSAL Mobile against your client app registration, be sure to set the full scope name of the newly created `user_impersonation` scope.  For example, your `signIn` call to MSAL Mobile will look like this:
+
+```dart
+await msal.signIn(null, ["api://[app-registration-client-id]/user_impersonation"]).then((result) {
+    print('access token (truncated): ${result.accessToken}');
+})
+```
+
+Visit https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2 for an example of setting up a .NET Core backend service to authenticate against your new backend app registration.
+
 # Android Setup
 1. Open **android > app > src > main** > **AndroidManifest.xml**.
 2. Add BrowserTabActivity to your AndroidManifest.xml file.
@@ -154,7 +185,7 @@ override func application(_ app: UIApplication, open url: URL, options: [UIAppli
     return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[.sourceApplication] as? String)
 }
 ```
-6. Add the following to the Info.plist file in **\<dict\>** by right clicking the file and opening as source. Replace `\[your-bundle-identifier\]` with the iOS bundle identifier identified during the iOS platform setup portion of the app registration setup.
+6. Add the following to the Info.plist file in **\<dict\>** by right clicking the file and opening as source. Replace `[your-bundle-identifier]` with the iOS bundle identifier identified during the iOS platform setup portion of the app registration setup.
 ```xml
 <key>CFBundleURLTypes</key>
 <array>

android/build.gradle

@@ -34,7 +34,14 @@ android {
 }
 
 dependencies {
-    implementation 'com.microsoft.identity.client:msal:1.0.1'
-    implementation 'org.jetbrains:annotations-java5:15.0'
     implementation 'com.google.code.gson:gson:2.8.6'
+    if (findProject(':msal') != null) {
+        // For developer team only.
+        localImplementation project(':msal')
+        externalImplementation 'com.microsoft.identity.client:msal:1.0.+'
+    }
+    else {
+        // Downloads and Builds MSAL from maven central.
+        implementation 'com.microsoft.identity.client:msal:1.0.+'
+    }
 }

android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.0.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.2-all.zip

android/src/main/java/com/gbwisx/msal_mobile/Payloads.java

@@ -4,7 +4,6 @@
 import com.microsoft.identity.client.IAuthenticationResult;
 
 import java.text.SimpleDateFormat;
-import java.util.Date;
 import java.util.Map;
 
 public class Payloads {

example/android/app/src/main/AndroidManifest.xml

@@ -29,8 +29,8 @@
                 <category android:name="android.intent.category.DEFAULT" />
                 <category android:name="android.intent.category.BROWSABLE" />
                 <data
-                    android:host="[your-package-name]"
-                    android:path="/[your-base64-signature-hash]"
+                    android:host="com.gbwisx.msal_mobile_example"
+                    android:path="/ldYUHWCGNN20tqnfF/8PbpDXSXM="
                     android:scheme="msauth" />
             </intent-filter>
         </activity>

example/assets/auth_config.json

@@ -1,8 +1,8 @@
 {
-  "client_id" : "[app-registration-client-id]",
+  "client_id" : "e5a55502-c69d-4135-a49d-0e5d0cd5049c",
   "authorization_user_agent" : "DEFAULT",
-  "redirect_uri" : "msauth://[your-package-name]/[url-encoded-package-signature-hash]",
-  "ios_redirect_uri": "msauth.[your-ios-bundle-identifier]://auth",
+  "redirect_uri" : "msauth://com.gbwisx.msal_mobile_example/ldYUHWCGNN20tqnfF%2F8PbpDXSXM%3D",
+  "ios_redirect_uri": "msauth.<your-ios-bundle-identifier>://auth",
   "account_mode": "SINGLE",
   "authorities" : [
     {

example/lib/main.dart

@@ -9,8 +9,8 @@ class MyApp extends StatefulWidget {
 }
 
 class _MyAppState extends State<MyApp> {
-  static const String SCOPE = 'api://[app-registration-client-id]/[delegated-permission-name]';
-  static const String TENANT_ID = '[target-tenant-id_or_"organizations"]';
+  static const String SCOPE = 'api://1b96e9ff-c59a-4123-8fa4-fcd1a76c1b06/user_impersonation';
+  static const String TENANT_ID = 'organizations';
   static String authority = "https://login.microsoftonline.com/$TENANT_ID";
 
   MsalMobile msal;

example/pubspec.lock

@@ -122,7 +122,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.1.0"
+    version: "0.1.4"
   path:
     dependency: transitive
     description:
@@ -256,4 +256,4 @@ packages:
     version: "3.5.0"
 sdks:
   dart: ">=2.4.0 <3.0.0"
-  flutter: ">1.12.0 <2.0.0"
+  flutter: ">=1.2.1 <2.0.0"

pubspec.lock

@@ -242,4 +242,4 @@ packages:
     version: "3.5.0"
 sdks:
   dart: ">=2.6.0 <3.0.0"
-  flutter: ">1.12.0 <2.0.0"
+  flutter: ">=1.10.1 <2.0.0"

pubspec.yaml

@@ -1,11 +1,10 @@
 name: msal_mobile
 description: A Flutter plugin for authenticating with Azure AD on Android and iOS using the Microsoft Authentication library (MSAL).
-version: 0.1.0
+version: 0.1.4
 homepage: https://github.com/gbwisx/msal_mobile
 
 environment:
   sdk: ">=2.1.0 <3.0.0"
-  flutter: ">1.12.0"
 
 dependencies:
   flutter:
@@ -25,13 +24,10 @@ flutter:
   # The androidPackage and pluginClass identifiers should not ordinarily
   # be modified. They are used by the tooling to maintain consistency when
   # adding or updating assets for this project.
+
   plugin:
-    platforms:
-      android:
-        package: com.gbwisx.msal_mobile
-        pluginClass: MsalMobilePlugin
-      ios:
-        pluginClass: MsalMobilePlugin
+    androidPackage: com.gbwisx.msal_mobile
+    pluginClass: MsalMobilePlugin
 
 
   # To add assets to your plugin package, add an assets section, like this: