Lambda

Gateway support

This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see Lambda.

About

The Lambda policy lets you trigger AWS Lambda functions from within an API's assembly without requiring you to use the Amazon API Gateway. When you add the policy to an API assembly, you can specify the Lambda function to invoke and provide credentials for using it. The credentials can be either an AWS IAM role, or an Access Key ID/Secret Access Key pair.

Setting up permissions and trust in AWS

Use the instructions for the option that best suits your needs.

Access Key ID/Secret Access Key

Provide the AWS Access Key ID/AWS Secret Access Key pair of an account with permission to invoke one or more Lambda functions. The permissions of this account should be as narrowly-scoped as possible; the account should be a service account with no other permissions other than the ability to invoke one or more Lambda functions. For more information, see the Identity-Based IAM Policies for Lambda documentation.

To use the Access Key ID/Secret Access Key authentication option, complete the following steps to use your account's IAM service and create an IAM service account with appropriate permissions to facilitate limited communication with API Connect:

1. Sign in to the AWS Management Console and open the IAM console.
2. On the AWS IAM console, click Users in the navigation list, and then click Add users.
3. When prompted to "Set user details", provide a User name (unique within your AWS account) and select Access key - Programmatic access.

   You can select the Password - AWS Management Console access option, but it is not required for interaction with API Connect.

   There are a variety of options for defining permissions for the new user account. See the AWS Identity and Access Management User Guide for information on adding the user to a user group, or attaching a policy directly to the user.

   A straightforward method of defining user permissions that adheres to the least-privilege principle is to create an IAM user with no permissions, and then add that user to the permissions configuration of a specific Lambda function, as demonstrated in the following steps.

4. On the "Set user details" page, click Next: Tags without making any changes to the new User account.
5. Create the desired Tags and then click Next: Review.
6. Review your settings and click Create user.

   Ignore the warning that This user has no permissions because you will assign permissions in the remaining steps.

7. Click Download .csv to save the new user's Access key ID and Secret access key, and store them in a safe place. These values will be used as the AWS Access Key ID and AWS Secret Access Key when configuring the Lambda policy of your API in API Connect.
8. Update the Lambda function to provide permissions for the new user:
   1. In the Lambda console, open the Functions page.
   2. Select the function that API Connect will invoke.
   3. Click Configuration.
   4. In the Resource-based policy statements section, click Add permissions.
   5. Select AWS account and add a unique Statement ID.
   6. Set Principal to the ARN of the new user.

      arn:aws:iam::<AWS_account_ID>:user/<username>, available on the Users > <username> page.

   7. Set the Action to lambda:InvokeFunction.
   8. Click Save.

   Repeat this step for every Lambda function that the user account will invoke.

Assume Role ARN

Provide the AWS Assume Role ARN of a role with permission to invoke one or more Lambda functions. This role must have a specific configuration for the trust policy that includes the following parameters: Action, Condition, Effect, and Principal.

The permissions of this role should be as narrowly-scoped as possible; the role should have no other permissions other than the ability to invoke one or more Lambda functions. For more information, see the Lambda permissions documentation.

To use the AWS Assume Role ARN authentication option, complete the following steps to create an appropriate AWS Policy and Role with your account's IAM service to facilitate limited communication with API Connect:

1. Sign in to the AWS Management Console and open the IAM console.
2. On the AWS IAM console, click Roles in the navigation list, and then click Create role.
3. When prompted to "Select trusted entity", click Custom trust policy, use the following code example as a guide to create the trust policy, and then click Next.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "AWS": "arn:aws:iam::623947394061:role/ibm-apiconnect-<apic_region>"
               },
               "Action": "sts:AssumeRole",
               "Condition": {
                   "StringEquals": {
                       "sts:ExternalId": "<apic_provider_org_ID>"
                   }
               }
           }
       ]
   }

   Replace the following variables with your own values:

   • <apic_region> is the region where you deployed your API Connect service instance; for example: us-east-a.
   • <apic_provider_org_ID> is the API Connect ID of your provider organization.
     To determine the name of your provider organization:

     1. Log in to API Connect using the --sso option; for example:

        ./apic login \
          --sso \
          --context provider \
          --server platform-api.<apic_region>.example.com

        where <apic_region> is the region where you deployed your API Connect service instance.

     2. Run the following command to get the API Connect ID of your provider organization:

        ./apic orgs:list \
          --my \
          --fields name,id \
          --format yaml \
          --output - \
          --server platform-api.<apic_region>.example.com

        where <apic_region> is the region where you deployed your API Connect service instance.

        The response returns a list of provider organization names, with the corresponding ID for each name.

4. When prompted to "Add permissions" choose a method for adding a policy to the new role:
   • Attach the AWSLambdaRole policy:

     The AWSLambdaRole policy is managed by AWS and allows the required lambda:InvokeFunction action. The policy's scope applies to all Lambda functions in the current AWS account.

   • Create your own custom policy that allows the lambda:InvokeFunction action:

     If you want to use a more tightly-scoped policy, you can create the policy while creating the new role, or create the policy in advance and attach it while creating the new role. To create a policy, click Policiesin the IAM console's navigation list, then click Create policy.

   The policy that you use must allow the lambda:InvokeFunction action for the desired Lambda function resource or resources. The following sample policy is scoped to a single Lambda function:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "lambda:InvokeFunction",
               "Resource": "arn:aws:lambda:us-east-1:<AWS_account_ID>:function:<lambda_function_name>"
           }
       ]
   }

   Replace the following variables with your own values:

   • <AWS_account_ID> is the API Connect AWS Production account ID -- use the following value:

     623947394061

   • <lambda_function_name> is the name or Amazon Resource Name (ARN) of the AWS Lambda function to execute.

   For information on alternative policy structures, see the AWS Identity and Access Management User Guide.

5. Provide a Role name, a Description, and some Tags.
6. Click Create role.

When you configure the Lambda policy of your API in API Connect, provide the ARN of the new role as the value for the AWS Assume Role ARN field.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.