Copy changes

Author: simonkurtz-MSFT

samples/authX-pro/create.ipynb

@@ -8,8 +8,6 @@
     "\n",
     "Sets up a more sophisticate authentication (authN) and authorization (authZ) combination for role-based access control (RBAC) to a mock API and its operations.  \n",
     "\n",
-    "This sample, compared to the simpler _AuthX_, introduces use of API Management Product and policy fragments to simplify and consolidate shared logic. When considering scaling, consider this as your starting point.\n",
-    "\n",
     "⚙️ **Supported infrastructures**: All infrastructures\n",
     "\n",
     "⌚ **Expected *Run All* runtime (excl. infrastructure prerequisite): ~2-3 minutes**\n",
@@ -23,14 +21,25 @@
     "1. Experience how API Management policy fragments simplify shared logic.\n",
     "\n",
     "## 📝 Scenario\n",
+    "This sample, compared to the simpler _AuthX_, introduces use of API Management Product and policy fragments to simplify and consolidate shared logic. When considering scaling, consider this as your starting point.\n",
     "\n",
-    "This sample combines _authentication (authN)_ and _authorization (authZ)_ into _authX_. This scenario focuses on a Human Resources API that requires privileged role-based access to GET and to POST data. This is simplistic but shows the combination of authN and authZ.\n",
-    "\n",
-    "There are two personas at play:\n",
+    "The same two personas from _AuthX_ are at play:\n",
     "\n",
     "- `HR Administrator` - holds broad rights to the API\n",
     "- `HR Associate` - has read-only permissions\n",
     "\n",
+    "The API hierarchy is as follows:\n",
+    "\n",
+    "1. All APIs / global\n",
+    "    This is a great place to do authentication, but we refrain from doing it in the sample as to not affect other samples. \n",
+    "1. HR Product\n",
+    "    Perform authentication and authorization for HR_Member in the JWT claims. Continue on success; otherwise, return 401.\n",
+    "1. HR Employee & Benefits APIs\n",
+    "    Both APIs are associated with the HR Product. The API must be called in a product context.\n",
+    "1. API Operations\n",
+    "    GET authorization must either satisfy an HR Administrator or HR Associate role\n",
+    "    POST authorization must satisfy an HR Administrator role..\n",
+    "\n",
     "Both personas are part of an HR_Members group and may access the HR API Management Product. Subsequent access to the APIs and their operations must be granular.\n",
     "\n",
     "### 💡 Notes\n",
@@ -128,7 +137,9 @@
     "\n",
     "hr_product_name = 'hr'\n",
     "products: List[Product] = [\n",
-    "    Product(hr_product_name, 'Human Resources', 'Product for Human Resources APIs providing access to employee data, organizational structure, benefits information, and HR management services. Includes JWT-based authentication for HR members.', 'published', False, False, hr_product_xml)\n",
+    "    Product(hr_product_name, 'Human Resources', \n",
+    "            'Product for Human Resources APIs providing access to employee data, organizational structure, benefits information, and HR management services. Includes JWT-based authentication for HR members.', \n",
+    "            'published', False, False, hr_product_xml)\n",
     "]\n",
     "\n",
     "# 6) Define the APIs and their operations and policies\n",
@@ -137,13 +148,15 @@
     "hremployees_api_path = f'/{api_prefix}employees'\n",
     "hremployees_get = GET_APIOperation('Gets the employees', utils.read_policy_xml('./hr_get.xml'))\n",
     "hremployees_post = POST_APIOperation('Creates a new employee', utils.read_policy_xml('./hr_post.xml'))\n",
-    "hremployees = API(f'{api_prefix}Employees', 'Employees Pro', hremployees_api_path, 'This is a Human Resources API for employee information', utils.read_policy_xml(DEFAULT_XML_POLICY_PATH), operations = [hremployees_get, hremployees_post], tags = tags, productNames = [hr_product_name])\n",
+    "hremployees = API(f'{api_prefix}Employees', 'Employees Pro', hremployees_api_path, 'This is a Human Resources API for employee information', utils.read_policy_xml(DEFAULT_XML_POLICY_PATH), \n",
+    "                  operations = [hremployees_get, hremployees_post], tags = tags, productNames = [hr_product_name], subscriptionRequired = True)\n",
     "\n",
     "# Benefits (HR)\n",
     "hrbenefits_api_path = f'/{api_prefix}benefits'\n",
     "hrbenefits_get = GET_APIOperation('Gets employee benefits', utils.read_policy_xml('./hr_get.xml'))\n",
     "hrbenefits_post = POST_APIOperation('Creates employee benefits', utils.read_policy_xml('./hr_post.xml'))\n",
-    "hrbenefits = API(f'{api_prefix}Benefits', 'Benefits Pro', hrbenefits_api_path, 'This is a Human Resources API for employee benefits', utils.read_policy_xml(DEFAULT_XML_POLICY_PATH), operations = [hrbenefits_get, hrbenefits_post], tags = tags, productNames = [hr_product_name])\n",
+    "hrbenefits = API(f'{api_prefix}Benefits', 'Benefits Pro', hrbenefits_api_path, 'This is a Human Resources API for employee benefits', utils.read_policy_xml(DEFAULT_XML_POLICY_PATH), \n",
+    "                 operations = [hrbenefits_get, hrbenefits_post], tags = tags, productNames = [hr_product_name], subscriptionRequired = True)\n",
     "\n",
     "# APIs Array\n",
     "apis: List[API] = [hremployees, hrbenefits]\n",

samples/authX/create.ipynb

@@ -28,7 +28,7 @@
     "- `HR Administrator` - holds broad rights to the API\n",
     "- `HR Associate` - has read-only permissions\n",
     "\n",
-    "Both personas are part of an HR_Members group and may access the HR API Management Product. Subsequent access to the APIs and their operations must be granular.\n",
+    "Both personas are part of an HR_Members group and may access the HR Employees API, but its operations permissions are more granular.\n",
     "\n",
     "### 💡 Notes\n",
     "\n",