chore(apigateway): improve docs and default value settings for identi…

…ty source in authorizer (aws#28214)

Addressed the following points about Authorizer's `identitySource` property.

- Reference link is broken.
  - now: https://docs.aws.amazon.com/apigateway/api-reference/link-relation/authorizer-create/#identitySource
  - new: https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html#apigw-CreateAuthorizer-request-identitySource
- One explanation was confusing, so I enclosed it in quotes.
  - now: ```this should be `method.request.header.Authorizer` where Authorizer is the header containing the bearer token.```
  - new: ```this should be `method.request.header.Authorizer` where `Authorizer` is the header containing the bearer token.```
- Not using the static method written in the doc to set default values when a prop is not specified.
  - now: `'method.request.header.Authorization'`
  - new: `IdentitySource.header('Authorization')`

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/aws-cdk-lib/aws-apigateway/lib/authorizers/cognito.ts

@@ -1,4 +1,5 @@
 import { Construct } from 'constructs';
+import { IdentitySource } from './identity-source';
 import * as cognito from '../../../aws-cognito';
 import { Duration, FeatureFlags, Lazy, Names, Stack } from '../../../core';
 import { APIGATEWAY_AUTHORIZER_CHANGE_DEPLOYMENT_LOGICAL_ID } from '../../../cx-api';
@@ -33,8 +34,9 @@ export interface CognitoUserPoolsAuthorizerProps {
 
   /**
    * The request header mapping expression for the bearer token. This is typically passed as part of the header, in which case
-   * this should be `method.request.header.Authorizer` where Authorizer is the header containing the bearer token.
-   * @see https://docs.aws.amazon.com/apigateway/api-reference/link-relation/authorizer-create/#identitySource
+   * this should be `method.request.header.Authorizer` where `Authorizer` is the header containing the bearer token.
+   *
+   * @see https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html#apigw-CreateAuthorizer-request-identitySource
    * @default `IdentitySource.header('Authorization')`
    */
   readonly identitySource?: string;
@@ -78,7 +80,7 @@ export class CognitoUserPoolsAuthorizer extends Authorizer implements IAuthorize
       type: 'COGNITO_USER_POOLS',
       providerArns: props.cognitoUserPools.map(userPool => userPool.userPoolArn),
       authorizerResultTtlInSeconds: props.resultsCacheTtl?.toSeconds(),
-      identitySource: props.identitySource || 'method.request.header.Authorization',
+      identitySource: props.identitySource || IdentitySource.header('Authorization'),
     };
 
     this.authorizerProps = authorizerProps;

packages/aws-cdk-lib/aws-apigateway/lib/authorizers/lambda.ts

@@ -1,4 +1,5 @@
 import { Construct } from 'constructs';
+import { IdentitySource } from './identity-source';
 import * as iam from '../../../aws-iam';
 import * as lambda from '../../../aws-lambda';
 import { Arn, ArnFormat, Duration, FeatureFlags, Lazy, Names, Stack } from '../../../core';
@@ -182,8 +183,9 @@ export interface TokenAuthorizerProps extends LambdaAuthorizerProps {
 
   /**
    * The request header mapping expression for the bearer token. This is typically passed as part of the header, in which case
-   * this should be `method.request.header.Authorizer` where Authorizer is the header containing the bearer token.
-   * @see https://docs.aws.amazon.com/apigateway/api-reference/link-relation/authorizer-create/#identitySource
+   * this should be `method.request.header.Authorizer` where `Authorizer` is the header containing the bearer token.
+   *
+   * @see https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html#apigw-CreateAuthorizer-request-identitySource
    * @default `IdentitySource.header('Authorization')`
    */
   readonly identitySource?: string;
@@ -216,7 +218,7 @@ export class TokenAuthorizer extends LambdaAuthorizer {
       authorizerUri: lambdaAuthorizerArn(props.handler),
       authorizerCredentials: props.assumeRole?.roleArn,
       authorizerResultTtlInSeconds: props.resultsCacheTtl?.toSeconds() ?? Duration.minutes(5).toSeconds(),
-      identitySource: props.identitySource || 'method.request.header.Authorization',
+      identitySource: props.identitySource || IdentitySource.header('Authorization'),
       identityValidationExpression: props.validationRegex,
     };
 
@@ -242,14 +244,14 @@ export interface RequestAuthorizerProps extends LambdaAuthorizerProps {
   /**
    * An array of request header mapping expressions for identities. Supported parameter types are
    * Header, Query String, Stage Variable, and Context. For instance, extracting an authorization
-   * token from a header would use the identity source `IdentitySource.header('Authorizer')`.
+   * token from a header would use the identity source `IdentitySource.header('Authorization')`.
    *
    * Note: API Gateway uses the specified identity sources as the request authorizer caching key. When caching is
    * enabled, API Gateway calls the authorizer's Lambda function only after successfully verifying that all the
    * specified identity sources are present at runtime. If a specified identify source is missing, null, or empty,
    * API Gateway returns a 401 Unauthorized response without calling the authorizer Lambda function.
    *
-   * @see https://docs.aws.amazon.com/apigateway/api-reference/link-relation/authorizer-create/#identitySource
+   * @see https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html#apigw-CreateAuthorizer-request-identitySource
    */
   readonly identitySources: string[];
 }