.Net: Add UserSecurityContext to SK dotnet AzureOpenAIPromptExecutionSettings (#11656)

### Motivation and Context

Expose UserSecurityContext in SK dotnet via
AzureOpenAIPromptExecutionSettings as this is available in Azure only.

https://learn.microsoft.com/en-us/dotnet/api/azure.ai.openai.usersecuritycontext?view=azure-dotnet-preview

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [ ] The code builds clean without any errors or warnings
- [ ] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [ ] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄

---------

Co-authored-by: Roger Barreto <[email protected]>
Co-authored-by: Mark Wallace <[email protected]>

Author: 3 people

dotnet/src/Connectors/Connectors.AzureOpenAI.UnitTests/Services/AzureOpenAIChatCompletionServiceTests.cs

@@ -306,6 +306,49 @@ public async Task GetChatMessageContentsHandlesMaxTokensCorrectlyAsync(bool useN
         Assert.Equal(123, propertyValue.GetInt32());
     }
 
+    [Fact]
+    public async Task GetChatMessageContentsHandlesUserSecurityContextCorrectlyAsync()
+    {
+        // Arrange
+        var service = new AzureOpenAIChatCompletionService("deployment", "https://endpoint", "api-key", "model-id", this._httpClient);
+        var settings = new AzureOpenAIPromptExecutionSettings();
+
+#pragma warning disable AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+        var userSecurityContext = new UserSecurityContext()
+        {
+            ApplicationName = "My-AI-App",
+            SourceIP = "203.0.113.42",
+            EndUserId = "f3b8e23c-36a1-4e47-8f12-bd77a33f29b4",
+            EndUserTenantId = "8c946a0e-c75b-4f3a-b2e6-0d12e63c7e48"
+        };
+        settings.UserSecurityContext = userSecurityContext;
+
+        using var responseMessage = new HttpResponseMessage(HttpStatusCode.OK)
+        {
+            Content = new StringContent(AzureOpenAITestHelper.GetTestResponse("chat_completion_test_response.json"))
+        };
+        this._messageHandlerStub.ResponsesToReturn.Add(responseMessage);
+
+        // Act
+        var result = await service.GetChatMessageContentsAsync(new ChatHistory("System message"), settings);
+
+        // Assert
+        var requestContent = this._messageHandlerStub.RequestContents[0];
+
+        Assert.NotNull(requestContent);
+
+        var content = JsonSerializer.Deserialize<JsonElement>(Encoding.UTF8.GetString(requestContent));
+
+        Assert.True(content.TryGetProperty("user_security_context", out var propertyValue));
+
+        using JsonDocument doc = JsonDocument.Parse(propertyValue.GetRawText());
+        Assert.Equal(userSecurityContext.ApplicationName, doc.RootElement.GetProperty("application_name").GetString());
+        Assert.Equal(userSecurityContext.SourceIP, doc.RootElement.GetProperty("source_ip").GetString());
+        Assert.Equal(userSecurityContext.EndUserId, doc.RootElement.GetProperty("end_user_id").GetString());
+        Assert.Equal(userSecurityContext.EndUserTenantId, doc.RootElement.GetProperty("end_user_tenant_id").GetString());
+#pragma warning restore AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+    }
+
     [Theory]
     [InlineData("stream", "true")]
     [InlineData("stream_options", "{\"include_usage\":true}")]

dotnet/src/Connectors/Connectors.AzureOpenAI.UnitTests/Settings/AzureOpenAIPromptExecutionSettingsTests.cs

@@ -35,6 +35,7 @@ public void ItCreatesOpenAIExecutionSettingsWithCorrectDefaults()
         Assert.Null(executionSettings.TopLogprobs);
         Assert.Null(executionSettings.Logprobs);
         Assert.Null(executionSettings.AzureChatDataSource);
+        Assert.Null(executionSettings.UserSecurityContext);
         Assert.False(executionSettings.SetNewMaxCompletionTokensEnabled);
         Assert.Equal(maxTokensSettings, executionSettings.MaxTokens);
         Assert.Null(executionSettings.Store);
@@ -263,6 +264,7 @@ public void PromptExecutionSettingsFreezeWorksAsExpected()
         Assert.Throws<InvalidOperationException>(() => executionSettings.Store = false);
         Assert.Throws<NotSupportedException>(() => executionSettings.Metadata?.Add("bar", "foo"));
         Assert.Throws<InvalidOperationException>(() => executionSettings.SetNewMaxCompletionTokensEnabled = true);
+        Assert.Throws<InvalidOperationException>(() => executionSettings.UserSecurityContext = null);
 
         executionSettings!.Freeze(); // idempotent
         Assert.True(executionSettings.IsFrozen);

dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs

@@ -61,6 +61,13 @@ protected override ChatCompletionOptions CreateChatCompletionOptions(
 #pragma warning restore AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         }
 
+        if (azureSettings.UserSecurityContext is not null)
+        {
+#pragma warning disable AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+            options.SetUserSecurityContext(azureSettings.UserSecurityContext);
+#pragma warning restore AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+        }
+
         var responseFormat = GetResponseFormat(executionSettings);
         if (responseFormat is not null)
         {

dotnet/src/Connectors/Connectors.AzureOpenAI/Settings/AzureOpenAIPromptExecutionSettings.cs

@@ -4,6 +4,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 using System.Text.Json.Serialization;
+using Azure.AI.OpenAI;
 using Azure.AI.OpenAI.Chat;
 using Microsoft.SemanticKernel.Connectors.OpenAI;
 using Microsoft.SemanticKernel.Text;
@@ -16,6 +17,25 @@ namespace Microsoft.SemanticKernel.Connectors.AzureOpenAI;
 [JsonNumberHandling(JsonNumberHandling.AllowReadingFromString)]
 public sealed class AzureOpenAIPromptExecutionSettings : OpenAIPromptExecutionSettings
 {
+    /// <summary>
+    /// Get/Set the user security context which contains several parameters that describe the AI application itself, and the end user that interacts with the AI application.
+    /// These fields assist your security operations teams to investigate and mitigate security incidents by providing a comprehensive approach to protecting your AI applications.
+    /// <see href="https://learn.microsoft.com/en-us/azure/defender-for-cloud/gain-end-user-context-ai">Learn more</see> about protecting AI applications using Microsoft Defender for Cloud.
+    /// </summary>
+    [JsonIgnore]
+#pragma warning disable AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+    [Experimental("SKEXP0010")]
+    public UserSecurityContext? UserSecurityContext
+    {
+        get => this._userSecurityContext;
+        set
+        {
+            this.ThrowIfFrozen();
+            this._userSecurityContext = value;
+        }
+    }
+#pragma warning restore AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
     /// <summary>
     /// Enabling this property will enforce the new <c>max_completion_tokens</c> parameter to be send the Azure OpenAI API.
     /// </summary>
@@ -59,6 +79,7 @@ public override PromptExecutionSettings Clone()
         var settings = base.Clone<AzureOpenAIPromptExecutionSettings>();
         settings.AzureChatDataSource = this.AzureChatDataSource;
         settings.SetNewMaxCompletionTokensEnabled = this.SetNewMaxCompletionTokensEnabled;
+        settings.UserSecurityContext = this.UserSecurityContext;
         return settings;
     }
 
@@ -125,6 +146,9 @@ public static AzureOpenAIPromptExecutionSettings FromExecutionSettingsWithData(P
     [Experimental("SKEXP0010")]
     private AzureSearchChatDataSource? _azureChatDataSource;
     private bool _setNewMaxCompletionTokensEnabled;
+#pragma warning disable AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+    private UserSecurityContext? _userSecurityContext;
+#pragma warning restore AOAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
 
     #endregion
 }