From 25cf96b2b771619d5a1ff3a144a9cd19db8b5ad2 Mon Sep 17 00:00:00 2001 From: Matt Finkel Date: Fri, 31 Jul 2026 17:32:07 +0100 Subject: [PATCH 1/2] Document S3 environment credential resolution The S3 provider section only showed static credentials, so there was no indication that omitting the access key and secret key makes the api server resolve credentials from its environment instead. Add an Authentication subsection describing both credential modes, the resolution order, when resolution happens, and the fact that EKS Pod Identity is not supported. Signed-off-by: Matt Finkel --- docs/reference/configuration/file-storage.md | 32 ++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/reference/configuration/file-storage.md b/docs/reference/configuration/file-storage.md index b97a6157..39ee6769 100644 --- a/docs/reference/configuration/file-storage.md +++ b/docs/reference/configuration/file-storage.md @@ -46,6 +46,38 @@ dt.file-storage.s3.secret-key= dt.file-storage.s3.region=us-east-1 ``` +#### Authentication + +The `s3` provider supports two credential modes. + +**Static credentials.** Configure `dt.file-storage.s3.access-key` and `dt.file-storage.s3.secret-key`. +Both properties require each other. If you configure only one of them, Dependency-Track fails to start. +This mode works with any S3-compatible object store. + +**Environment credentials.** Omit both properties. Dependency-Track resolves credentials from its +environment instead, using the first of these sources that provides them: + +1. The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables +2. The shared AWS configuration file, `~/.aws/credentials` by default +3. IAM Roles for Service Accounts (IRSA) on Amazon EKS +4. Task roles on Amazon ECS +5. Instance profiles on Amazon EC2 + +```ini +dt.file-storage.provider=s3 +dt.file-storage.s3.endpoint=https://s3.us-east-1.amazonaws.com +dt.file-storage.s3.bucket=dtrack-files +dt.file-storage.s3.region=us-east-1 +``` + +Dependency-Track resolves credentials when it verifies the bucket during startup. +If no source provides credentials, startup fails. + +!!! note + Amazon EKS Pod Identity is not supported. The S3 client does not read the token file that the + Pod Identity Agent provides, and it rejects the agent's endpoint because that address is not a + loopback address. Use IRSA on Amazon EKS. + Configuration: - [`dt.file-storage.s3.endpoint`](properties.md#dtfile-storages3endpoint) From 14f706855ef583dedd70835b03bcdba2f16e4984 Mon Sep 17 00:00:00 2001 From: Matt Finkel Date: Fri, 7 Aug 2026 20:08:30 +0100 Subject: [PATCH 2/2] Document the S3 credentials-source property The api server change was reworked: ambient AWS credential resolution is now opt-in via dt.file-storage.s3.credentials-source=aws, and the default keeps the original behavior, including anonymous access when no credentials are configured. Describe all three modes. --- docs/reference/configuration/file-storage.md | 21 ++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/reference/configuration/file-storage.md b/docs/reference/configuration/file-storage.md index 39ee6769..3698a946 100644 --- a/docs/reference/configuration/file-storage.md +++ b/docs/reference/configuration/file-storage.md @@ -48,14 +48,20 @@ dt.file-storage.s3.region=us-east-1 #### Authentication -The `s3` provider supports two credential modes. +How the `s3` provider authenticates is controlled by `dt.file-storage.s3.credentials-source`, +which defaults to `static`. -**Static credentials.** Configure `dt.file-storage.s3.access-key` and `dt.file-storage.s3.secret-key`. -Both properties require each other. If you configure only one of them, Dependency-Track fails to start. +**Static credentials** (`credentials-source=static`, the default). Configure +`dt.file-storage.s3.access-key` and `dt.file-storage.s3.secret-key`. Both properties require +each other. If you configure only one of them, Dependency-Track fails to start. This mode works with any S3-compatible object store. -**Environment credentials.** Omit both properties. Dependency-Track resolves credentials from its -environment instead, using the first of these sources that provides them: +**Anonymous access.** With the `static` source, omitting both properties sends unsigned requests. +This is intended for S3-compatible object stores that allow anonymous access. Anonymous uploads +are limited to 5GiB per file. + +**AWS environment credentials** (`credentials-source=aws`). Dependency-Track resolves credentials +from its environment, using the first of these sources that provides them: 1. The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables 2. The shared AWS configuration file, `~/.aws/credentials` by default @@ -68,10 +74,12 @@ dt.file-storage.provider=s3 dt.file-storage.s3.endpoint=https://s3.us-east-1.amazonaws.com dt.file-storage.s3.bucket=dtrack-files dt.file-storage.s3.region=us-east-1 +dt.file-storage.s3.credentials-source=aws ``` Dependency-Track resolves credentials when it verifies the bucket during startup. -If no source provides credentials, startup fails. +If no source provides credentials, or if static credentials are configured alongside +`credentials-source=aws`, startup fails. !!! note Amazon EKS Pod Identity is not supported. The S3 client does not read the token file that the @@ -82,6 +90,7 @@ Configuration: - [`dt.file-storage.s3.endpoint`](properties.md#dtfile-storages3endpoint) - [`dt.file-storage.s3.bucket`](properties.md#dtfile-storages3bucket) +- [`dt.file-storage.s3.credentials-source`](properties.md#dtfile-storages3credentials-source) - [`dt.file-storage.s3.access-key`](properties.md#dtfile-storages3access-key) - [`dt.file-storage.s3.secret-key`](properties.md#dtfile-storages3secret-key) - [`dt.file-storage.s3.region`](properties.md#dtfile-storages3region)