From 1e474722df54187b48037885bc694d014db5b8e2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 10 Oct 2025 07:44:44 +0000 Subject: [PATCH 1/6] Initial plan From 9133d9a9fc2deb69c794972458d1cc5d7c83f3e9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 10 Oct 2025 07:49:15 +0000 Subject: [PATCH 2/6] Document ClaimActions configuration for dashboard OIDC authentication Co-authored-by: JamesNK <303201+JamesNK@users.noreply.github.com> --- docs/fundamentals/dashboard/configuration.md | 87 +++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index 9f2235bb70..e433eb7bb9 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -1,7 +1,7 @@ --- title: Aspire dashboard configuration description: Aspire dashboard configuration options -ms.date: 04/15/2025 +ms.date: 10/10/2025 ms.topic: reference --- @@ -91,11 +91,96 @@ Browser token authentication works by the frontend asking for a token. The token | `Dashboard:Frontend:OpenIdConnect:UsernameClaimType` | `preferred_username` | Specifies one or more claim types that should be used to display the authenticated user's username. Can be a single claim type or a comma-delimited list of claim types. | | `Dashboard:Frontend:OpenIdConnect:RequiredClaimType` | `null` | Specifies the claim that must be present for authorized users. Authorization fails without this claim. This value is optional. | | `Dashboard:Frontend:OpenIdConnect:RequiredClaimValue` | `null` | Specifies the value of the required claim. Only used if `Dashboard:Frontend:OpenIdConnect:RequireClaimType` is also specified. This value is optional. | +| `Dashboard:Frontend:OpenIdConnect:ClaimActions` | `null` | An array of claim actions to configure how claims are mapped from the OpenID Connect user info endpoint. Each claim action can map JSON properties to claims. This value is optional. | | `Authentication:Schemes:OpenIdConnect:Authority` | `null` | URL to the identity provider (IdP). | | `Authentication:Schemes:OpenIdConnect:ClientId` | `null` | Identity of the relying party (RP). | | `Authentication:Schemes:OpenIdConnect:ClientSecret` | `null` | A secret that only the real RP would know. | | Other properties of | `null` | Values inside configuration section `Authentication:Schemes:OpenIdConnect:*` are bound to `OpenIdConnectOptions`, such as `Scope`. | +### Claim actions + +Claim actions configure how claims are mapped from the JSON returned by the OpenID Connect user info endpoint to the user's claims identity. Each claim action in the `Dashboard:Frontend:OpenIdConnect:ClaimActions` array supports the following properties: + +| Property | Description | +|--|--| +| `ClaimType` (required) | The claim type to create. | +| `JsonKey` (required) | The JSON key to map from. | +| `SubKey` (optional) | The sub-key within the JSON key to map from. Used when the value is nested within another JSON object. | +| `IsUnique` (optional) | When `true`, ensures only one claim of this type exists. If a claim already exists, it won't be added again. Defaults to `false`. | +| `ValueType` (optional) | The claim value type. Defaults to `string`. | + +The following JSON example shows how to configure claim actions to map role claims: + +```json +{ + "Authentication": { + "Schemes": { + "OpenIdConnect": { + "Authority": "https://id.example.com", + "ClientId": "aspire-dashboard", + "ClientSecret": "secret", + "GetClaimsFromUserInfoEndpoint": true, + "Scope": [ + "roles" + ] + } + } + }, + "Dashboard": { + "Frontend": { + "AuthMode": "OpenIdConnect", + "OpenIdConnect": { + "RequiredClaimType": "role", + "RequiredClaimValue": "AspireAdmin", + "ClaimActions": [ + { + "ClaimType": "role", + "JsonKey": "role" + } + ] + } + } + } +} +``` + +The following example shows the equivalent configuration using environment variables: + +```bash +export Dashboard__Frontend__AuthMode="OpenIdConnect" +export Dashboard__Frontend__OpenIdConnect__ClaimActions__0__ClaimType="role" +export Dashboard__Frontend__OpenIdConnect__ClaimActions__0__JsonKey="role" +export Dashboard__Frontend__OpenIdConnect__RequiredClaimType="role" +export Dashboard__Frontend__OpenIdConnect__RequiredClaimValue="AspireAdmin" +export Authentication__Schemes__OpenIdConnect__Authority="https://id.example.com" +export Authentication__Schemes__OpenIdConnect__ClientId="aspire-dashboard" +export Authentication__Schemes__OpenIdConnect__ClientSecret="secret" +export Authentication__Schemes__OpenIdConnect__GetClaimsFromUserInfoEndpoint="true" +export Authentication__Schemes__OpenIdConnect__Scope__0="roles" +``` + +For more complex scenarios, you can map nested JSON properties using `SubKey`: + +```json +{ + "Dashboard": { + "Frontend": { + "OpenIdConnect": { + "ClaimActions": [ + { + "ClaimType": "department", + "JsonKey": "profile", + "SubKey": "department" + } + ] + } + } + } +} +``` + +This configuration maps the `department` value from a JSON structure like `{ "profile": { "department": "Engineering" } }` to a `department` claim. + > [!NOTE] > Additional configuration may be required when using `OpenIdConnect` as authentication mode behind a reverse-proxy that terminates SSL. Check if you need `ASPIRE_DASHBOARD_FORWARDEDHEADERS_ENABLED` to be set to `true`. > From 38180f253de0b5bedc54f5f419fc1af9a1d9c0f4 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 10 Oct 2025 15:58:40 +0800 Subject: [PATCH 3/6] Apply suggestion from @JamesNK --- docs/fundamentals/dashboard/configuration.md | 22 -------------------- 1 file changed, 22 deletions(-) diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index e433eb7bb9..8abecacf16 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -159,28 +159,6 @@ export Authentication__Schemes__OpenIdConnect__GetClaimsFromUserInfoEndpoint="tr export Authentication__Schemes__OpenIdConnect__Scope__0="roles" ``` -For more complex scenarios, you can map nested JSON properties using `SubKey`: - -```json -{ - "Dashboard": { - "Frontend": { - "OpenIdConnect": { - "ClaimActions": [ - { - "ClaimType": "department", - "JsonKey": "profile", - "SubKey": "department" - } - ] - } - } - } -} -``` - -This configuration maps the `department` value from a JSON structure like `{ "profile": { "department": "Engineering" } }` to a `department` claim. - > [!NOTE] > Additional configuration may be required when using `OpenIdConnect` as authentication mode behind a reverse-proxy that terminates SSL. Check if you need `ASPIRE_DASHBOARD_FORWARDEDHEADERS_ENABLED` to be set to `true`. > From bebff40758ad2b3ca7205e47a400769a8d88a2b8 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 10 Oct 2025 15:59:53 +0800 Subject: [PATCH 4/6] Apply suggestion from @JamesNK --- docs/fundamentals/dashboard/configuration.md | 37 +------------------- 1 file changed, 1 insertion(+), 36 deletions(-) diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index 8abecacf16..ded25added 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -109,42 +109,7 @@ Claim actions configure how claims are mapped from the JSON returned by the Open | `IsUnique` (optional) | When `true`, ensures only one claim of this type exists. If a claim already exists, it won't be added again. Defaults to `false`. | | `ValueType` (optional) | The claim value type. Defaults to `string`. | -The following JSON example shows how to configure claim actions to map role claims: - -```json -{ - "Authentication": { - "Schemes": { - "OpenIdConnect": { - "Authority": "https://id.example.com", - "ClientId": "aspire-dashboard", - "ClientSecret": "secret", - "GetClaimsFromUserInfoEndpoint": true, - "Scope": [ - "roles" - ] - } - } - }, - "Dashboard": { - "Frontend": { - "AuthMode": "OpenIdConnect", - "OpenIdConnect": { - "RequiredClaimType": "role", - "RequiredClaimValue": "AspireAdmin", - "ClaimActions": [ - { - "ClaimType": "role", - "JsonKey": "role" - } - ] - } - } - } -} -``` - -The following example shows the equivalent configuration using environment variables: +The following example shows how to configure claim actions using environment variables: ```bash export Dashboard__Frontend__AuthMode="OpenIdConnect" From eb921f406006a48a893d32393c80913da49c36b3 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 10 Oct 2025 16:00:15 +0800 Subject: [PATCH 5/6] Apply suggestion from @JamesNK --- docs/fundamentals/dashboard/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index ded25added..140ab4fde0 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -91,7 +91,7 @@ Browser token authentication works by the frontend asking for a token. The token | `Dashboard:Frontend:OpenIdConnect:UsernameClaimType` | `preferred_username` | Specifies one or more claim types that should be used to display the authenticated user's username. Can be a single claim type or a comma-delimited list of claim types. | | `Dashboard:Frontend:OpenIdConnect:RequiredClaimType` | `null` | Specifies the claim that must be present for authorized users. Authorization fails without this claim. This value is optional. | | `Dashboard:Frontend:OpenIdConnect:RequiredClaimValue` | `null` | Specifies the value of the required claim. Only used if `Dashboard:Frontend:OpenIdConnect:RequireClaimType` is also specified. This value is optional. | -| `Dashboard:Frontend:OpenIdConnect:ClaimActions` | `null` | An array of claim actions to configure how claims are mapped from the OpenID Connect user info endpoint. Each claim action can map JSON properties to claims. This value is optional. | +| `Dashboard:Frontend:OpenIdConnect:ClaimActions` | `null` | A collection of claim actions to configure how claims are mapped from the OpenID Connect user info endpoint. Each claim action can map JSON properties to claims. This value is optional. | | `Authentication:Schemes:OpenIdConnect:Authority` | `null` | URL to the identity provider (IdP). | | `Authentication:Schemes:OpenIdConnect:ClientId` | `null` | Identity of the relying party (RP). | | `Authentication:Schemes:OpenIdConnect:ClientSecret` | `null` | A secret that only the real RP would know. | From 7fff1ec60f4c9fae1b721cc7ad08634621666b79 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 10 Oct 2025 16:04:28 +0800 Subject: [PATCH 6/6] Update configuration.md --- docs/fundamentals/dashboard/configuration.md | 41 +++++++++++++------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index 140ab4fde0..c5cec73ccb 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -97,9 +97,14 @@ Browser token authentication works by the frontend asking for a token. The token | `Authentication:Schemes:OpenIdConnect:ClientSecret` | `null` | A secret that only the real RP would know. | | Other properties of | `null` | Values inside configuration section `Authentication:Schemes:OpenIdConnect:*` are bound to `OpenIdConnectOptions`, such as `Scope`. | +> [!NOTE] +> Additional configuration may be required when using `OpenIdConnect` as authentication mode behind a reverse-proxy that terminates SSL. Check if you need `ASPIRE_DASHBOARD_FORWARDEDHEADERS_ENABLED` to be set to `true`. +> +> For more information, see [Configure ASP.NET Core to work with proxy servers and load balancers](/aspnet/core/host-and-deploy/proxy-load-balancer). + ### Claim actions -Claim actions configure how claims are mapped from the JSON returned by the OpenID Connect user info endpoint to the user's claims identity. Each claim action in the `Dashboard:Frontend:OpenIdConnect:ClaimActions` array supports the following properties: +Claim actions configure how claims are mapped from the JSON returned by the OpenID Connect user info endpoint to the user's claims identity. Each claim action in the `Dashboard:Frontend:OpenIdConnect:ClaimActions` collection supports the following properties: | Property | Description | |--|--| @@ -109,26 +114,32 @@ Claim actions configure how claims are mapped from the JSON returned by the Open | `IsUnique` (optional) | When `true`, ensures only one claim of this type exists. If a claim already exists, it won't be added again. Defaults to `false`. | | `ValueType` (optional) | The claim value type. Defaults to `string`. | -The following example shows how to configure claim actions using environment variables: +The following example shows how to configure claim actions using JSON configuration: + +```json +{ + "Dashboard": { + "Frontend": { + "OpenIdConnect": { + "ClaimActions": [ + { + "ClaimType": "role", + "JsonKey": "role" + } + ] + } + } + } +} +``` + +Or using environment variables for configuration: ```bash -export Dashboard__Frontend__AuthMode="OpenIdConnect" export Dashboard__Frontend__OpenIdConnect__ClaimActions__0__ClaimType="role" export Dashboard__Frontend__OpenIdConnect__ClaimActions__0__JsonKey="role" -export Dashboard__Frontend__OpenIdConnect__RequiredClaimType="role" -export Dashboard__Frontend__OpenIdConnect__RequiredClaimValue="AspireAdmin" -export Authentication__Schemes__OpenIdConnect__Authority="https://id.example.com" -export Authentication__Schemes__OpenIdConnect__ClientId="aspire-dashboard" -export Authentication__Schemes__OpenIdConnect__ClientSecret="secret" -export Authentication__Schemes__OpenIdConnect__GetClaimsFromUserInfoEndpoint="true" -export Authentication__Schemes__OpenIdConnect__Scope__0="roles" ``` -> [!NOTE] -> Additional configuration may be required when using `OpenIdConnect` as authentication mode behind a reverse-proxy that terminates SSL. Check if you need `ASPIRE_DASHBOARD_FORWARDEDHEADERS_ENABLED` to be set to `true`. -> -> For more information, see [Configure ASP.NET Core to work with proxy servers and load balancers](/aspnet/core/host-and-deploy/proxy-load-balancer). - ## OTLP authentication The OTLP endpoint authentication is configured with `Dashboard:Otlp:AuthMode`. The OTLP endpoint can be secured with an API key or [client certificate](/aspnet/core/security/authentication/certauth) authentication.