labs/access-controlling/access-controlling.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# APIM ❤️ OpenAI\n",
    "\n",
    "## Access Controlling lab\n",
    "![flow](../../images/access-controlling.gif)\n",
    "\n",
    "Playground to try the [OAuth 2.0 authorization feature](https://learn.microsoft.com/azure/api-management/api-management-authenticate-authorize-azure-openai#oauth-20-authorization-using-identity-provider) using identity provider to enable more fine-grained access to OpenAPI APIs by particular users or client.\n",
    "\n",
    "### Prerequisites\n",
    "- [Python 3.12 or later version](https://www.python.org/) installed\n",
    "- [Pandas Library](https://pandas.pydata.org/) installed\n",
    "- [VS Code](https://code.visualstudio.com/) installed with the [Jupyter notebook extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) enabled\n",
    "- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed\n",
    "- [An Azure Subscription](https://azure.microsoft.com/free/) with Contributor permissions\n",
    "- [Access granted to Azure OpenAI](https://aka.ms/oai/access) or just enable the mock service\n",
    "- [Sign in to Azure with Azure CLI](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='0'></a>\n",
    "### 0️⃣ Initialize notebook variables\n",
    "\n",
    "- Resources will be suffixed by a unique string based on your subscription id.\n",
    "- Adjust the location parameters according your preferences and on the [product availability by Azure region.](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/?cdn=disable&products=cognitive-services,api-management) \n",
    "- Adjust the OpenAI model and version according the [availability by region.](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "metadata": {}
   },
   "outputs": [],
   "source": [
    "import os, sys, json\n",
    "sys.path.insert(1, '../../shared')  # add the shared directory to the Python path\n",
    "import utils\n",
    "\n",
    "deployment_name = os.path.basename(os.path.dirname(globals()['__vsc_ipynb_file__']))\n",
    "resource_group_name = f\"lab-{deployment_name}\" # change the name to match your naming style\n",
    "app_registration_name = f\"{deployment_name}-app\" # name of the app that will be registered in Microsoft Entra ID\n",
    "resource_group_location = \"uksouth\"\n",
    "\n",
    "apim_sku = 'Basicv2'\n",
    "\n",
    "openai_resources = [ {\"name\": \"openai1\", \"location\": \"uksouth\"}]\n",
    "\n",
    "openai_model_name = \"gpt-4o-mini\"\n",
    "openai_model_version = \"2024-07-18\"\n",
    "openai_model_sku = \"GlobalStandard\"\n",
    "openai_model_capacity = 20\n",
    "openai_deployment_name = \"gpt-4o-mini\"\n",
    "openai_api_version = \"2024-10-21\"\n",
    "\n",
    "utils.print_ok('Notebook initialized')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='1'></a>\n",
    "### 1️⃣ Create the App Registration in Microsoft Entra ID\n",
    "The following command creates a client application registration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output = utils.run(\"az account show\", \"Retrieved az account\", \"Failed to get the current az account\")\n",
    "\n",
    "if output.success and output.json_data:\n",
    "    current_user = output.json_data['user']['name']\n",
    "    tenant_id = output.json_data['tenantId']\n",
    "    subscription_id = output.json_data['id']\n",
    "\n",
    "    utils.print_info(f\"Current user: {current_user}\")\n",
    "    utils.print_info(f\"Tenant ID: {tenant_id}\")\n",
    "    utils.print_info(f\"Subscription ID: {subscription_id}\")\n",
    "\n",
    "client_id = None\n",
    "output = utils.run(f\"az ad app list --filter \\\"displayName eq '{app_registration_name}'\\\"\", f\"Retrieved app registration with name {app_registration_name}\", \"Failed to get the app registration\")\n",
    "if output.success and output.json_data:\n",
    "    client_id = output.json_data[0]['appId']\n",
    "else:\n",
    "    output = utils.run(f\"az ad app create --display-name {app_registration_name} --is-fallback-public-client true\", f\"Created app registration with name {app_registration_name}\", \"Failed to create the app registration\")\n",
    "    if output.success and output.json_data:\n",
    "        client_id = output.json_data['appId']\n",
    "\n",
    "print(f\"👉🏻 Client Id: {client_id}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='2'></a>\n",
    "### 2️⃣ Create deployment using 🦾 Bicep\n",
    "\n",
    "This lab uses [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview?tabs=bicep) to declarative define all the resources that will be deployed in the specified resource group. Change the parameters or the [main.bicep](main.bicep) directly to try different configurations.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the resource group if doesn't exist\n",
    "utils.create_resource_group(resource_group_name, resource_group_location)\n",
    "\n",
    "# Define the Bicep parameters\n",
    "bicep_parameters = {\n",
    "    \"$schema\": \"https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\",\n",
    "    \"contentVersion\": \"1.0.0.0\",\n",
    "    \"parameters\": {\n",
    "        \"apimSku\": { \"value\": apim_sku },\n",
    "        \"openAIConfig\": { \"value\": openai_resources },\n",
    "        \"openAIDeploymentName\": { \"value\": openai_deployment_name },\n",
    "        \"openAIModelName\": { \"value\": openai_model_name },\n",
    "        \"openAIModelVersion\": { \"value\": openai_model_version },\n",
    "        \"openAIModelCapacity\": { \"value\": openai_model_capacity },\n",
    "        \"openAIModelSKU\": { \"value\": openai_model_sku },\n",
    "        \"openAIAPIVersion\": { \"value\": openai_api_version },\n",
    "        \"tenantId\": { \"value\": tenant_id },\n",
    "        \"clientId\": { \"value\": client_id }\n",
    "    }\n",
    "}\n",
    "\n",
    "# Write the parameters to the params.json file\n",
    "with open('params.json', 'w') as bicep_parameters_file:\n",
    "    bicep_parameters_file.write(json.dumps(bicep_parameters))\n",
    "\n",
    "# Run the deployment\n",
    "output = utils.run(f\"az deployment group create --name {deployment_name} --resource-group {resource_group_name} --template-file main.bicep --parameters params.json\",\n",
    "    f\"Deployment '{deployment_name}' succeeded\", f\"Deployment '{deployment_name}' failed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='4'></a>\n",
    "### 4️⃣ Get the deployment outputs\n",
    "\n",
    "We are now at the stage where we only need to retrieve the gateway URL and the subscription before we are ready for testing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Obtain all of the outputs from the deployment\n",
    "output = utils.run(f\"az deployment group show --name {deployment_name} -g {resource_group_name}\", f\"Retrieved deployment: {deployment_name}\", f\"Failed to retrieve deployment: {deployment_name}\")\n",
    "\n",
    "if output.success and output.json_data:\n",
    "    apim_service_id = utils.get_deployment_output(output, 'apimServiceId', 'APIM Service Id')\n",
    "    apim_resource_gateway_url = utils.get_deployment_output(output, 'apimResourceGatewayURL', 'APIM API Gateway URL')\n",
    "    apim_subscription_key = utils.get_deployment_output(output, 'apimSubscriptionKey', 'APIM Subscription Key (masked)', True)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='5'></a>\n",
    "### 5️⃣ Create a device flow to get the access token\n",
    "\n",
    "Notes for fine grained authorization:\n",
    "- The APIM [JWT validation policy](https://learn.microsoft.com/azure/api-management/validate-azure-ad-token-policy) can check for specific claims (that needs to exist in the token) and apply fine-grained authorization.\n",
    "- Group claims is a typical method. You can use this approach to drive authorization. However, when the user is a member of too many groups, the `groups` will be excluded from the token due to limitations in token size.\n",
    "- An alternative is to configure app role definitions and assign users/groups to app roles. This Zero Trust developer best practice improves flexibility and control while increasing application security with least privilege. [Learn more](https://learn.microsoft.com/security/zero-trust/develop/configure-tokens-group-claims-app-roles).\n",
    "- To obtain the `roles` claim, navigate to the \"Expose an API\" section of the App Registration. Add the Application ID URI and a scope. Then, copy the full scope `(app://<id>/scope)` and replace in the scope array below.\n",
    "- Navigate to the \"App Roles\" blade and create an App Role (ex: OpenAI.ChatCompletion) for Users/Groups members. Then assign the testing user or group to the App Role.   \n",
    "- After logging in, use https://jwt.io/ to decode the `access_token` variable and verify that the `roles` are being sent.\n",
    "- With the above configuration, you can add the following fragment to the APIM policy to verify that the user belongs to a specific App Role:\n",
    "```\n",
    "            <required-claims>\n",
    "                <claim name=\"roles\" match=\"any\">\n",
    "                    <value>OpenAI.ChatCompletion</value>\n",
    "                </claim>\n",
    "            </required-claims>\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import msal\n",
    "\n",
    "app = msal.PublicClientApplication(client_id, authority = \"https://login.microsoftonline.com/\" + tenant_id)\n",
    "\n",
    "flow = app.initiate_device_flow(scopes = [\"User.Read\"])\n",
    "\n",
    "if \"user_code\" not in flow:\n",
    "    raise ValueError(\n",
    "        \"Fail to create device flow. Err: %s\" % json.dumps(flow, indent = 4))\n",
    "\n",
    "print(flow[\"message\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='6'></a>\n",
    "### 6️⃣ Acquire the token and query the graph API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "result = app.acquire_token_by_device_flow(flow)\n",
    "\n",
    "if \"access_token\" in result:\n",
    "    access_token = result['access_token']\n",
    "    # Calling graph using the access token\n",
    "    graph_data = requests.get(  # Use token to call downstream service\n",
    "        \"https://graph.microsoft.com/v1.0/me\",\n",
    "        headers={'Authorization': 'Bearer ' + access_token},).json()\n",
    "    print(\"Graph API call result: %s\" % json.dumps(graph_data, indent = 2))\n",
    "    # print(access_token) # Use a tool like https://jwt.io/ to decode the access token and see its contents\n",
    "else:\n",
    "    print(result.get(\"error\"))\n",
    "    print(result.get(\"error_description\"))\n",
    "    print(result.get(\"correlation_id\"))  # You may need this when reporting a bug"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='requests'></a>\n",
    "### 🧪 Test the API using a direct HTTP call\n",
    "Requests is an elegant and simple HTTP library for Python that will be used here to make raw API requests and inspect the responses.\n",
    "\n",
    "Tip: Use the [tracing tool](../../tools/tracing.ipynb) to debug the policy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "url = apim_resource_gateway_url + \"/openai/deployments/\" + openai_deployment_name + \"/chat/completions?api-version=\" + openai_api_version\n",
    "\n",
    "messages = { \"messages\": [\n",
    "    {\"role\": \"system\", \"content\": \"You are a sarcastic unhelpful assistant.\"},\n",
    "    {\"role\": \"user\", \"content\": \"Can you tell me the time, please?\"}\n",
    "]}\n",
    "\n",
    "response = requests.post(url, headers = {'api-key': apim_subscription_key, 'Authorization': 'Bearer ' + access_token}, json = messages)\n",
    "utils.print_response_code(response)\n",
    "\n",
    "if (response.status_code == 200):\n",
    "    data = json.loads(response.text)\n",
    "    print(f\"💬 {data.get(\"choices\")[0].get(\"message\").get(\"content\")}\")\n",
    "else:\n",
    "    print(response.text)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='sdk'></a>\n",
    "### 🧪 Test the API using the Azure OpenAI Python SDK\n",
    "OpenAPI provides a widely used [Python library](https://github.com/openai/openai-python). The library includes type definitions for all request params and response fields. The goal of this test is to assert that APIM can seamlessly proxy requests to OpenAI without disrupting its functionality.\n",
    "- Note: run ```pip install openai``` in a terminal before executing this step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from openai import AzureOpenAI\n",
    "\n",
    "client = AzureOpenAI(\n",
    "    azure_endpoint = apim_resource_gateway_url,\n",
    "    api_key = apim_subscription_key,\n",
    "    api_version = openai_api_version\n",
    ")\n",
    "\n",
    "response = client.chat.completions.create(model = openai_model_name, messages = [\n",
    "                        {\"role\": \"system\", \"content\": \"You are a sarcastic unhelpful assistant.\"},\n",
    "                        {\"role\": \"user\", \"content\": \"Can you tell me the time, please?\"}\n",
    "                    ], \n",
    "                    extra_headers = {\"Authorization\": \"Bearer \" + access_token}) \n",
    "\n",
    "print(response.choices[0].message.content)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='clean'></a>\n",
    "### 🗑️ Clean up resources\n",
    "\n",
    "When you're finished with the lab, you should remove all your deployed resources from Azure to avoid extra charges and keep your Azure subscription uncluttered.\n",
    "Use the [clean-up-resources notebook](clean-up-resources.ipynb) for that."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}