Enable user pool group access to storage and modify owner access syntax (#1104)

Author: edwardfoyle

.changeset/spicy-bulldogs-itch.md

@@ -0,0 +1,6 @@
+---
+'@aws-amplify/backend-storage': minor
+'@aws-amplify/backend-auth': minor
+---
+
+Enable auth group access to storage and change syntax for specifying owner-based access

packages/backend-auth/API.md

@@ -46,7 +46,7 @@ export type AuthLoginWithFactoryProps = Omit<AuthProps['loginWith'], 'externalPr
 };
 
 // @public (undocumented)
-export type BackendAuth = ResourceProvider<AuthResources> & ResourceAccessAcceptorFactory<AuthRoleName>;
+export type BackendAuth = ResourceProvider<AuthResources> & ResourceAccessAcceptorFactory<AuthRoleName | string>;
 
 // @public
 export const defineAuth: (props: AmplifyAuthProps) => ConstructFactory<BackendAuth>;

packages/backend-auth/src/factory.ts

@@ -23,7 +23,7 @@ import { UserPool, UserPoolOperation } from 'aws-cdk-lib/aws-cognito';
 import { AmplifyUserError } from '@aws-amplify/platform-core';
 
 export type BackendAuth = ResourceProvider<AuthResources> &
-  ResourceAccessAcceptorFactory<AuthRoleName>;
+  ResourceAccessAcceptorFactory<AuthRoleName | string>;
 
 export type AmplifyAuthProps = Expand<
   Omit<AuthProps, 'outputStorageStrategy' | 'loginWith'> & {
@@ -126,12 +126,24 @@ class AmplifyAuthGenerator implements ConstructContainerEntryGenerator {
 
     const authConstructMixin: BackendAuth = {
       ...authConstruct,
+      /**
+       * Returns a resourceAccessAcceptor for the given role
+       * @param roleIdentifier Either the auth or unauth role name or the name of a UserPool group
+       */
       getResourceAccessAcceptor: (
-        roleName: AuthRoleName
+        roleIdentifier: AuthRoleName | string
       ): ResourceAccessAcceptor => ({
-        identifier: `${roleName}ResourceAccessAcceptor`,
+        identifier: `${roleIdentifier}ResourceAccessAcceptor`,
         acceptResourceAccess: (policy: Policy) => {
-          const role = authConstruct.resources[roleName];
+          const role = roleNameIsAuthRoleName(roleIdentifier)
+            ? authConstruct.resources[roleIdentifier]
+            : authConstruct.resources.groups?.[roleIdentifier]?.role;
+          if (!role) {
+            throw new AmplifyUserError('InvalidResourceAccessConfig', {
+              message: `No auth IAM role found for "${roleIdentifier}".`,
+              resolution: `If you are trying to configure UserPool group access, ensure that the group name is specified correctly.`,
+            });
+          }
           policy.attachToRole(role);
         },
       }),
@@ -140,6 +152,13 @@ class AmplifyAuthGenerator implements ConstructContainerEntryGenerator {
   };
 }
 
+const roleNameIsAuthRoleName = (roleName: string): roleName is AuthRoleName => {
+  return (
+    roleName === 'authenticatedUserIamRole' ||
+    roleName === 'unauthenticatedUserIamRole'
+  );
+};
+
 /**
  * Provide the settings that will be used for authentication.
  */

packages/backend-storage/API.md

@@ -33,19 +33,23 @@ export type AmplifyStorageTriggerEvent = 'onDelete' | 'onUpload';
 // @public
 export const defineStorage: (props: AmplifyStorageFactoryProps) => ConstructFactory<ResourceProvider<StorageResources>>;
 
+// @public
+export type EntityId = 'identity';
+
 // @public
 export type StorageAccessBuilder = {
     authenticated: StorageActionBuilder;
     guest: StorageActionBuilder;
-    owner: StorageActionBuilder;
+    group: (groupName: string) => StorageActionBuilder;
+    entity: (entityId: EntityId) => StorageActionBuilder;
     resource: (other: ConstructFactory<ResourceProvider & ResourceAccessAcceptorFactory>) => StorageActionBuilder;
 };
 
 // @public (undocumented)
 export type StorageAccessDefinition = {
     getResourceAccessAcceptor: (getInstanceProps: ConstructFactoryGetInstanceProps) => ResourceAccessAcceptor;
     actions: StorageAction[];
-    ownerPlaceholderSubstitution: string;
+    idSubstitution: string;
 };
 
 // @public (undocumented)

packages/backend-storage/src/access_builder.test.ts

@@ -10,11 +10,15 @@ import {
 
 void describe('storageAccessBuilder', () => {
   const resourceAccessAcceptorMock = mock.fn();
+  const groupAccessAcceptorMock = mock.fn();
 
   const getResourceAccessAcceptorMock = mock.fn(
     // allows us to get proper typing on the mock args
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    (_: string) => resourceAccessAcceptorMock
+    (roleName: string) =>
+      roleName === 'testGroupName'
+        ? groupAccessAcceptorMock
+        : resourceAccessAcceptorMock
   );
 
   const getConstructFactoryMock = mock.fn(
@@ -50,7 +54,7 @@ void describe('storageAccessBuilder', () => {
       'write',
       'delete',
     ]);
-    assert.equal(accessDefinition.ownerPlaceholderSubstitution, '*');
+    assert.equal(accessDefinition.idSubstitution, '*');
     assert.equal(
       accessDefinition.getResourceAccessAcceptor(stubGetInstanceProps),
       resourceAccessAcceptorMock
@@ -75,7 +79,7 @@ void describe('storageAccessBuilder', () => {
       'write',
       'delete',
     ]);
-    assert.equal(accessDefinition.ownerPlaceholderSubstitution, '*');
+    assert.equal(accessDefinition.idSubstitution, '*');
     assert.equal(
       accessDefinition.getResourceAccessAcceptor(stubGetInstanceProps),
       resourceAccessAcceptorMock
@@ -89,19 +93,17 @@ void describe('storageAccessBuilder', () => {
       'unauthenticatedUserIamRole'
     );
   });
-  void it('builds storage access definition for owner', () => {
-    const accessDefinition = roleAccessBuilder.owner.to([
-      'read',
-      'write',
-      'delete',
-    ]);
+  void it('builds storage access definition for IdP identity', () => {
+    const accessDefinition = roleAccessBuilder
+      .entity('identity')
+      .to(['read', 'write', 'delete']);
     assert.deepStrictEqual(accessDefinition.actions, [
       'read',
       'write',
       'delete',
     ]);
     assert.equal(
-      accessDefinition.ownerPlaceholderSubstitution,
+      accessDefinition.idSubstitution,
       '${cognito-identity.amazonaws.com:sub}'
     );
     assert.equal(
@@ -133,10 +135,23 @@ void describe('storageAccessBuilder', () => {
       'write',
       'delete',
     ]);
-    assert.equal(accessDefinition.ownerPlaceholderSubstitution, '*');
+    assert.equal(accessDefinition.idSubstitution, '*');
     assert.equal(
       accessDefinition.getResourceAccessAcceptor(stubGetInstanceProps),
       resourceAccessAcceptorMock
     );
   });
+
+  void it('builds storage access definition for user pool groups', () => {
+    const accessDefinition = roleAccessBuilder
+      .group('testGroupName')
+      .to(['read', 'write']);
+
+    assert.deepStrictEqual(accessDefinition.actions, ['read', 'write']);
+    assert.equal(accessDefinition.idSubstitution, '*');
+    assert.equal(
+      accessDefinition.getResourceAccessAcceptor(stubGetInstanceProps),
+      groupAccessAcceptorMock
+    );
+  });
 });

packages/backend-storage/src/access_builder.ts

@@ -11,29 +11,37 @@ export const roleAccessBuilder: StorageAccessBuilder = {
     to: (actions) => ({
       getResourceAccessAcceptor: getAuthRoleResourceAccessAcceptor,
       actions,
-      ownerPlaceholderSubstitution: '*',
+      idSubstitution: '*',
     }),
   },
   guest: {
     to: (actions) => ({
       getResourceAccessAcceptor: getUnauthRoleResourceAccessAcceptor,
       actions,
-      ownerPlaceholderSubstitution: '*',
+      idSubstitution: '*',
     }),
   },
-  owner: {
+  group: (groupName) => ({
+    to: (actions) => ({
+      getResourceAccessAcceptor: (getInstanceProps) =>
+        getUserRoleResourceAccessAcceptor(getInstanceProps, groupName),
+      actions,
+      idSubstitution: '*',
+    }),
+  }),
+  entity: () => ({
     to: (actions) => ({
       getResourceAccessAcceptor: getAuthRoleResourceAccessAcceptor,
       actions,
-      ownerPlaceholderSubstitution: '${cognito-identity.amazonaws.com:sub}',
+      idSubstitution: '${cognito-identity.amazonaws.com:sub}',
     }),
-  },
+  }),
   resource: (other) => ({
     to: (actions) => ({
       getResourceAccessAcceptor: (getInstanceProps) =>
         other.getInstance(getInstanceProps).getResourceAccessAcceptor(),
       actions,
-      ownerPlaceholderSubstitution: '*',
+      idSubstitution: '*',
     }),
   }),
 };
@@ -56,19 +64,19 @@ const getUnauthRoleResourceAccessAcceptor = (
 
 const getUserRoleResourceAccessAcceptor = (
   getInstanceProps: ConstructFactoryGetInstanceProps,
-  roleName: AuthRoleName
+  roleName: AuthRoleName | string
 ) => {
   const resourceAccessAcceptor = getInstanceProps.constructContainer
     .getConstructFactory<
-      ResourceProvider & ResourceAccessAcceptorFactory<AuthRoleName>
+      ResourceProvider & ResourceAccessAcceptorFactory<AuthRoleName | string>
     >('AuthResources')
     ?.getInstance(getInstanceProps)
     .getResourceAccessAcceptor(roleName);
   if (!resourceAccessAcceptor) {
     throw new Error(
-      `Cannot specify ${
+      `Cannot specify auth access for ${
         roleName as string
-      } user policies without defining auth. See <defineAuth docs link> for more information.`
+      } users without defining auth. See https://docs.amplify.aws/gen2/build-a-backend/auth/set-up-auth/ for more information.`
     );
   }
   return resourceAccessAcceptor;

packages/backend-storage/src/constants.ts

@@ -1 +1 @@
-export const ownerPathPartToken = '{owner}';
+export const entityIdPathToken = '{entity_id}';