KMS: Add a way to get an `IKey` reference from an `Alias` `ARN`

[BalmungSan]

Describe the feature

Currently, there is no way to get a proper IKey reference from an Alias ARN, that would produce a proper IAM PolicyStatement.

This would be especially useful for cross-account situations where the current available options like Key.fromLookup and Alias.fromAliasName are not sufficient.

Use Case

My current use case is creating a Lambda ESM from an encrypted cross-account Kinesis Stream.

From the external account, granting the permissions to the Stream and Key was pretty easy thanks to the existing CDK constructs.
On the reader account, however, we originally thought that we could centralize all the cross-account stuff in our custom Kinesis L3 Stream construct, and that the Lambda one would just create a KinesisEventSource without caring about the IStream origin. Sadly, that was not the case since there was no way to get a reference to the external account KMS Alias that would create a correct IAM PolicyStatement.

We tried the following CDK code:

const streamArn = Stack.of(this).formatArn({
  account: externalAccountId,
  service: 'kinesis',
  resource: 'stream',
  resourceName: streamName
})

const keyArn = Stack.of(this).formatArn({
  account: externalAccountId,
  service: 'kms',
  resource: 'alias',
  resourceName: `${streamName}-key`
})

const stream = Stream.fromStreamAttributes(this, 'external-stream', {
  streamArn,
  // Sadly, this doesn't produce the correct policy, and we have to explicitly modify the lambda policy.
  encryptionKey: Key.fromKeyArn(this, 'external-stream-key', keyArn)
})

But that created this IAM PolicyStatement (which is wrong):

{
  "Action": "kms:Decrypt",
  "Resource": "arn:aws:kms:<region>:<external-account-id>:alias/<stream-name>-key",
  "Effect": "Allow"
}

Thus, we had to expose the cross-account information to the Lambda module, and explicitly grant the correct IAM PolicyStatement.

// Workaround for lack of cross-account KMS alias lookup.
lambda.addToRolePolicy(
  new PolicyStatement({
    actions: ['kms:Decrypt'],
    resources: [
      Stack.of(this).formatArn({
        account: externalAccountId,
        service: 'kms',
        resource: 'key',
        resourceName: '*'
      })
    ],
    conditions: {
      'ForAnyValue:StringEquals': {
        'kms:ResourceAliases': `alias/${streamName}-key`
      }
    }
  })
)

---

Of course, another option would have been to use the external Key ARN instead of the Alias one. However, since Key's ARN values are not predictable, and we deploy this same Stack in multiple regions in multiple environments, we would need to have a hardcoded map of values. And we believe that is a worse solution since it is brittle and error-prone.

Proposed Solution

A static method like Key.fromAliasArn or Alias.fromArn that would return an IKey reference pointing to that Alias, and whose grant methods would produce a proper PolicyStatement with a kms:ResourceAliases condition.

Other Information

This feels related to #28284 & #8822

And, it is likely to be a recurring problem, since the official AWS recommendation is to use multiple accounts, and when sharing data, for example, using Kinesis Streams, it is a security best practice to encrypt it using KMS Keys.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.243.0

AWS CDK CLI version

2.1111.0

Environment details (OS name and version, etc.)

Any

[pahud]

Hi @BalmungSan,

Issue at a glance — how it fails:

┌──────────────────────────────────────────────────────┐
│ Path A: Key.fromKeyArn(aliasArn)                     │
│                                                      │
│ User passes arn:aws:kms:...:alias/my-key             │
│         │                                            │
│         ▼                                            │
│ splitArn extracts resourceName = "my-key" (truthy)   │
│         │                                            │
│         ▼                                            │
│ ❌ No validation that resource type = "key"           │
│         │                                            │
│         ▼                                            │
│ Grant uses alias ARN as Resource directly             │
│ ──▶ "Resource": "arn:...:alias/my-key"               │
│ ──▶ IAM ignores this — KMS grants require key ARNs   │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│ Path B: Alias.fromAliasName("alias/my-key")          │
│                                                      │
│ ✅ Correct condition: kms:ResourceAliases             │
│         │                                            │
│         ▼                                            │
│ ❌ Resource ARN built via Stack.of(scope)             │
│    ──▶ "Resource": "arn:...:222222222222:key/*"       │
│                              ^^^^^^^^^^^^             │
│    Uses LOCAL account, not external 111111111111      │
│         │                                            │
│         ▼                                            │
│ Cross-account decrypt fails — wrong account in ARN   │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│ Path C: Alias.fromAliasArn() ← MISSING               │
│                                                      │
│ Would parse account/region from alias ARN            │
│         │                                            │
│         ▼                                            │
│ ✅ "Resource": "arn:...:111111111111:key/*"            │
│ ✅ "Condition": kms:ResourceAliases = alias/my-key    │
└──────────────────────────────────────────────────────┘

I was able to reproduce this locally. Here's what I found:

1. Key.fromKeyArn silently accepts alias ARNs because it only validates that a resourceName exists in the ARN, not that the resource type is key. This produces an invalid IAM policy with the alias ARN as the resource — IAM doesn't recognize alias ARNs in KMS policy resource fields.

2. Alias.fromAliasName does produce correct kms:ResourceAliases conditions (with the @aws-cdk/aws-kms:applyImportedAliasPermissionsToPrincipal feature flag), but it uses Stack.of(scope) to build the grant resource ARN — which always resolves to the local account. For cross-account scenarios, this means the kms:key/* resource ARN points to the wrong account.

In my opinion, the right fix involves two things:

• A new Alias.fromAliasArn() static method that parses the alias ARN to extract account/region and returns an IAlias whose grant* methods produce correct cross-account policies with kms:ResourceAliases conditions
• A validation improvement in Key.fromKeyArn to reject alias ARNs with a clear error message

This is related to #28284 (cross-account KMS alias grants for Secrets Manager) and #8822 (which led to fromAliasName being added), but is a distinct feature request since neither existing method handles the alias-ARN-to-cross-account-grant path.

We need a PR here. The implementation would primarily live in alias.ts. The new fromAliasArn method would follow the same pattern as the existing fromAliasName but use Stack.of(scope).splitArn() to extract account and region from the provided ARN for the grant resource.

Let me get this with a PR.