SMART on FHIR Token Introspection Endpoint #5257

mikaelweave · 2025-12-03T19:36:40Z

Description

Implements RFC 7662 token introspection endpoint at /connect/introspect for SMART on FHIR server with swapple support for the introspection endpoint for alternate SMART configurations.

Key Features:

RFC 7662 compliant introspection endpoint supporting both OpenIddict (development) and external IdP tokens
Service abstraction pattern (ITokenIntrospectionService) enabling alternate authentication patterns
SMART on FHIR v1/v2 claim support (patient, fhirUser, raw_scope)
Bearer token authentication required via [Authorize] attribute
Integrated with existing audit logging infrastructure
Handles issuer variations (with/without trailing slash) for OpenIddict compatibility

Related issues

Addresses AB#174822

Testing

Unit Tests (12 tests - all passing):
Manual Testing

Test Coverage:

Controller layer: Parameter validation, HTTP status codes
Service layer: Token parsing, validation, claim extraction
Integration: Audit logging, authentication filters

FHIR Team Checklist

Update the title of the PR to be succinct and less than 65 characters
Add a milestone to the PR for the sprint that it is merged (i.e. add S47)
Tag the PR with the type of update: Bug, Build, Dependencies, Enhancement, New-Feature or Documentation
Tag the PR with Open source, Azure API for FHIR (CosmosDB or common code) or Azure Healthcare APIs (SQL or common code) to specify where this change is intended to be released.
Tag the PR with Schema Version backward compatible or Schema Version backward incompatible or Schema Version unchanged if this adds or updates Sql script which is/is not backward compatible with the code.
When changing or adding behavior, if your code modifies the system design or changes design assumptions, please create and include an ADR.
CI is green before merge
Review squash-merge requirements

Semver Change (docs)

Patch|Skip|Feature|Breaking (reason)

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs

src/Microsoft.Health.Fhir.Shared.Api/Controllers/TokenIntrospectionController.cs

src/Microsoft.Health.Fhir.Api/Features/Security/DefaultTokenIntrospectionService.cs

…d improve logging

…ment and enhance assertions

…ms verification

…ndpoint

…cy tests

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs

Updated `DefaultTokenIntrospectionService` to use `IHttpClientFactory` for managing `HttpClient` instances and initialized a shared `ConfigurationManager` for OpenID Connect configurations. Removed inline `ConfigurationManager` instantiation in token validation logic for consistency. Enhanced `TokenIntrospectionControllerTests` by mocking `IHttpClientFactory` with `NSubstitute` to support the updated service constructor. Refactored `TokenIntrospectionTests` to improve handling of unauthenticated requests, added skipping logic for in-process test servers, and leveraged existing test infrastructure. Removed `[Consumes]` attribute from `TokenIntrospectionController` to simplify content type handling. Replaced synchronous calls with asynchronous token validation to align with best practices. Added logging and validation for `httpClientFactory` dependency. Updated namespaces across files to support new functionality.

The test `GivenContentTypeNotFormEncoded_WhenIntrospecting_ThenReturnsUnsupportedMediaType` was removed from `TokenIntrospectionTests.cs`. This test validated that the introspection endpoint returned `UnsupportedMediaType` when the content type was not `application/x-www-form-urlencoded` (per RFC 7662). Its removal suggests that this behavior is no longer relevant or required in the codebase. Other tests, such as `GivenMultipleValidTokens_WhenIntrospecting_ThenEachReturnsCorrectClaims`, remain unchanged.

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs

Refactored `ValidateFormatParametersAttribute` to improve modularity by introducing `ShouldIgnoreValidation` for skipping validation on specific paths (e.g., `/CustomError`). Enhanced `Content-Type` validation for `POST`, `PUT`, and `PATCH` requests with better error handling for unsupported or missing headers. Updated `TokenIntrospectionController` to remove the `[Authorize]` attribute, allowing unauthenticated access to `/connect/introspect`. Added `[Consumes("application/x-www-form-urlencoded")]` to specify the expected content type. Removed a skipped test case and related code in `TokenIntrospectionTests` that validated unauthorized access to the token introspection endpoint, aligning with the updated authentication behavior.

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs

…token introspection test content handling

mikaelweave · 2025-12-09T13:17:28Z

/azp run

azure-pipelines · 2025-12-09T13:17:38Z

Azure Pipelines successfully started running 1 pipeline(s).

…oved clarity and maintainability

…on local IDisposable Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Switch to TryGetValue for safer JSON field access in TokenIntrospectionTests, replacing ContainsKey/indexer usage. Also remove the unused _testFhirClient field for code clarity.

…ionService

…ndpoint

mikaelweave · 2025-12-11T14:23:08Z

build/jobs/e2e-tests.yml

      'app_globalReaderUserApp_secret': $(app_globalReaderUserApp_secret)
      'app_globalWriterUserApp_id': $(app_globalWriterUserApp_id)
      'app_globalWriterUserApp_secret': $(app_globalWriterUserApp_secret)
+      'app_smartUserClient_id': $(app_smartUserClient_id)


needed for E2E tests that use SMART client

mikaelweave · 2025-12-11T14:23:46Z

build/jobs/provision-deploy.yml

            serviceName = $webAppName
            keyVaultName = "${{ parameters.keyVaultName }}".ToLower()
-            securityAuthenticationAuthority = "https://login.microsoftonline.com/$(tenant-id)"
+            securityAuthenticationAuthority = "https://sts.windows.net/$(tenant-id-guid)"


Our test env has been using an invalid authority for ... not sure how long. I reuse the authority in the OSS service to check the token so I had to fix the authority.

src/Microsoft.Health.Fhir.Api/Features/Filters/ValidateFormatParametersAttribute.cs

mikaelweave · 2025-12-11T14:34:48Z

src/Microsoft.Health.Fhir.Api/Features/Security/DefaultTokenIntrospectionService.cs

+    /// Default implementation of token introspection for OSS (single authority/audience).
+    /// PaaS can extend this class and override ValidateToken() to support multiple authorities.
+    /// </summary>
+    public class DefaultTokenIntrospectionService : ITokenIntrospectionService


Note - this service can be overriden downstream for token validation

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs

Converted all token introspection logic, endpoints, and tests to use async/await patterns. Updated ITokenIntrospectionService and DefaultTokenIntrospectionService to provide asynchronous methods. The controller endpoint now supports CancellationToken and awaits the introspection service. Replaced blocking OpenID Connect configuration retrieval with async calls. Updated all related unit tests to be asynchronous. These changes improve scalability and follow best practices for I/O-bound operations in ASP.NET Core.

…oken parameter

…ndpoint

Refactored TokenIntrospectionControllerTests to use a mocked ITokenIntrospectionService, removing direct JWT creation and cryptographic logic for simpler, more focused tests. Added a test to verify service invocation. Removed unused helpers and IDisposable. Updated .NET SDK version to 9.0.308. Added .runsettings and launchSettings.json files with environment variables for E2E and integration test configuration.

…ttps://github.com/microsoft/fhir-server into personal/mikaelw/smart-token-introspection-endpoint

mikaelweave · 2025-12-28T06:29:41Z

/azp run

azure-pipelines · 2025-12-28T06:29:58Z

Azure Pipelines successfully started running 1 pipeline(s).

… to include authorization header

… introspection

- Remove keyVaultName parameter and related logic from provision-deploy.yml. - Update Azure AD authority URL to use login.microsoftonline.com. - Add logic to restore Key Vaults in removed state before provisioning. - Eliminate retry helper usage for Cosmos DB and NSP steps; use direct cmdlets. - Remove inclusion of provision-healthcheck.yml template. - Clean up comment in DevelopmentIdentityProviderRegistrationExtensions.cs.

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs

…ttps://github.com/microsoft/fhir-server into personal/mikaelw/smart-token-introspection-endpoint

…ndpoint

…ersion

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs

…unity Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

…spection tests with detailed assertions

mikaelweave added 2 commits December 3, 2025 10:33

Add token introspection endpoint and related tests

a23bfe0

Refactor token introspection endpoint handling and add audit event type

fcf508b

mikaelweave changed the title ~~Personal/mikaelw/smart token introspection endpoint~~ SMART on FHIR Token Introspection Endpoint Dec 3, 2025

github-advanced-security bot found potential problems Dec 3, 2025

View reviewed changes

mikaelweave commented Dec 4, 2025

View reviewed changes

src/Microsoft.Health.Fhir.Shared.Api/Controllers/TokenIntrospectionController.cs Outdated Show resolved Hide resolved

Implement token introspection service and update controller to use it

6410e8f

github-advanced-security bot found potential problems Dec 5, 2025

View reviewed changes

mikaelweave and others added 6 commits December 5, 2025 14:07

Refactor DefaultTokenIntrospectionService to enhance extensibility an…

e005e0a

…d improve logging

Refactor scope claim retrieval for improved readability and efficiency

afb3e4c

Refactor TokenIntrospectionControllerTests to improve resource manage…

b7b2d53

…ment and enhance assertions

Add TokenIntrospectionTests for RFC 7662 compliance and standard clai…

a9d08c7

…ms verification

Merge branch 'main' into personal/mikaelw/smart-token-introspection-e…

fc13cc7

…ndpoint

Add Token Introspection Tests for RFC 7662 compliance and remove lega…

1e03cac

…cy tests

github-advanced-security bot found potential problems Dec 6, 2025

View reviewed changes

mikaelweave added 2 commits December 8, 2025 06:37

mikaelweave marked this pull request as ready for review December 8, 2025 17:25

mikaelweave requested a review from a team as a code owner December 8, 2025 17:25

github-advanced-security bot found potential problems Dec 8, 2025

View reviewed changes

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs Fixed Show fixed Hide fixed

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs Fixed Show fixed Hide fixed

github-advanced-security bot found potential problems Dec 8, 2025

View reviewed changes

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs Fixed Show fixed Hide fixed

Add smart user client credentials to E2E test variables and refactor …

5b23a53

…token introspection test content handling

mikaelweave force-pushed the personal/mikaelw/smart-token-introspection-endpoint branch from 6b7008b to 5b23a53 Compare December 9, 2025 13:16

mikaelweave and others added 3 commits December 9, 2025 11:05

Refactor token request handling in Token Introspection tests for impr…

4931b4d

…oved clarity and maintainability

Potential fix for code scanning alert no. 2964: Missing Dispose call …

5e497a5

…on local IDisposable Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Refactor JSON access in TokenIntrospectionTests

a6c28ed

Switch to TryGetValue for safer JSON field access in TokenIntrospectionTests, replacing ContainsKey/indexer usage. Also remove the unused _testFhirClient field for code clarity.

mikaelweave added Azure API for FHIR Label denotes that the issue or PR is relevant to the Azure API for FHIR Azure Healthcare APIs Label denotes that the issue or PR is relevant to the FHIR service in the Azure Healthcare APIs labels Dec 9, 2025

mikaelweave added 2 commits December 11, 2025 06:19

Add named HttpClient for OIDC configuration in DefaultTokenIntrospect…

5e7f434

…ionService

Merge branch 'main' into personal/mikaelw/smart-token-introspection-e…

a6ea92d

…ndpoint

mikaelweave commented Dec 11, 2025

View reviewed changes

src/Microsoft.Health.Fhir.Api/Features/Filters/ValidateFormatParametersAttribute.cs Outdated Show resolved Hide resolved

Refactor token introspection service documentation for clarity

cbf335a

mikaelweave commented Dec 11, 2025

View reviewed changes

Remove unused HttpClient field from TokenIntrospectionControllerTests

ad7f161

github-advanced-security bot found potential problems Dec 11, 2025

View reviewed changes

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs Fixed Show fixed Hide fixed

mikaelweave and others added 5 commits December 22, 2025 21:54

Refactor token introspection endpoint to remove unused cancellation t…

5cf5776

…oken parameter

Merge branch 'main' into personal/mikaelw/smart-token-introspection-e…

7ae0d86

…ndpoint

Merge branch 'personal/mikaelw/smart-token-introspection-endpoint' of h…

28cc5cc

…ttps://github.com/microsoft/fhir-server into personal/mikaelw/smart-token-introspection-endpoint

mikaelweave and others added 3 commits January 4, 2026 20:53

Remove token expiration check from introspection service; update test…

654340c

… to include authorization header

Add default scope claim names and configure OIDC HttpClient for token…

7fef30c

… introspection

github-advanced-security bot found potential problems Jan 9, 2026

View reviewed changes

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs Fixed Show fixed Hide fixed

src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs Fixed Show fixed Hide fixed

mikaelweave and others added 7 commits January 9, 2026 08:53

better understanding of validate

b6ef5f8

undo mistake change

eb7b7e3

fix copilot suggestions

1d6900d

Merge branch 'personal/mikaelw/smart-token-introspection-endpoint' of h…

b9f3197

…ttps://github.com/microsoft/fhir-server into personal/mikaelw/smart-token-introspection-endpoint

Merge branch 'main' into personal/mikaelw/smart-token-introspection-e…

8b2cdd4

…ndpoint

refactor: streamline Microsoft Graph module installation in cleanup job

d2796fa

fix: update Microsoft Graph module installation to use variable for v…

51caf60

…ersion

github-advanced-security bot found potential problems Jan 9, 2026

View reviewed changes

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs Fixed Show fixed Hide fixed

test/Microsoft.Health.Fhir.Shared.Tests.E2E/Rest/TokenIntrospectionTests.cs Fixed Show fixed Hide fixed

mikaelweave and others added 2 commits January 9, 2026 12:46

Potential fix for code scanning alert no. 3128: Missed 'using' opport…

5f4d87a

…unity Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

fix: update security authentication authority and enhance token intro…

6f942ad

…spection tests with detailed assertions

SMART on FHIR Token Introspection Endpoint #5257

Are you sure you want to change the base?

SMART on FHIR Token Introspection Endpoint #5257

Uh oh!

Conversation

mikaelweave commented Dec 3, 2025 • edited by azure-boards bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

Testing

FHIR Team Checklist

Semver Change (docs)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikaelweave commented Dec 9, 2025

Uh oh!

azure-pipelines bot commented Dec 9, 2025

Uh oh!

mikaelweave Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

mikaelweave Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mikaelweave Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mikaelweave commented Dec 28, 2025

Uh oh!

azure-pipelines bot commented Dec 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mikaelweave commented Dec 3, 2025 •

edited by azure-boards bot

Loading