AWS Amplify 升级至Gen2版本时授权头缺失问题的解决方案

背景介绍

在将React应用从AWS Amplify Gen1升级到Gen2版本的过程中，开发者经常遇到API请求中授权头缺失的问题。这个问题尤其影响那些使用Cognito用户池作为API Gateway授权机制的应用。本文详细分析问题原因并提供完整的解决方案。

问题现象

在升级到Amplify v6（Gen2）后，开发者发现原本正常工作的API请求开始返回401未授权错误。通过检查网络请求发现，Authorization头没有像Gen1版本那样被自动添加到请求中。

配置差异分析

Gen1配置（正常工作）

Amplify.configure({
  Auth: {
    mandatorySignIn: true,
    region: config.cognito.REGION,
    userPoolId: config.cognito.USER_POOL_ID,
    identityPoolId: config.cognito.IDENTITY_POOL_ID,
    userPoolWebClientId: config.cognito.APP_CLIENT_ID,
  },
  API: {
    endpoints: [
      {
        name: "users",
        endpoint: config.apiGateway.URL,
        custom_header: async () => {
          return {
            Authorization: `${(await Auth.currentSession())
              .getAccessToken()
              .getJwtToken()}`,
          };
        },
      },
    ],
  },
});

Gen2初始配置（存在问题）

Amplify.configure({
  Auth: {
    userPoolWebClientId: config.cognito.APP_CLIENT_ID,
    identityPoolId: config.cognito.IDENTITY_POOL_ID,
    region: config.cognito.REGION,
    Cognito: {
      mandatorySignIn: true,
      userPoolId: config.cognito.USER_POOL_ID,
      userPoolClientId: config.cognito.APP_CLIENT_ID,
    }
  },
  API: {
    REST: {
      headers: async () => {
        return {Authorization: `${(await fetchAuthSession()).tokens.idToken.toString()}`};
      },
      'users': {
          name: "users",
          endpoint: config.apiGateway.URL,
          headers: async () => {
            return {Authorization: `${(await fetchAuthSession()).tokens.idToken.toString()}`};
          },
      },
    },
  },
});

问题根源

1. 配置结构变化：Gen2版本中，Auth和API的配置结构发生了显著变化，特别是headers配置的位置和方式。
2. 授权头处理机制变更：在Gen2中，headers配置需要作为库选项单独提供，而不是直接嵌套在API配置中。
3. Cognito授权范围要求：Gen2对授权范围的要求与Gen1不同，不再需要特定的授权范围如aws.cognito.signin.user.admin。

完整解决方案

正确的Gen2配置

Amplify.configure({
  Auth: {
    Cognito: {
      identityPoolId: config.cognito.IDENTITY_POOL_ID,
      userPoolId: config.cognito.USER_POOL_ID,
      userPoolClientId: config.cognito.APP_CLIENT_ID,
      allowGuestAccess: false, // 替代Gen1中的mandatorySignIn
    }
  },
  API: {
    REST: {
      'users': {
          name: "users",
          endpoint: config.apiGateway.URL,
      },
    },
  },
}, {
  API: {
    REST: {
      headers: async () => {
        return {Authorization: `${(await fetchAuthSession()).tokens.idToken.toString()}`};
      },
    }
  }
});

API Gateway调整

1. 移除API Gateway中Cognito授权器的授权范围要求
2. 确保授权器仍然验证JWT令牌的有效性
3. 检查CORS设置，确保包含Authorization头

实现原理

1. 双参数配置：Gen2采用两个参数对象进行配置，第一个包含基础配置，第二个包含库选项。
2. 全局headers：在库选项中定义的headers会应用到所有API请求。
3. 令牌获取：使用fetchAuthSession()获取当前会话，并通过tokens.idToken获取JWT令牌。

注意事项

1. 确保用户已正确登录并获取有效令牌
2. 检查网络请求确实包含Authorization头
3. 验证API Gateway日志以确认请求到达时的头部信息
4. 考虑令牌刷新机制，确保长时间会话的有效性

总结

从Amplify Gen1升级到Gen2时，授权机制的变化需要开发者特别注意配置结构的调整。通过正确理解Gen2的配置方式，并相应调整API Gateway的设置，可以确保授权流程继续正常工作。这一升级不仅带来了更清晰的配置结构，还简化了授权范围的管理，使安全配置更加灵活。