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.

Maintain and dispose HttpClient instance in tests to ensure proper resource management. The mock IHttpClientFactory now returns a dedicated HttpClient, which is disposed of in the test class's Dispose method.

…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.

mikaelweave · 2025-12-11T14:31:18Z

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

-            // If the request is a put or post and has a content-type, check that it's supported
-            if (httpContext.Request.Method.Equals(HttpMethod.Post.Method, StringComparison.OrdinalIgnoreCase) ||
-                httpContext.Request.Method.Equals(HttpMethod.Put.Method, StringComparison.OrdinalIgnoreCase))
+            if (!ShouldIgnoreValidation(httpContext))


This avoids format validation on token introspection endpoints

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

+            // Create mock HttpClientFactory that returns HttpClient for named client
+            var httpClientFactory = Substitute.For<IHttpClientFactory>();
+            httpClientFactory.CreateClient(DefaultTokenIntrospectionService.OidcConfigurationHttpClientName)
+                .Returns(new HttpClient());


To fix the problem, ensure that the instantiated HttpClient object in the test setup is disposed of properly. Since it is registered as the return value for the substitute's CreateClient method and potentially used throughout the life of the TokenIntrospectionControllerTests test class, the best solution is to store the HttpClient instance in a field, and dispose of it in the test class's Dispose() method (since the class already implements IDisposable).

Make the following changes in src/Microsoft.Health.Fhir.Shared.Api.UnitTests/Controllers/TokenIntrospectionControllerTests.cs:

Add a private field to hold the created HttpClient.

In the constructor, assign the new HttpClient to this field, and return it from the substitute as currently.

Implement or modify the Dispose() method of the test class so it disposes the field if it is not null.

No new imports are needed, as HttpClient and IDisposable are already imported.

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 this to the FY26\Q2\2Wk\2Wk12 milestone Dec 9, 2025

mikaelweave added the Enhancement Enhancement on existing functionality. label Dec 9, 2025

mikaelweave and others added 4 commits December 9, 2025 14:51

Refactor TokenIntrospectionControllerTests HttpClient usage

f5e7d63

Maintain and dispose HttpClient instance in tests to ensure proper resource management. The mock IHttpClientFactory now returns a dedicated HttpClient, which is disposed of in the test class's Dispose method.

Fix build issues introduced by codeql

9567a41

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

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

@@ -37,6 +37,7 @@
                     private readonly SigningCredentials _signingCredentials;
                     private readonly string _issuer = "https://test-issuer.com";
                     private readonly string _audience = "test-audience";
+                    private readonly HttpClient _httpClient;
                     public TokenIntrospectionControllerTests()
                     {
@@ -63,8 +64,9 @@
                         // Create mock HttpClientFactory that returns HttpClient for named client
                         var httpClientFactory = Substitute.For<IHttpClientFactory>();
+                        _httpClient = new HttpClient();
                         httpClientFactory.CreateClient(DefaultTokenIntrospectionService.OidcConfigurationHttpClientName)
-                            .Returns(new HttpClient());
+                            .Returns(_httpClient);
                         // Create introspection service
                         _introspectionService = new DefaultTokenIntrospectionService(
@@ -406,5 +407,10 @@
                     {
                         _rsa?.Dispose();
                     }
+                    public void Dispose()
+                    {
+                        _httpClient?.Dispose();
+                        _rsa?.Dispose();
+                    }
                 }
             }

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!

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!

Check warning

Copilot Autofix

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mikaelweave commented Dec 3, 2025 •

edited by azure-boards bot

Loading