Merge pull request #3423 from lindazqli/patch-27

Update openapi-spec.md

Author: JillGrant615

articles/ai-services/agents/how-to/tools/openapi-spec.md

@@ -6,7 +6,7 @@ services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
 ms.topic: how-to
-ms.date: 12/16/2024
+ms.date: 03/12/2025
 author: aahill
 ms.author: aahi
 zone_pivot_groups: selection-function-calling
@@ -25,7 +25,7 @@ OpenAPI Specified tool improves your function calling experience by providing st
 automated, and scalable API integrations that enhance the capabilities and efficiency of your agent. 
 [OpenAPI specifications](https://spec.openapis.org/oas/latest.html) provide a formal standard for 
 describing HTTP APIs. This allows people to understand how an API works, how a sequence of APIs 
-work together, generate client code, create tests, apply design standards, and more. Currently, we support 3 authentication types with the OpenAPI 3.0 specified tools: `anonymous`, `API key`, `managed identity`.
+work together, generate client code, create tests, apply design standards, and more. Currently, we support three authentication types with the OpenAPI 3.0 specified tools: `anonymous`, `API key`, `managed identity`.
 
 ### Usage support
 
@@ -42,17 +42,30 @@ work together, generate client code, create tests, apply design standards, and m
 
 ## Authenticating with API Key
 
-1. Verify that the OpenAPI spec supports API keys: it has `securitySchemes` section and has one scheme of type `apiKey`. For example:
+With API key authentication, you can authenticate your OpenAPI spec using various methods such as an API key or Bearer token. Only one API key security schema is supported per OpenAPI spec. If you need multiple security schemas, create multiple OpenAPI spec tools.
+
+1. Update your OpenAPI spec security schemas. it has a `securitySchemes` section and one scheme of type `apiKey`. For example:
+
    ```json
-       "securitySchemes": {
-          "apiKeyHeader": {
-                    "type": "apiKey",
-                    "name": "x-api-key",
-                    "in": "header"
-                }
-        }
+    "securitySchemes": {
+        "apiKeyHeader": {
+                "type": "apiKey",
+                "name": "x-api-key",
+                "in": "header"
+            }
+    }
+   ```
+
+   You usually only need to update the `name` field, which corresponds to the name of `key` in the connection. If the security schemes include multiple schemes, we recommend keeping only one of them.
+
+1. Update your OpenAPI spec to include a `security` section:
+   ```json
+   "security": [
+        {  
+        "apiKeyHeader": []  
+        }  
+    ]
    ```
-   If the security schemes include multiple schemes, we recommend keeping only one of them.
 
 1. Remove any parameter in the OpenAPI spec that needs API key, because API key will be stored and passed through a connection, as described later in this article.
 
@@ -72,7 +85,7 @@ work together, generate client code, create tests, apply design standards, and m
         :::image type="content" source="../../media/tools/bing/api-key-connection.png" alt-text="A screenshot of the custom keys selection for the AI project." lightbox="../../media/tools/bing/api-key-connection.png":::
 
    1. Enter the following information
-      - key: `name` of your security scheme. In this example, it should be `x-api-key`
+      - key: `name` field of your security scheme. In this example, it should be `x-api-key`
         ```json
                "securitySchemes": {
                   "apiKeyHeader": {
@@ -85,9 +98,41 @@ work together, generate client code, create tests, apply design standards, and m
       - value: YOUR_API_KEY
       - Connection name: YOUR_CONNECTION_NAME (You will use this connection name in the sample code below.)
       - Access: you can choose either *this project only* or *shared to all projects*. Just make sure in the sample code below, the project you entered connection string for has access to this connection.
-     
+
+1. Once you have created a connection, you can use it through the SDK or REST API. Use the tabs at the top of this article to see code examples.
+
+## Authenticating with managed identity (Microsoft Entra ID)
+
+[Microsoft Entra ID](/entra/fundamentals/whatis) is a cloud-based identity and access management service that your employees can use to access external resources. Microsoft Entra ID allows you to authenticate your APIs with additional security without the need to pass in API keys. Once you have set up managed identity authentication, it will authenticate through the Azure AI Service your agent is using. 
+
+To set up authenticating with Managed Identity:
+
+1. Enable the Azure AI Service of your agent has `system assigned managed identity` enabled.
+
+    :::image type="content" source="../../media/tools/managed-identity-portal.png" alt-text="A screenshot showing the managed identity selector in the Azure portal." lightbox="../../media/tools/managed-identity-portal.png":::
+
+1. Create a resource of the service you want to connect to through OpenAPI spec.
+
+1. Assign proper access to the resource.
+    1. Click **Access Control** for your resource
+       
+    1. Click **Add** and then **add role assignment** at the top of the screen.
+
+        :::image type="content" source="../../media/tools/role-assignment-portal.png" alt-text="A screenshot showing the role assignment selector in the Azure portal." lightbox="../../media/tools/role-assignment-portal.png":::
+        
+    1. Select the proper role assignment needed, usually it will require at least *READER* role. Then click **Next**.
+
+    1. Select **Managed identity** and then click **select members**.
+
+    1. In the managed identity dropdown menu, search for **Azure AI services** and then select the AI Service of your agent.
+
+    1. Click **Finish**.
+
+1. Once the setup is done, you can continue by using the tool through the SDK or REST API. Use the tabs at the top of this article to see code samples.
+
 ::: zone-end
 
+
 ::: zone pivot="code-example"
 ## Step 1: Create a project client
 Create a client object, which will contain the connection string for connecting to your AI project and other resources.