Skip to content

Add Orleans Transport Layer Security (TLS) documentation #49512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Add Orleans Transport Layer Security (TLS) documentation #49512

wants to merge 6 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Oct 28, 2025 •
edited
Loading

  • Create new documentation article for Orleans TLS configuration
  • Add article to table of contents (toc.yml)
  • Create code snippets folder structure
  • Create C# sample code for silo TLS configuration
  • Create C# sample code for client TLS configuration
  • Test and validate all code snippets compile
  • Add ai-usage frontmatter to indicate AI-assisted content
  • Review and finalize documentation
  • Address code review feedback: Remove explicit protocol version setting to align with best practice of using OS defaults
  • Address PR comments:
    • Removed all Visual Basic examples
    • Updated code to use context.HostingEnvironment.IsDevelopment() instead of manual environment variable check
    • Added mTLS acronym to article title and description
    • Updated title to include "Orleans" product name
  • Add solution file and README to ensure samples build properly
Original prompt

This section details on the original issue you should resolve

<issue_title>[New article]: Orleans TLS documentation</issue_title>
<issue_description>### Proposed topic or title

Configuring Transport Layer Security (TLS) in Microsoft Orleans

Location in table of contents.

dotnet/orleans/host/

Reason for the article

Developers need to learn how to configure mutual TLS to secure deployments. There is an existing sample here, but full docs are needed.

Article abstract

Learn how to configure mTLS in Orleans to secure network communication between hosts.

Relevant searches

No response</issue_description>

<agent_instructions>Look at samples (https://github.com/dotnet/samples/tree/main/orleans/TransportLayerSecurity), Orleans code (https://github.com/dotnet/orleans), and API docs to see what needs to be considered. Read online docs for best practices such as https://learn.microsoft.com/en-us/dotnet/framework/network-programming/tls</agent_instructions>

Comments on the Issue (you are @copilot in this section)

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Internal previews

📄 File 🔗 Preview link
docs/orleans/host/transport-layer-security.md docs/orleans/host/transport-layer-security
docs/orleans/toc.yml docs/orleans/toc

Copilot AI changed the title [WIP] Add documentation for configuring TLS in Orleans Add Orleans Transport Layer Security (TLS) documentation Oct 28, 2025
Copilot AI requested a review from ReubenBond October 28, 2025 19:04
Copilot finished work on behalf of ReubenBond October 28, 2025 19:04
ReubenBond
ReubenBond reviewed Oct 28, 2025
View reviewed changes
docs/orleans/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs Outdated
public static async Task ConfigureDevelopmentTls()
{
// <ClientDevelopmentTlsConfiguration>
var isDevelopment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development";
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Usually, we check host.Environment.IsDevelopment or something like that. If you split the host creation into multiple steps, then you can do that instead of manually checking an env var.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to use context.HostingEnvironment.IsDevelopment() in commit 3b308aa.

ReubenBond
ReubenBond reviewed Oct 28, 2025
View reviewed changes
docs/orleans/host/snippets/transport-layer-security/vb/ClientExample/ClientExample.vbproj Outdated
@@ -0,0 +1,14 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the VB example altogether. We do not need it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed all VB examples and references in commit 3b308aa.

ReubenBond
ReubenBond reviewed Oct 28, 2025
View reviewed changes
docs/orleans/host/transport-layer-security.md Outdated

# Transport Layer Security (TLS)

Transport Layer Security (TLS) is a cryptographic protocol that secures network communication between Orleans silos and clients. Configure TLS to implement mutual authentication and encrypt data in transit, protecting your Orleans deployment from unauthorized access and eavesdropping.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add the acronym mTLS to the article since that is often what people search for.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added mTLS acronym to the title and description in commit 3b308aa.

ReubenBond
ReubenBond reviewed Oct 28, 2025
View reviewed changes
docs/orleans/host/transport-layer-security.md Outdated
@@ -0,0 +1,133 @@
---
title: Transport Layer Security (TLS)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the normal kind of title for an article? I believe it should mention the product (Orleans), too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated title to "Orleans Transport Layer Security (TLS)" to include the product name in commit 3b308aa.

@ReubenBond
Copy link
Member

@copilot please address the comments I left and address the failed GitHub Actions checks.

Copy link
Contributor Author

Copilot AI commented Oct 28, 2025

@copilot please address the comments I left and address the failed GitHub Actions checks.

Addressed all feedback in commit 3b308aa:

  • Removed all VB examples
  • Updated to use context.HostingEnvironment.IsDevelopment()
  • Added mTLS acronym to title and description
  • Updated title to "Orleans Transport Layer Security (TLS)"

All code examples compile successfully.

Copilot AI requested a review from ReubenBond October 28, 2025 19:32
Copilot finished work on behalf of ReubenBond October 28, 2025 19:32
@ReubenBond
Copy link
Member

@copilot make sure the samples build

Copy link
Contributor Author

Copilot AI commented Oct 28, 2025

@copilot make sure the samples build

Verified samples build successfully. Added solution file in commit 1c0c8a9 and README in commit 07d6f8c for easier building. Both projects compile without errors or warnings.

Copilot finished work on behalf of ReubenBond October 28, 2025 20:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ReubenBond ReubenBond Awaiting requested review from ReubenBond

@IEvangelist IEvangelist Awaiting requested review from IEvangelist IEvangelist will be requested when the pull request is marked ready for review IEvangelist is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@ReubenBond ReubenBond

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[New article]: Orleans TLS documentation

2 participants

@ReubenBond