Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

fix(iam): route long-term access keys to owning accounts (#2319)

Saatvik Arya02898cf5e2d3
diff --git a/docs/configuration/advanced/application-yml.md b/docs/configuration/advanced/application-yml.md
index 58bcfa49fd..4dac5fddbe 100644
--- a/docs/configuration/advanced/application-yml.md
+++ b/docs/configuration/advanced/application-yml.md
@@ -87,7 +87,7 @@ floci:
# - localhost.localstack.cloud
auth:
- validate-signatures: false # Set to true to enforce AWS SigV4 validation
+ validate-signatures: false # Set to true to verify S3 presigned URL signatures
presign-secret: local-emulator-secret # HMAC secret for S3 pre-signed URL verification
tls:
diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.md
index 5672e6627b..42b9a9259d 100644
--- a/docs/configuration/docker-compose.md
+++ b/docs/configuration/docker-compose.md
@@ -173,7 +173,7 @@ The most frequently set variables when running Floci as a Docker image:
| `FLOCI_STORAGE_MODE` | `memory` | `memory`, `persistent`, `hybrid`, or `wal` |
| `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Directory for persistent storage |
| `FLOCI_SERVICES_DOCKER_NETWORK` | _(none)_ | Docker network for spawned containers (Lambda, ElastiCache, RDS, OpenSearch, MSK) |
-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify AWS request signatures |
+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify S3 presigned URL signatures |
| `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove Lambda containers after each invocation |
For the complete list of every `FLOCI_*` variable, see [Environment Variables Reference](./environment-variables.md).
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
index f4ef6860fe..c3deefaf33 100644
--- a/docs/configuration/environment-variables.md
+++ b/docs/configuration/environment-variables.md
@@ -22,7 +22,7 @@ Floci is configured exclusively through environment variables. Every option belo
| Variable | Default | Description |
|---|---|---|
-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | When `true`, verifies AWS Signature V4 on every request. Leave `false` for local development |
+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | When `true`, verifies S3 presigned URL signatures |
| `FLOCI_AUTH_PRESIGN_SECRET` | `local-emulator-secret` | Secret used to sign and verify pre-signed URLs |
## Browser CORS
diff --git a/docs/configuration/multi-account.md b/docs/configuration/multi-account.md
index ff4fc7097f..215d984b0b 100644
--- a/docs/configuration/multi-account.md
+++ b/docs/configuration/multi-account.md
@@ -4,10 +4,12 @@ Floci supports full per-account resource isolation out of the box. Resources cre
## How It Works
-Every incoming request carries an AWS SigV4 `Authorization` header. Floci reads the **Access Key ID** (AKID) from that header and applies one simple rule:
+Every incoming request carries an AWS SigV4 `Authorization` header. Floci reads the **Access Key ID** (AKID) from that header and resolves the account in this order:
-> **If the AKID is exactly 12 digits, it is used as the account ID.**
-> Any other key format (e.g. `AKIAIOSFODNN7EXAMPLE`) falls back to `FLOCI_DEFAULT_ACCOUNT_ID`.
+1. An exactly 12-digit AKID is used directly as the account ID.
+2. An active long-term IAM access key resolves to the account that owns it.
+3. A live STS temporary credential resolves to its recorded account.
+4. Any other key falls back to `FLOCI_DEFAULT_ACCOUNT_ID`.
```
Authorization: AWS4-HMAC-SHA256 Credential=111111111111/20260510/us-east-1/sqs/aws4_request, ...
@@ -20,6 +22,12 @@ Once the account ID is determined, every storage read and write is transparently
!!! note "Same convention as LocalStack"
This 12-digit AKID → account ID rule matches LocalStack's multi-account behavior, so existing multi-account test setups work without changes.
+## Long-Term IAM Credentials
+
+Active access keys created through IAM route requests back to the account that owns the key. This lets a client keep using its generated `AKIA…` credentials instead of replacing the access key ID with a synthetic 12-digit account ID.
+
+Account selection is AKID-based and is not proof that the caller possesses the corresponding secret. This extends Floci's existing local-emulator trust model for 12-digit AKIDs; do not treat account namespaces as a security boundary between mutually untrusted clients.
+
## Temporary Credentials (AssumeRole)
STS temporary credentials are also routed to the correct account. When you call `AssumeRole` (or `AssumeRoleWithWebIdentity`, `AssumeRoleWithSAML`, `GetFederationToken`), Floci issues a temporary `ASIA…` access key and remembers which account it belongs to:
@@ -33,11 +41,11 @@ Account 111111111111 ──AssumeRole arn:aws:iam::222222222222:role/Deployer─
ASIA… temp key ──CreateTable orders──▶ stored as 222222222222/...::orders ◀──┘
```
-This makes the cross-account `AssumeRole`-then-provision pattern (e.g. CloudFormation deploying into a target account) work locally exactly as it does in AWS. Resolution precedence is: **12-digit AKID → account ID; otherwise temporary-session lookup → `FLOCI_DEFAULT_ACCOUNT_ID`.**
+This makes the cross-account `AssumeRole`-then-provision pattern (e.g. CloudFormation deploying into a target account) work locally exactly as it does in AWS.
## Default Behavior (Single Account)
-If you use any non-12-digit credentials (e.g. `test`, `AKIA…`), all requests resolve to the default account ID:
+If a credential is not a 12-digit account ID, an active IAM access key, or a live STS session (for example, `test`), requests resolve to the default account ID:
```bash
FLOCI_DEFAULT_ACCOUNT_ID=000000000000 # default
@@ -151,16 +159,16 @@ Background workers (Lambda event-source pollers, DynamoDB TTL sweeper, MSK readi
## Signature Validation
-By default Floci **does not** validate SigV4 signatures — only the access key ID matters for account resolution. The secret access key can be any non-empty string.
+Floci does not currently perform general SigV4 validation for `Authorization` headers. Only the access key ID matters for account resolution, so the secret access key can be any non-empty string.
-To enforce real signature validation:
+`FLOCI_AUTH_VALIDATE_SIGNATURES` currently applies only to S3 presigned URL validation. It does not authenticate general service requests or protect IAM and STS account routing. To validate S3 presigned URLs:
```bash
FLOCI_AUTH_VALIDATE_SIGNATURES=true
FLOCI_AUTH_PRESIGN_SECRET=your-secret # for pre-signed URL verification
```
-When `validate-signatures` is `false` (the default), account isolation still works correctly — the AKID is extracted from the `Authorization` header regardless of whether the signature itself is verified.
+When `validate-signatures` is `false` (the default), S3 presigned URL signatures are not verified. Account routing remains AKID-based regardless of this setting.
## Persistence and Account Isolation
@@ -170,6 +178,6 @@ Storage keys are namespaced per account at the persistence layer. When using `pe
| Variable | Default | Description |
|---|---|---|
-| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Account ID used when the AKID is not exactly 12 digits |
+| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Account ID used when the AKID does not resolve directly or through a stored credential |
| `FLOCI_DEFAULT_REGION` | `us-east-1` | Region used when not derivable from the `Authorization` header |
-| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Enforce SigV4 signature verification |
+| `FLOCI_AUTH_VALIDATE_SIGNATURES` | `false` | Verify S3 presigned URL signatures |
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java b/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java
index 3010d66ddf..53f96a8d0b 100644
--- a/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/AccountContextFilter.java
@@ -17,8 +17,8 @@ import java.util.Optional;
* downstream filters (e.g. IAM enforcement) can rely on the context being set.
*
* <p>Account resolution precedence: a 12-digit access key ID is used directly as
- * the account; otherwise temporary credentials (e.g. assumed-role {@code ASIA...}
- * keys) are looked up in the session store via {@link SessionAccountLookup}; if
+ * the account; otherwise IAM and temporary credentials (e.g. assumed-role {@code ASIA...}
+ * keys) are looked up via {@link SessionAccountLookup}; if
* neither matches, the configured default account applies.
*/
@Provider
@@ -66,13 +66,13 @@ public class AccountContextFilter implements ContainerRequestFilter {
/**
* Applies the account-resolution precedence. A 12-digit AKID is already reflected in
* {@code resolvedDefault} (the account or default returned by {@link AccountResolver});
- * for any other key shape, a live session lookup takes precedence before falling back.
+ * for any other key shape, an IAM or live-session lookup takes precedence before falling back.
*/
private String resolveAccount(String akid, String resolvedDefault) {
if (akid != null && !akid.matches("\\d{12}")) {
- Optional<String> sessionAccount = sessionAccountLookup.resolveAccountId(akid);
- if (sessionAccount.isPresent()) {
- return sessionAccount.get();
+ Optional<String> credentialAccount = sessionAccountLookup.resolveAccountId(akid);
+ if (credentialAccount.isPresent()) {
+ return credentialAccount.get();
}
}
return resolvedDefault;
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java b/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java
index 47ce083747..bb3388f806 100644
--- a/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/SessionAccountLookup.java
@@ -3,8 +3,7 @@ package io.github.hectorvent.floci.core.common;
import java.util.Optional;
/**
- * Port that maps an STS temporary access key ID (e.g. {@code ASIA...}) to the AWS
- * account the request should resolve to.
+ * Port that maps an IAM or STS access key ID to the AWS account the request should resolve to.
*
* <p>Declared in {@code core.common} so {@link AccountContextFilter} can route
* assumed-role and other temporary credentials to the correct account without
@@ -14,8 +13,8 @@ import java.util.Optional;
public interface SessionAccountLookup {
/**
- * Returns the account ID associated with the given temporary access key ID,
- * or {@link Optional#empty()} if it is not a known, live session.
+ * Returns the account ID associated with the given access key ID, or
+ * {@link Optional#empty()} if it is not a known, active credential.
*/
Optional<String> resolveAccountId(String accessKeyId);
}
diff --git a/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java b/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java
index 7ce91deb54..65e11461d6 100644
--- a/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java
+++ b/src/main/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackend.java
@@ -31,6 +31,9 @@ import java.util.stream.Collectors;
*/
public class AccountAwareStorageBackend<V> implements StorageBackend<String, V> {
+ /** A stored value together with its owning AWS account and account-relative key. */
+ public record AccountEntry<T>(String accountId, String key, T value) {}
+
private final StorageBackend<String, V> delegate;
private final Instance<RequestContext> requestContextInstance;
private final String defaultAccountId;
@@ -129,6 +132,27 @@ public class AccountAwareStorageBackend<V> implements StorageBackend<String, V>
return result;
}
+ /**
+ * Returns entries across every account while preserving the account that owns each logical key.
+ * The filter receives the account-relative key. Keys without a 12-digit ASCII account prefix,
+ * including legacy keys that contain slashes, are returned unchanged under the configured
+ * default account. Unlike {@link #get}, this scan does not migrate legacy entries.
+ */
+ public List<AccountEntry<V>> scanAllAccountEntries(Predicate<String> keyFilter) {
+ List<AccountEntry<V>> result = new ArrayList<>();
+ for (String rawKey : delegate.keys()) {
+ boolean hasAccountPrefix = hasAccountPrefix(rawKey);
+ String accountId = hasAccountPrefix ? rawKey.substring(0, 12) : defaultAccountId;
+ String logicalKey = hasAccountPrefix ? rawKey.substring(13) : rawKey;
+ if (!keyFilter.test(logicalKey)) {
+ continue;
+ }
+ delegate.get(rawKey).ifPresent(value ->
+ result.add(new AccountEntry<>(accountId, logicalKey, value)));
+ }
+ return result;
+ }
+
/**
* Returns all entries across every account as a map of logical-key (account prefix stripped)
* to value. Entries without a slash-prefixed account segment are skipped.
@@ -325,4 +349,17 @@ public class AccountAwareStorageBackend<V> implements StorageBackend<String, V>
private String prefixed(String key) {
return prefix() + "/" + key;
}
+
+ private static boolean hasAccountPrefix(String key) {
+ if (key.length() < 13 || key.charAt(12) != '/') {
+ return false;
+ }
+ for (int i = 0; i < 12; i++) {
+ char character = key.charAt(i);
+ if (character < '0' || character > '9') {
+ return false;
+ }
+ }
+ return true;
+ }
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java b/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java
index 68eabbcb22..6e5bd8fcc7 100644
--- a/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java
+++ b/src/main/java/io/github/hectorvent/floci/services/iam/IamService.java
@@ -1631,15 +1631,21 @@ public class IamService implements SessionAccountLookup {
}
/**
- * Resolves the account a temporary access key belongs to: the account encoded in the
- * session's role (or federated-user) ARN when present, otherwise the caller account captured
- * at mint time. Returns empty for unknown or expired sessions so callers fall back to the
- * default account.
+ * Resolves the account an IAM or temporary access key belongs to. Long-term IAM access keys
+ * resolve from their owning account namespace. Temporary credentials resolve from the account
+ * encoded in the session's role (or federated-user) ARN when present, otherwise the caller
+ * account captured at mint time. Returns empty for unknown, inactive, or expired credentials.
*/
@Override
public Optional<String> resolveAccountId(String accessKeyId) {
if (!isTemporaryAccessKey(accessKeyId)) {
- return Optional.empty();
+ if (accessKeyId == null || !(accessKeys instanceof AccountAwareStorageBackend<AccessKey> aware)) {
+ return Optional.empty();
+ }
+ return aware.scanAllAccountEntries(accessKeyId::equals).stream()
+ .filter(entry -> "Active".equals(entry.value().getStatus()))
+ .map(AccountAwareStorageBackend.AccountEntry::accountId)
+ .findFirst();
}
Optional<SessionCredential> sessionOpt = findSessionAnyAccount(accessKeyId);
if (sessionOpt.isEmpty()) {
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java b/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java
index 428912542f..e2b1fbf976 100644
--- a/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java
+++ b/src/test/java/io/github/hectorvent/floci/core/common/AccountContextFilterTest.java
@@ -104,6 +104,29 @@ class AccountContextFilterTest {
assertEquals("us-west-2", requestContext.getRegion());
}
+ @Test
+ void resolvesIamAccessKeyToOwningAccount() {
+ sessionAccounts.put("AKIAEXAMPLEACCESSKEY", "333344445555");
+ ContainerRequestContext ctx = mockContext(
+ "AWS4-HMAC-SHA256 Credential=AKIAEXAMPLEACCESSKEY/20260617/us-west-2/kms/aws4_request, "
+ + "SignedHeaders=host, Signature=abc",
+ null
+ );
+ filter.filter(ctx);
+ assertEquals("333344445555", requestContext.getAccountId());
+ assertEquals("us-west-2", requestContext.getRegion());
+ }
+
+ @Test
+ void resolvesIamAccessKeyFromPresignedCredential() {
+ sessionAccounts.put("AKIAPRESIGNEDACCESSKEY", "444455556666");
+ ContainerRequestContext ctx = mockContext(null,
+ "AKIAPRESIGNEDACCESSKEY/20260617/eu-central-1/s3/aws4_request");
+ filter.filter(ctx);
+ assertEquals("444455556666", requestContext.getAccountId());
+ assertEquals("eu-central-1", requestContext.getRegion());
+ }
+
@Test
void twelveDigitAkidWinsOverSessionLookup() {
sessionAccounts.put("000000000001", "999999999999");
diff --git a/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java b/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java
index 92a1f92a79..2e9edfa962 100644
--- a/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java
+++ b/src/test/java/io/github/hectorvent/floci/core/storage/AccountAwareStorageBackendTest.java
@@ -5,6 +5,7 @@ import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Map;
import java.util.Optional;
+import java.util.Set;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -158,4 +159,47 @@ class AccountAwareStorageBackendTest {
assertEquals(Optional.empty(), raw.get("us-east-1::Orders"),
"the superseded legacy key must be deleted, not left to collide again later");
}
+
+ @Test
+ void scanAllAccountEntriesPreservesOwnersAndTreatsNonAwsPrefixesAsLegacy() {
+ InMemoryStorage<String, String> raw = new InMemoryStorage<>();
+ raw.put("123456789012/us-east-1::api-a", "account-a");
+ raw.put("210987654321/us-east-1::api-b", "account-b");
+ raw.put("legacy/path", "legacy");
+ raw.put("12345678901/short", "short-prefix");
+ raw.put("1234567890123/long", "long-prefix");
+ raw.put("123456789012/unicode", "unicode-prefix");
+
+ AccountAwareStorageBackend<String> storage =
+ new AccountAwareStorageBackend<>(raw, null, "000000000000");
+
+ List<AccountAwareStorageBackend.AccountEntry<String>> entries =
+ storage.scanAllAccountEntries(key -> true);
+
+ assertEquals(Set.of(
+ new AccountAwareStorageBackend.AccountEntry<>("123456789012", "us-east-1::api-a", "account-a"),
+ new AccountAwareStorageBackend.AccountEntry<>("210987654321", "us-east-1::api-b", "account-b"),
+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "legacy/path", "legacy"),
+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "12345678901/short", "short-prefix"),
+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "1234567890123/long", "long-prefix"),
+ new AccountAwareStorageBackend.AccountEntry<>(
+ "000000000000", "123456789012/unicode", "unicode-prefix")),
+ Set.copyOf(entries));
+ }
+
+ @Test
+ void scanAllAccountEntriesFiltersAccountRelativeKeys() {
+ InMemoryStorage<String, String> raw = new InMemoryStorage<>();
+ raw.put("123456789012/us-east-1::api-a", "account-a");
+ raw.put("210987654321/eu-west-1::api-b", "account-b");
+ raw.put("us-east-1::legacy", "legacy");
+
+ AccountAwareStorageBackend<String> storage =
+ new AccountAwareStorageBackend<>(raw, null, "000000000000");
+
+ assertEquals(Set.of(
+ new AccountAwareStorageBackend.AccountEntry<>("123456789012", "us-east-1::api-a", "account-a"),
+ new AccountAwareStorageBackend.AccountEntry<>("000000000000", "us-east-1::legacy", "legacy")),
+ Set.copyOf(storage.scanAllAccountEntries(key -> key.startsWith("us-east-1::"))));
+ }
}
diff --git a/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java b/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java
index e3a094c4eb..b5ecef9d83 100644
--- a/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/iam/IamServiceTest.java
@@ -36,11 +36,11 @@ class IamServiceTest {
return iamService(seedDeployerPrincipal, new InMemoryStorage<>());
}
- private static IamService iamService(boolean seedDeployerPrincipal, InMemoryStorage<String, AccessKey> accessKeys) {
+ private static IamService iamService(boolean seedDeployerPrincipal, StorageBackend<String, AccessKey> accessKeys) {
return iamService(seedDeployerPrincipal, accessKeys, new InMemoryStorage<>());
}
- private static IamService iamService(boolean seedDeployerPrincipal, InMemoryStorage<String, AccessKey> accessKeys,
+ private static IamService iamService(boolean seedDeployerPrincipal, StorageBackend<String, AccessKey> accessKeys,
StorageBackend<String, SessionCredential> sessions) {
return new IamService(
new InMemoryStorage<>(),
@@ -500,12 +500,28 @@ class IamServiceTest {
}
@Test
- void resolveAccountIdDoesNotScanSessionsForLongTermAccessKey() {
- CountingAccountAwareSessionStorage sessions = new CountingAccountAwareSessionStorage();
- IamService service = iamService(false, new InMemoryStorage<>(), sessions);
+ void resolveAccountIdUsesLongTermAccessKeyOwnerAccount() {
+ AccountAwareStorageBackend<AccessKey> accessKeys = new AccountAwareStorageBackend<>(
+ new InMemoryStorage<>(), null, "000000000000");
+ AccessKey accessKey = new AccessKey("AKIAIOSFODNN7EXAMPLE", "secret", "worker");
+ accessKeys.putForAccount("111122223333", accessKey.getAccessKeyId(), accessKey);
+
+ IamService service = iamService(false, accessKeys, new InMemoryStorage<>());
+
+ assertEquals("111122223333", service.resolveAccountId(accessKey.getAccessKeyId()).orElseThrow());
+ }
+
+ @Test
+ void resolveAccountIdIgnoresInactiveLongTermAccessKey() {
+ AccountAwareStorageBackend<AccessKey> accessKeys = new AccountAwareStorageBackend<>(
+ new InMemoryStorage<>(), null, "000000000000");
+ AccessKey accessKey = new AccessKey("AKIAINACTIVEEXAMPLE", "secret", "worker");
+ accessKey.setStatus("Inactive");
+ accessKeys.putForAccount("111122223333", accessKey.getAccessKeyId(), accessKey);
+
+ IamService service = iamService(false, accessKeys, new InMemoryStorage<>());
- assertTrue(service.resolveAccountId("AKIAIOSFODNN7EXAMPLE").isEmpty());
- assertEquals(0, sessions.scanAllAccountsAsMapCalls);
+ assertTrue(service.resolveAccountId(accessKey.getAccessKeyId()).isEmpty());
}
private static final class CountingAccountAwareSessionStorage