Merge pull request #49273 from MicrosoftDocs/NEW-intro-azure-openai-managed-identity-auth-javascript

New intro azure openai managed identity auth javascript

Author: Stacyrch140

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/1-introduction.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: introduction-azure-openai-managed-identity-authentication-javascript.introduction
+title: Introduction
+metadata:
+  title: Introduction
+  description: Introduction to using managed identity authentication for JavaScript applications with Azure OpenAI Service.
+  ms.date: 02/10/2025
+  author: sarah-yo
+  ms.author: sayoung
+  ms.topic: unit
+durationInMinutes: 1
+content: |
+  [!include[](includes/1-introduction.md)]

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/2-azure-openai-rbac-roles.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: introduction-azure-openai-managed-identity-authentication-javascript.azure-openai-rbac-roles
+title: Azure OpenAI RBAC roles
+metadata:
+  title: Azure OpenAI RBAC roles
+  description: Learn about the Azure OpenAI RBAC roles that are available for managing access to resources.
+  ms.date: 02/10/2025
+  author: sarah-yo
+  ms.author: sayoung
+  ms.topic: unit
+durationInMinutes: 7
+content: |
+  [!include[](includes/2-azure-openai-rbac-roles.md)]

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/3-keyless-authentication-methods.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: introduction-azure-openai-managed-identity-authentication-javascript.keyless-authentication-methods
+title: Keyless authentication methods
+metadata:
+  title: Keyless authentication methods
+  description: Learn about keyless authentication methods that can be used to authenticate with Azure services.
+  ms.date: 02/10/2025
+  author: sarah-yo
+  ms.author: sayoung
+  ms.topic: unit
+durationInMinutes: 12
+content: |
+  [!include[](includes/3-keyless-authentication-methods.md)]

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/4-benefits-managed-identity-azure-openai.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: introduction-azure-openai-managed-identity-authentication-javascript.benefits-of-using-managed-identity-for-azure-openai
+title: Benefits of using a managed identity for Azure OpenAI
+metadata:
+  title: Benefits of using a managed identity for Azure OpenAI
+  description: Learn about the benefits of using a managed identity for Azure OpenAI.
+  ms.date: 02/10/2025
+  author: sarah-yo
+  ms.author: sayoung
+  ms.topic: unit
+durationInMinutes: 4
+content: |
+  [!include[](includes/4-benefits-managed-identity-azure-openai.md)]

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/5-knowledge-check.yml

@@ -0,0 +1,47 @@
+### YamlMime:ModuleUnit
+uid: introduction-azure-openai-managed-identity-authentication-javascript.knowledge-check
+title: Knowledge check
+metadata:
+  title: Knowledge check
+  description: Display your knowledge.
+  ms.date: 02/10/2025
+  author: sarah-yo
+  ms.author: sayoung
+  ms.topic: unit
+durationInMinutes: 4
+content: Choose the best response for each question. 
+quiz:
+  questions:
+    - content: "What is the primary benefit of using managed identities over API keys in Azure OpenAI?"
+      choices:
+      - content: "Enhanced security"
+        isCorrect: true
+        explanation: "Managed identities eliminate the need to store credentials within application code, reducing the risk of credential leaks. They leverage Entra ID for authentication, providing a more secure and automated method for accessing Azure services."
+      - content: "Increased performance"
+        isCorrect: false
+        explanation: "While managed identities improve security, they don't inherently increase application performance."
+      - content: "Cost reduction"
+        isCorrect: false
+        explanation: "Managed identities don't directly impact the cost of Azure services; their primary benefit is enhanced security."
+    - content: "Which role in Azure OpenAI allows you to create custom fine-tuned models and manage model deployments?"
+      choices:
+      - content: "Cognitive Services OpenAI Contributor"
+        isCorrect: true
+        explanation: "This role includes permissions to create custom fine-tuned models, upload datasets, and manage model deployments."
+      - content: "Cognitive Services OpenAI User"
+        isCorrect: false
+        explanation: "The OpenAI User role has limited permissions and can't create or manage models. It only allows viewing resources and making inference API calls."
+      - content: "Cognitive Services Usages Reader"
+        isCorrect: false
+        explanation: "The Usages Reader role is focused on monitoring usage and doesn't have permissions for model management. It only allows viewing quota usage."
+    - content: "In the provided JavaScript code example, what is the purpose of the openai.ChatCompletion.create method?"
+      choices:
+      - content: "Generate a response from the OpenAI model"
+        isCorrect: true
+        explanation: "This method sends a request to the OpenAI service with the specified parameters, such as the model, prompt, and other settings, and returns the generated response."
+      - content: "Authenticate the user"
+        isCorrect: false
+        explanation: "Authentication is handled separately, typically using credentials or tokens, and isn't the purpose of this method."
+      - content: "Store the API response"
+        isCorrect: false
+        explanation: "This method generates a response from the OpenAI model but doesn't handle storing the response; storing data would require additional code."

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/6-summary.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: introduction-azure-openai-managed-identity-authentication-javascript.summary
+title: Summary
+metadata:
+  title: Summary
+  description: This unit summarizes what you learned in the module.
+  ms.date: 02/10/2025
+  author: sarah-yo
+  ms.author: sayoung
+  ms.topic: unit
+durationInMinutes: 1
+content: |
+  [!include[](includes/6-summary.md)]

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/includes/1-introduction.md

@@ -0,0 +1,8 @@
+Good security practices require that you control access to applications that you develop. Developing an application in Azure OpenAI Service is no different. In this module, you learn about configuring authentication to Azure OpenAI by using JavaScript, the available roles in Azure OpenAI, and the benefits of using managed identities over API keys.
+
+By the end of this module, you are able to:
+
+- Describe the role-based access control (RBAC) roles for use in Azure OpenAI and configure role assignments.
+- Describe the differences between using API keys and managed identities within Azure OpenAI.
+- Configure keyless authentication to Azure OpenAI for local development for JavaScript.
+- Configure keyless authentication to Azure OpenAI for Azure-hosted environments for JavaScript.

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/includes/2-azure-openai-rbac-roles.md

@@ -0,0 +1,60 @@
+These RBAC roles are available for you to assign to identities for Azure OpenAI Service:
+
+- The *Cognitive Services OpenAI User* role allows viewing resources, endpoints, and model deployments; using playground experiences; and making inference API calls. However, it doesn't permit creating resources, viewing/copying/regenerating keys, or managing model deployments.
+- The *Cognitive Services OpenAI Contributor* role includes all user permissions plus the ability to create custom fine-tuned models, upload datasets, and manage model deployments. It doesn't allow creating new resources or managing keys.
+- The *Cognitive Services Contributor* role permits creating new resources, viewing and managing keys, creating and managing model deployments, and using playground experiences. It doesn't allow access to quotas or making inference API calls.
+- The *Cognitive Services Usages Reader* role allows viewing quota usage across a subscription. This role provides minimal access and is typically combined with other roles.
+
+Always choose a role that provides the lowest amount of privilege required for the identity to do the tasks that it needs to perform. For more detail on Azure OpenAI RBAC roles.
+
+## Configure role assignments in the Azure portal
+
+To enable keyless authentication, follow these steps to configure the necessary role assignments:
+
+1. In the Azure portal, go to your specific Azure OpenAI resource.
+2. On the service menu, select **Access Control (IAM)**.
+3. Select **Add role assignment**. On the pane that opens, select the **Role** tab.
+4. Select the role that you want to assign.
+5. On the **Members** tab, select a user, group, service principal, or managed identity to assign to the role.
+6. On the **Review + assign** tab, confirm your selections. Select **Review + assign** to finalize the role assignment.
+
+Within a few minutes, the selected user or identity is granted the assigned role at the chosen scope. The user or identity can then access Azure OpenAI services without needing an API key.
+
+## Configure role assignments in the Azure CLI
+
+To configure role assignments by using the Azure CLI, perform these steps:
+
+1. Find the role for your usage of Azure OpenAI. Depending on how you intend to set that role, you need either the name or the ID:
+
+   - For the Azure CLI or Azure PowerShell, you can use a role name.
+   - For Bicep, you need the role ID.
+
+   Use the following table to select a role name or role ID:
+
+   | Use case | Role name | Role ID |
+   |---|---|---|
+   | Assistants | Cognitive Services OpenAI Contributor | a001fd3d-188f-4b5d-821b-7da978bf7442 |
+   | Chat completions | Cognitive Services OpenAI User | 5e0bd9bd-7b93-4f28-af87-19fc36ad61bd |
+
+1. Select an identity type to use:
+
+   - A *personal identity* is tied to your Azure sign-in.
+   - A *managed identity* is managed by Azure and created for use on Azure. For this choice, create a user-assigned managed identity. When you create the managed identity, you need the client ID (also called the app ID).
+
+1. Find your personal identity and use the ID as the `<identity-id>` value in this step.
+
+   For local development, to get your own identity ID, use the following command. You need to sign in with `az login` before using this command.
+
+   ```azurecli
+   az ad signed-in-user show \
+       --query id -o tsv
+   ```
+
+1. Assign the RBAC role to the identity for the resource group. To grant your identity permissions to your resource through RBAC, assign a role by using the Azure CLI command `az role assignment create`. Replace `<identity-id>`, `<subscription-id>`, and `<resource-group-name>` with your actual values.
+
+   ```azurecli
+   az role assignment create \
+       --role "Cognitive Services OpenAI User" \
+       --assignee "\<identity-id>" \
+       --scope "/subscriptions/\<subscription-id>/resourceGroups/\<resource-group-name>"
+   ```

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/includes/3-keyless-authentication-methods.md

@@ -0,0 +1,32 @@
+In keyless authentication to Azure OpenAI for JavaScript, you use Azure's managed identities or service principals to authenticate instead of hardcoding API keys or other credentials. This is done through the `DefaultAzureCredential` or `ManagedIdentityCredential` class, which provides a secure and streamlined way to obtain tokens needed for authenticating Azure services. Here's how it works in practice:
+
+1. Set Up Azure Environment: Ensure your Azure environment is configured correctly with managed identities.
+2. Initialize Credentials: Use the `DefaultAzureCredential` class or `ManagedIdentityCredential` class from the Azure Identity SDK for JavaScript to handle the authentication process seamlessly.
+
+Here's an example code snippet:
+
+```javascript
+import { AzureOpenAI } from 'openai';
+import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';
+
+// Make sure to set AZURE_OPENAI_ENDPOINT with the endpoint of your Azure resource.
+
+const credential = new DefaultAzureCredential();
+const scope = 'https://cognitiveservices.azure.com/.default';
+const azureADTokenProvider = getBearerTokenProvider(credential, scope);
+
+// Create client instance
+// 3) Create an Azure OpenAI client
+const openai = new AzureOpenAI({ azureADTokenProvider });
+
+// 4) Make API call and print response
+const result = await openai.chat.completions.create({
+  model: 'gpt-4-1106-preview',
+  messages: [{ role: 'user', content: 'Say hello!' }],
+});
+
+console.log(result.choices[0]!.message?.content);
+```
+
+3. Create Client Instance: Instantiate your `AzureOpenAI` with the endpoint and the credentials obtained from the `DefaultAzureCredential`.
+4. Make API Calls: Use the client to interact with Azure OpenAI services securely, without explicitly handling sensitive credentials.

learn-pr/advocates/intro-azure-openai-managed-identity-auth-javascript/includes/4-benefits-managed-identity-azure-openai.md

@@ -0,0 +1,40 @@
+When employing a Managed Identity, you need to specify the client ID of the user-managed identity when creating an instance of the `DefaultAzureCredential` or `ManagedIdentityCredential` class in your JavaScript application. The client ID value is established as an environment variable `$AZURE_CLIENT_ID` when the Managed Identity is set up.
+
+At first glance, it might seem that this is the only vital piece of information required for the connection, aside from the endpoint URL.
+
+```javascript
+import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
+import { AzureOpenAI } from "openai";
+
+// set environment variable AZURE_CLIENT_ID
+const credential = new DefaultAzureCredential();
+const scope = "https://cognitiveservices.azure.com/.default";
+const azureADTokenProvider = getBearerTokenProvider(credential, scope);
+
+const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
+const deployment = "<your Azure OpenAI deployment name>";
+const apiVersion = "2024-05-01-preview";
+const options = { azureADTokenProvider, deployment, apiVersion, endpoint }
+
+const client = new AzureOpenAI(options);
+
+```
+
+Let's evaluate the impact of a leaked client ID versus a leaked API key.
+
+An API key functions similarly to a regular password. If it's compromised, anyone with the key can access the resource. For Azure OpenAI, this means unrestricted use of AI models like GPT-4. If the network is publicly accessible, the security impact could be even greater.
+
+Conversely, if the client ID is leaked, the risks are minimal. This is because the client ID alone can't establish a connection to Azure OpenAI. To utilize a Managed Identity, the service must be operating on Azure and even if Azure OpenAI is public, you can't connect from a local environment or across a network using an application.
+
+Additionally, the following role assignment is configured for the Managed Identity:
+
+```sh
+az role assignment create --assignee $USER_MANAGED_ID_PRINCIPAL_ID \
+--scope $OPEN_AI_RESOURCE_ID \
+--role "Cognitive Services OpenAI User"
+```
+
+This configures the actions can be performed using this user ID (more on this later in the module). Here, the Cognitive Services OpenAI User role is assigned for Azure OpenAI services, limiting permissions to operations within Azure OpenAI.
+
+In summary, compared to the ramifications of a leaked API key, exploiting a leaked client ID involves several steps, making it harder for malicious actors to exploit. 
+For these reasons, Managed Identities offer a safer method to manage operations compared to API keys. It's recommended in the strongest possible terms that you use Managed Identity over API keys when authenticating to Azure OpenAI, or any other Azure service that supports Managed Identity.