From 2479d3c5f9057cae4430dcee064e2f7c66d5c98e Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Sat, 11 Apr 2026 17:24:14 +0800 Subject: [PATCH 1/2] Add OTLP client certificate auth details to dashboard config - Add client certificate authentication validation description - Add AllowedCertificates and CertificateAuthenticationOptions config options - Add Allowed certificates subsection with examples - Port changes from dotnet/docs-aspire#5196 --- .../content/docs/dashboard/configuration.mdx | 44 ++++++++++++++++++- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/src/frontend/src/content/docs/dashboard/configuration.mdx b/src/frontend/src/content/docs/dashboard/configuration.mdx index 53d54b8cb..54d7fdc99 100644 --- a/src/frontend/src/content/docs/dashboard/configuration.mdx +++ b/src/frontend/src/content/docs/dashboard/configuration.mdx @@ -145,17 +145,57 @@ For more information, see [Configure ASP.NET Core to work with proxy servers and ## OTLP -The OTLP endpoint authentication is configured with `Dashboard:Otlp:AuthMode`. The OTLP endpoint can be secured with an API key or [client certificate](http://learn.microsoft.com/aspnet/core/security/authentication/certauth) authentication. +The OTLP endpoint authentication is configured with `Dashboard:Otlp:AuthMode`. The OTLP endpoint can be secured with an API key or client certificate authentication. API key authentication works by requiring each OTLP request to have a valid `x-otlp-api-key` header value. It must match either the primary or secondary key. +Client certificate authentication validates the TLS connection's client certificate. When a request with a client certificate is received, two sets of validation are performed: + +- **ASP.NET Core certificate authentication validation:** By default this verifies that the certificate chains to a trusted root on the machine, the certificate hasn't expired, and that its Extended Key Usage value is appropriate for Client Authentication. For more information on this validation and how to configure it, see [Configure ASP.NET Core certificate validation](https://learn.microsoft.com/aspnet/core/security/authentication/certauth#configure-certificate-validation). +- **Optional explicit certificate allowlist:** You can optionally configure an explicit list of allowed certificates using `AllowedCertificates`. If `AllowedCertificates` is configured and a client certificate does not match any of the listed thumbprints, the request is rejected. If no allowed certificates are specified, all certificates that pass the minimum validation are accepted. + | Option | Description | |--------|-------------| | `Dashboard:Otlp:AuthMode`
Default: `Unsecured` | Can be set to `ApiKey`, `ClientCertificate` or `Unsecured`. `Unsecured` should only be used during local development. It's not recommended when hosting the dashboard publicly or in other settings. | | `Dashboard:Otlp:PrimaryApiKey`
Default: `null` | Specifies the primary API key. The API key can be any text, but a value with at least 128 bits of entropy is recommended. This value is required if auth mode is API key. | | `Dashboard:Otlp:SecondaryApiKey`
Default: `null` | Specifies the secondary API key. The API key can be any text, but a value with at least 128 bits of entropy is recommended. This value is optional. If a second API key is specified, then the incoming `x-otlp-api-key` header value can match either the primary or secondary key. | | `Dashboard:Otlp:SuppressUnsecuredMessage`
Default: `false` | Suppresses the unsecured message displayed in the dashboard when `Dashboard:Otlp:AuthMode` is `Unsecured`. This message should only be suppressed if an external frontdoor proxy is securing access to the endpoint. | -| `Dashboard:Otlp:AllowedCertificates`
Default: `null` | A list of allowed certificate rules for client certificate authentication. Each entry specifies a `Thumbprint` to match against. Only used when `Dashboard:Otlp:AuthMode` is `ClientCertificate`. | +| `Dashboard:Otlp:AllowedCertificates`
Default: `null` | Specifies a list of allowed client certificates. See [allowed certificates](#allowed-certificates) for more information. | +| Properties of [`CertificateAuthenticationOptions`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.authentication.certificate.certificateauthenticationoptions)
Default: `null` | Values inside configuration section `Dashboard:Otlp:CertificateAuthOptions:*` are bound to `CertificateAuthenticationOptions`, such as `AllowedCertificateTypes`. | + +### Allowed certificates + +When using client certificate authentication you can optionally configure an explicit list of allowed certificates using `AllowedCertificates`. Each allowed certificate in the `Dashboard:Otlp:AllowedCertificates` collection supports the following properties: + +| Property | Description | +|----------|-------------| +| `Thumbprint` (required) | The SHA256 thumbprint of the certificate to allow. | + +The following example shows how to configure allowed certificates using JSON configuration: + +```json title="JSON — appsettings.json" +{ + "Dashboard": { + "Otlp": { + "AllowedCertificates": [ + { + "Thumbprint": "HEX_SHA256_THUMBPRINT" + } + ] + } + } +} +``` + +Or using environment variables for configuration: + +```bash +export Dashboard__Otlp__AllowedCertificates__0__Thumbprint="HEX_SHA256_THUMBPRINT" +``` + + ## OTLP CORS From 661f0336023e8675dd6431787cebe74c96efc9e0 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Sat, 11 Apr 2026 17:45:20 +0800 Subject: [PATCH 2/2] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/frontend/src/content/docs/dashboard/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/dashboard/configuration.mdx b/src/frontend/src/content/docs/dashboard/configuration.mdx index 54d7fdc99..89fc6f45d 100644 --- a/src/frontend/src/content/docs/dashboard/configuration.mdx +++ b/src/frontend/src/content/docs/dashboard/configuration.mdx @@ -190,7 +190,7 @@ The following example shows how to configure allowed certificates using JSON con Or using environment variables for configuration: ```bash -export Dashboard__Otlp__AllowedCertificates__0__Thumbprint="HEX_SHA256_THUMBPRINT" +export DASHBOARD__OTLP__ALLOWEDCERTIFICATES__0__THUMBPRINT="HEX_SHA256_THUMBPRINT" ```