AWS healthimaging documentation change
Summary
Complete restructuring of OIDC authentication documentation with detailed implementation steps for IAM role configuration, Lambda authorizer setup, and datastore creation. Added Python code example for Cognito token validation.
Security assessment
The changes document security-focused authentication mechanisms (OIDC/JWT validation) and IAM role federation patterns. While it adds security documentation, there is no evidence of addressing a specific vulnerability or security incident - this appears to be routine documentation of security best practices for a feature.
Diff
diff --git a/healthimaging/latest/devguide/dicomweb-oidc-requirements.md b/healthimaging/latest/devguide/dicomweb-oidc-requirements.md index 264773ed2..8c30351bb 100644 --- a//healthimaging/latest/devguide/dicomweb-oidc-requirements.md +++ b//healthimaging/latest/devguide/dicomweb-oidc-requirements.md @@ -5 +5 @@ -OIDC RequirementsConfigure Token Validation on the DatastoreRequest Format (HTTP)Required JWT Claims +1\. Configure IAM Roles for DICOMWeb API Access2\. Create and Configure Lambda Authorizer Function3\. Create a New Datastore with OIDC AuthenticationException CodesImplementation Example @@ -7 +7 @@ OIDC RequirementsConfigure Token Validation on the DatastoreRequest Format (HTTP -# Requirements for JWT authorization +# Set up an AWS Lambda authorizer for OIDC authentication @@ -9 +9 @@ OIDC RequirementsConfigure Token Validation on the DatastoreRequest Format (HTTP -## OIDC Requirements +This guide assumes you have already configured your Identity Provider (IdP) of choice to provide access tokens compatible with the requirements of the HealthImaging OIDC authentication feature. @@ -11 +11 @@ OIDC RequirementsConfigure Token Validation on the DatastoreRequest Format (HTTP -To access DICOMweb resources on an OIDC-enabled HealthImaging datastore, a client application must be authorized by an OpenID Connect / OAuth 2.0 identity provider (IdP) and present an OAuth 2.0 Bearer token (a JWT) in the Authorization header of each request. HealthImaging validates the token using one of the integration paths you configure on the datastore and then authorizes the request by assuming an IAM role mapped to the caller. +## 1\. Configure IAM Roles for DICOMWeb API Access @@ -13 +13,60 @@ To access DICOMweb resources on an OIDC-enabled HealthImaging datastore, a clien -###### Note +Before configuring the Lambda authorizer, create IAM roles for HealthImaging to assume when processing DICOMWeb API requests. The authorizer Lambda function returns one of these roles ARN after successful token verification, allowing HealthImaging to execute the requests with appropriate permissions. + + 1. Create IAM policies defining the desired DICOMWeb API privileges. Refer to the "[Using DICOMweb](https://docs.aws.amazon.com/healthimaging/latest/devguide/using-dicomweb.html)" section of the HealthImaging documentation for available permissions. + + 2. Create IAM roles that: + + * Attach these policies + + * Include a trust relationship allowing the AWS HealthImaging service principal (`medical-imaging.amazonaws.com`) to assume these roles. + + + + +Here is an example of a policy allowing associated roles to access to HealthImaging DICOMWeb read-only API: + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "MedicalImagingDicomWebOperations", + "Effect": "Allow", + "Action": [ + "medical-imaging:SearchDICOMInstances", + "medical-imaging:GetImageSetMetadata", + "medical-imaging:GetDICOMSeriesMetadata", + "medical-imaging:SearchDICOMStudies", + "medical-imaging:GetDICOMBulkdata", + "medical-imaging:SearchDICOMSeries", + "medical-imaging:GetDICOMInstanceMetadata", + "medical-imaging:GetDICOMInstance", + "medical-imaging:GetDICOMInstanceFrames" + ], + "Resource": "arn:aws:medical-imaging:{Region}:{Account}:datastore/{DatastoreId}" + } + ] + } + +Here is an example of the trust relationship policy that should be associated to the role(s): + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "OIDCRoleFederation", + "Effect": "Allow", + "Principal": { + "Service": "medical-imaging.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + } + +The Lambda authorizer you'll create in the next step can evaluate the token claims and return the ARN of the appropriate role. AWS HealthImaging will then impersonate this role to execute the DICOMWeb API request with the corresponding permissions. + +For example: + + * A token with "admin" claims might return an ARN for a role with full access @@ -15 +74 @@ To access DICOMweb resources on an OIDC-enabled HealthImaging datastore, a clien -OIDC augments but does not replace SigV4. You may continue using SigV4 unchanged. OIDC is available for DICOMweb APIs only. + * A token with "reader" claims might return an ARN for a role with read-only access @@ -17 +76 @@ OIDC augments but does not replace SigV4. You may continue using SigV4 unchanged -## Configure Token Validation on the Datastore + * A token with "department_A" claims might return an ARN for a role specific to that department's access level @@ -19 +77,0 @@ OIDC augments but does not replace SigV4. You may continue using SigV4 unchanged -Choose one validation path when you create (or update) a datastore: @@ -21 +78,0 @@ Choose one validation path when you create (or update) a datastore: -### Customer-managed Lambda authorizer (JWT) @@ -23 +79,0 @@ Choose one validation path when you create (or update) a datastore: - * Provide LambdaAuthorizerArn. HealthImaging invokes your Lambda with the incoming token; your function validates it and returns required claims plus an IAM role ARN to assume. @@ -25 +81 @@ Choose one validation path when you create (or update) a datastore: - * The Lambda must return within 1 second. +This mechanism allows you to map your IdP's authorization model to specific AWS HealthImaging permissions through IAM roles. @@ -27 +83 @@ Choose one validation path when you create (or update) a datastore: - * Add a resource-based policy to the function that allows invocation by HealthImaging (service principal medical-imaging.`region`.amazonaws.com) and, optionally, restricts calls to your datastore ARN. +## 2\. Create and Configure Lambda Authorizer Function @@ -29 +85 @@ Choose one validation path when you create (or update) a datastore: - * Enabling a Lambda authorizer on an existing datastore requires an AWS Support case. +Create a Lambda function that will verify the JWT token and return the appropriate IAM role ARN based on the token claims evaluation. This function is invoked by the health imaging service and passed an event that contains the HealthImaging datastore Id, the DICOMWeb operation, and the access token found in the HTTP request: @@ -31,0 +88,5 @@ Choose one validation path when you create (or update) a datastore: + { + "datastoreId": "{datastore id}", + "operation": "{Healthimaging API name e.g. GetDICOMInstance}", + "bearerToken": "{access token}" + } @@ -32,0 +94 @@ Choose one validation path when you create (or update) a datastore: +The HealthImaging expects the lambda authorizer function to return a JSON struct with the following structure: @@ -34 +95,0 @@ Choose one validation path when you create (or update) a datastore: -## Request Format (HTTP) @@ -36 +97,4 @@ Choose one validation path when you create (or update) a datastore: -Send the access token in the Authorization header: + { + "isTokenValid": {true or false}, + "roleArn": "{role arn or empty string meaning to deny the request explicitly}" + } @@ -38 +102 @@ Send the access token in the Authorization header: -###### Example of Get Operation - GetDICOMInstance +You can refer to the implementation example for more information. @@ -39,0 +104,18 @@ Send the access token in the Authorization header: +###### Note + +Because the DICOMWeb request is only answered after the access token is verified by the lambda authorizer, it is important that the execution of this function be as fast as possible to provide with the best DICOMWeb API response time. + +For the HealthImaging to be authorized to invoke the lambda authorizer function it must have a resource policy that allows HealthImaging service to invoke it. This resource policy can be created in the permission menu of the lambda configuration tab or Using AWS AWS CLI: + + + aws lambda add-permission \ + --function-name YourAuthorizerFunctionName \ + --statement-id HealthImagingInvoke \ + --action lambda:InvokeFunction \ + --principal medical-imaging.amazonaws.com + +This resource policy allows the HealthImaging service to invoke your Lambda authorizer when authenticating DICOMWeb API requests. + +###### Note + +The lambda resource policy can be updated later on with an "ArnLike" condition matching the ARN of a specific HealthImaging datastore. @@ -41,6 +123 @@ Send the access token in the Authorization header: - curl --request GET \ - 'service endpoint/datastore/datastore/studies/studies/series/series/instances/instances?imageSetId=imageSetId' \ - --header "Authorization: Bearer access token" \ - --header 'Accept: application/dicom; transfer-syntax=1.2.840.10008.1.2.1' \ - --output 'dicom-instance.dcm' \ - --fail-with-body +Here is an example of lambda resource policy: @@ -48 +124,0 @@ Send the access token in the Authorization header: -## Required JWT Claims @@ -50 +126,20 @@ Send the access token in the Authorization header: -For a DICOMweb request to succeed, the effective token/authorization payload must contain these claims: + { + "Version": "2012-10-17", + "Id": "default", + "Statement": [ + { + "Sid": "LambaAuthorizer-HealthImagingInvokePermission", + "Effect": "Allow", + "Principal": { + "Service": "medical-imaging.amazonaws.com" + }, + "Action": "lambda:InvokeFunction", + "Resource": "arn:aws:lambda:{Region}:{Account}::function:{LambdaAuthorizerFunctionName}", + "Condition": { + "ArnLike": { + "AWS:SourceArn": "arn:aws:medical-imaging:{Region}:{Account}:datastore/{DatastoreId}" + } + } + } + ] + } @@ -52 +147 @@ For a DICOMweb request to succeed, the effective token/authorization payload mus - * `exp` — Expiration. The current time must be before this value. +## 3\. Create a New Datastore with OIDC Authentication @@ -54 +149 @@ For a DICOMweb request to succeed, the effective token/authorization payload mus - * `iat` \- Issued at. Must be before the current time in UTC and must NOT be earlier than 12 hours before the current time in UTC (maximum token lifetime) +To enable OIDC authentication, you must create a new datastore using the AWS AWS CLI with the parameter "lambda-authorizer-arn". OIDC Authentication cannot be enabled on existing datastores without contacting AWS Support. @@ -55,0 +151 @@ For a DICOMweb request to succeed, the effective token/authorization payload mus +Here's an example of how to create a new datastore with OIDC authentication enabled: @@ -57,0 +154,241 @@ For a DICOMweb request to succeed, the effective token/authorization payload mus + aws medical-imaging create-datastore \ + --datastore-name YourDatastoreName \ + --lambda-authorizer-arn YourAuthorizerFunctionArn + +You can check if a specific datastore has OIDC authentication feature enabled by using the AWS AWS CLI get-datastore command, and verifying if the attribute "lambdaAuthorizerArn" is present: + + + aws medical-imaging get-datastore --datastore-id YourDatastoreId + + + { + "datastoreProperties": { + "datastoreId": YourdatastoreId, + "datastoreName": YourDatastoreName, + "datastoreStatus": "ACTIVE", + "lambdaAuthorizerArn": YourAuthorizerFunctionArn, + "datastoreArn": YourDatastoreArn, + "createdAt": "2025-09-30T14:16:04.015000-05:00", + "updatedAt": "2025-09-30T14:16:04.015000-05:00" + } + } +