Skip to content

Commit 6c868f3

Browse files
srajiangseratch
srajiang
and
seratch
authored
Improve oauth lambda deploy instructs (#621)
Co-authored-by: Kazuhiro Sera <[email protected]>
1 parent 8bdc43a commit 6c868f3

File tree

1 file changed

+118
-84
lines changed

1 file changed

+118
-84
lines changed

‎examples/aws_lambda/README.md‎

Lines changed: 118 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -85,87 +85,121 @@ Instructions on how to set up and deploy each example are provided below.
8585

8686
## OAuth Lambda Listener Example Bolt App
8787

88-
1. You need an AWS account and your AWS credentials set up on your machine.
89-
2. Make sure you have an AWS IAM Role defined with the needed permissions for
90-
your Lambda function powering your Slack app:
91-
- Head to the AWS IAM section of AWS Console
92-
- Click Roles from the menu
93-
- Click the Create Role button
94-
- Under "Select type of trusted entity", choose "AWS service"
95-
- Under "Choose a use case", select "Common use cases: Lambda"
96-
- Click "Next: Permissions"
97-
- Under "Attach permission policies", enter "lambda" in the Filter input
98-
- Check the "AWSLambdaBasicExecutionRole" and "AWSLambdaExecute" policies
99-
- Under "Attach permission policies", enter "s3" in the Filter input
100-
- Check the "AWSS3FullAccess" policy
101-
- Click "Next: tags"
102-
- Click "Next: review"
103-
- Enter `bolt_python_s3_storage` as the Role name. You can change this
104-
if you want, but then make sure to update the role name in
105-
`aws_lambda_oauth_config.yaml`
106-
- Optionally enter a description for the role, such as "Bolt Python with S3
107-
access role"
108-
3. Ensure you have created an app on api.slack.com/apps as per the [Getting
109-
Started Guide](https://slack.dev/bolt-python/tutorial/getting-started).
110-
You do not need to ensure you have installed it to a workspace, as the OAuth
111-
flow will provide your app the ability to be installed by anyone.
112-
4. You will need to create two S3 buckets: one to store installation credentials
113-
(when a new Slack workspace installs your app) and one to store state
114-
variables during the OAuth flow. You will need the names of these buckets in
115-
the next step.
116-
5. You need many environment variables exported! Specifically the following from
117-
api.slack.com/apps:
118-
- `SLACK_SIGNING_SECRET`: Signing Secret from Basic Information page
119-
- `SLACK_CLIENT_ID`: Client ID from Basic Information page
120-
- `SLACK_CLIENT_SECRET`: Client Secret from Basic Information page
121-
- `SLACK_SCOPES="app_mentions:read,chat:write"`: Which scopes this application
122-
needs
123-
- `SLACK_INSTALLATION_S3_BUCKET_NAME`: The name of one of the S3 buckets you
124-
created
125-
- `SLACK_STATE_S3_BUCKET_NAME`: The name of the other S3 bucket you created
126-
6. Let's deploy the Lambda! Run `./deploy_oauth.sh`. By default it deploys to the
127-
us-east-1 region in AWS - you can change this at the top of `aws_lambda_oauth_config.yaml` if you wish.
128-
7. Load up AWS Lambda inside the AWS Console - make sure you are in the correct
129-
region that you deployed your app to. You should see a `bolt_py_oauth_function`
130-
Lambda there.
131-
8. While your Lambda exists, it is not accessible to the internet, so Slack
132-
cannot send events happening in your Slack workspace to your Lambda. Let's
133-
fix that by adding an AWS API Gateway in front of your Lambda so that your
134-
Lambda can accept HTTP requests:
135-
- Click on your `bolt_py_oauth_function` Lambda
136-
- In the Function Overview, on the left side, click "+ Add Trigger"
137-
- Select API Gateway from the trigger list
138-
- Make sure "Create an API" is selected in the dropdown, and choose "HTTP API"
139-
as the API Type
140-
- Under Security, select "Open"
141-
- Click "Add"
142-
9. Congrats! Your Slack app is now accessible to the public. On the left side of
143-
your `bolt_py_oauth_function` Function Overview you should see a purple API Gateway
144-
icon. Click it.
145-
10. Click Details to expand the details section.
146-
11. Copy the API Endpoint - this is the URL your Lambda function is accessible
147-
at publicly.
148-
12. We will now inform Slack that this example app can accept Slash Commands.
149-
- Back on api.slack.com/apps, select your app and choose Slash Commands from the left menu.
150-
- Click Create New Command
151-
- By default, the `aws_lambda_oauth.py` function has logic for a
152-
`/hello-bolt-python-lambda` command. Enter `/hello-bolt-python-lambda` as
153-
the Command.
154-
- Under Request URL, paste in the previously-copied API Endpoint from API
155-
Gateway.
156-
- Click Save
157-
13. We also need to register the API Endpoint as the OAuth redirect URL:
158-
- Load up the "OAuth &amp; Permissions" page on api.slack.com/apps
159-
- Scroll down to Redirect URLs
160-
- Copy the API endpoint in - but remove the path portion. The Redirect URL
161-
needs to only _partially_ match where we will send users.
162-
14. You can now install the app to any workspace!
163-
15. Test it out! Once installed to a Slack workspace, try typing
164-
`/hello-bolt-python-lambda hello`.
165-
16. If you have issues, here are some debugging options:
166-
- Check the Monitor tab under your Lambda. Did the Lambda get invoked? Did it
167-
respond with an error? Investigate the graphs to see how your Lambda is
168-
behaving.
169-
- From this same Monitor tab, you can also click "View Logs in CloudWatch" to
170-
see the execution logs for your Lambda. This can be helpful to see what
171-
errors are being raised.
88+
### Setup your AWS Account + Credentials
89+
You need an AWS account and your AWS credentials set up on your machine.
90+
91+
Once you’ve done that you should have access to AWS Console, which is what we’ll use for the rest of this tutorial.
92+
93+
### Create S3 Buckets to store Installations and State
94+
95+
1. Start by creating two S3 buckets:
96+
1. One to store installation credentials for each Slack workspace that installs your app.
97+
2. One to store state variables during the OAuth flow.
98+
2. Head over to **Amazon S3** in the AWS Console
99+
3. Give your bucket a name, region, and set access controls. If you’re doing this for the first time, it’s easiest to keep the defaults and edit them later as necessary. We'll be using the names:
100+
1. slack-installations-s3
101+
2. slack-state-store-s3
102+
4. After your buckets are created, in each bucket’s page head over to “Properties” and save the Amazon Resource Name (ARN). It should look something like `arn:aws:s3:::slack-installations-s3`.
103+
104+
### Create a Policy to Enable Actions on S3 Buckets
105+
Now let's create a policy that will allow the holder of the policy to take actions in your S3 buckets.
106+
107+
1. Head over to Identity and Access Management (IAM) in the AWS Console via Search Bar
108+
2. Head to **Access Management > Policies** and select “Create Policy”
109+
3. Click the JSON tab and copy this in:
110+
```json
111+
{
112+
"Version": "2012-10-17",
113+
"Statement": [
114+
{
115+
"Effect": "Allow",
116+
"Action": [
117+
"s3:Get*",
118+
"s3:Put*",
119+
"s3:Delete*",
120+
"s3-object-lambda:*"
121+
],
122+
"Resource": [
123+
"<your-first-bucket-arn>/*", // don't forget the `/*`
124+
"<your-second-bucket-arn>/*"
125+
]
126+
}
127+
]
128+
}
129+
```
130+
4. Edit “Resource” to include the ARNs of the two buckets you created in the earlier step. These need to exactly match the ARNS you copied earlier and end with a `/*`
131+
5. Hit "Next:Tags" and "Next:Review"
132+
6. Review policy
133+
1. Name your policy something memorable enough that you won’t have forgotten it 5 minutes from now when we’ll need to look it up from a list. (e.g. AmazonS3-FullAccess-SlackBuckets)
134+
2. Review the summary, and hit "Create Policy". Once the policy is created you should be redirected to the Policies page and see your new policy show up as Customer managed policy.
135+
136+
### Setup an AWS IAM Role with Policies for Executing Your Lambda
137+
Let’s create a user role that will use the custom policy we created as well as other policies to let us execute our lambda, write output logs to CloudWatch.
138+
139+
1. Head to the **Identity and Access Management (IAM)** section of AWS Console
140+
2. Select **Access Management > Roles** from the menu
141+
3. Click "Create Role"
142+
4. Step 1 - Select trusted entity
143+
1. Under "Select type of trusted entity", choose "AWS service"
144+
2. Under "Choose a use case", select "Common use cases: Lambda"
145+
3. Click "Next: Permissions”
146+
5. Step 2 - Add permissions
147+
1. Add the following policies to the role we’re creating that will allow the user with the role permission to execute Lambda, make changes to their S3 Buckets, log output to CloudWatch
148+
1. `AWSLambdaExecute`
149+
2. `AWSLambdaBasicExecutionRole`
150+
3. `<NameOfRoleYouCreatedEarlier>`
151+
6. Step 3 - Name, review, create
152+
1. Enter `bolt_python_s3_storage` as your role name. To use a different name, make sure to update the role name in `aws_lambda_oauth_config.yaml`
153+
2. Optionally enter a description for the role, such as "Bolt Python with S3 access role”
154+
3. "Create Role"
155+
156+
### Create Slack App and Load your Lambda to AWS
157+
Ensure you have created an app on [api.slack.com/apps](https://api.slack.com/apps) as per the [Getting Started Guide](https://slack.dev/bolt-python/tutorial/getting-started). You do not need to ensure you have installed it to a workspace, as the OAuth flow will provide your app the ability to be installed by anyone.
158+
159+
1. Remember those S3 buckets we made? You will need the names of these buckets again in the next step.
160+
2. You need many environment variables exported! Specifically the following from api.slack.com/apps
161+
162+
```bash
163+
SLACK_SIGNING_SECRET= # Signing Secret from Basic Information page
164+
SLACK_CLIENT_ID= # Client ID from Basic Information page
165+
SLACK_CLIENT_SECRET # Client Secret from Basic Information page
166+
SLACK_SCOPES= "app_mentions:read,chat:write"
167+
SLACK_INSTALLATION_S3_BUCKET_NAME: # The name of installations bucket
168+
SLACK_STATE_S3_BUCKET_NAME: # The name of the state store bucket
169+
export
170+
```
171+
6. Let's deploy the Lambda! Run `./deploy_oauth.sh`. By default it deploys to the us-east-1 region in AWS - you can customize this in `aws_lambda_oauth_config.yaml`.
172+
7. Load up AWS Lambda inside the AWS Console - make sure you are in the correct region that you deployed your app to. You should see a `bolt_py_oauth_function` Lambda there.
173+
174+
### Set up AWS API Gateway
175+
Your Lambda exists, but it is not accessible to the internet, so Slack cannot yet send events happening in your Slack workspace to your Lambda. Let's fix that by adding an AWS API Gateway in front of your Lambda so that your Lambda can accept HTTP requests
176+
177+
1. Click on your `bolt_py_oauth_function` Lambda
178+
2. In the **Function Overview**, on the left side, click "+ Add Trigger"
179+
3. Select "API Gateway" from the trigger list
180+
4. Make sure "Create an API" is selected in the dropdown, and choose "HTTP API" as the API Type
181+
5. Under Security, select "Open"
182+
6. Click "Add"
183+
184+
Phew, congrats! Your Slack app is now accessible to the public. On the left side of your bolt_py_oauth_function Function Overview you should see a purple API Gateway icon. Click it.
185+
186+
1. Click "Details"
187+
2. Copy the API Endpoint - this is the URL your Lambda function is accessible at publicly.
188+
3. We will now inform Slack that this example app can accept Slash Commands.
189+
4. Back on [api.slack.com/apps](https://api.slack.com/apps), select your app and choose "Slash Commands" from the left menu.
190+
5. Click "Create New Command"
191+
1. By default, the `aws_lambda_oauth.py` function has logic for a /hello-bolt-python-lambda command. Enter `/hello-bolt-python-lambda` as the Command.
192+
* Under **Request URL**, paste in the previously-copied API Endpoint from API Gateway.
193+
* Click "Save"
194+
6. We also need to register the API Endpoint as the OAuth redirect URL:
195+
1. Load up the **OAuth & Permissions** page on[api.slack.com/apps](https://api.slack.com/apps)
196+
2. Scroll down to "Redirect URLs"
197+
3. Copy the API endpoint in - but remove the path portion. The Redirect URL needs to only partially match where we will send users.
198+
199+
You can now install the app to any workspace!
200+
201+
### Test it out!
202+
1. Once installed to a Slack workspace, try typing `/hello-bolt-python-lambda` hello.
203+
2. If you have issues, here are some debugging options:
204+
1. _View lambda activity_: Head to the Monitor tab under your Lambda. Did the Lambda get invoked? Did it respond with an error? Investigate the graphs to see how your Lambda is behaving.
205+
2. _Check out the logs_: From this same Monitor tab, you can also click "View Logs in CloudWatch" to see the execution logs for your Lambda. This can be helpful to see what errors are being raised.

0 commit comments

Comments
 (0)