AWS Machine Learning Blog

Deploy a Slack gateway for Amazon Q Business

July 2024: If you created a new Amazon Q Business application on or after April 30th, 2024, your new application is integrated with IAM Identity Center (IDC). This blog post has been updated with the steps required to setup Okta, IAM Identity Center, and the Slack gateway for new applications. The GitHub repository that accompanies this blog post has also had its AWS CloudFormation (CFN) template and instructions updated to reflect the latest requirements.

Amazon Q is a new generative AI-powered application that helps users get work done. Amazon Q can become your tailored business expert and let you discover content, brainstorm ideas, or create summaries using your company’s data safely and securely. You can use Amazon Q to have conversations, solve problems, generate content, gain insights, and take action by connecting to your company’s information repositories, code, data, and enterprise systems. For more information, see Introducing Amazon Q, a new generative AI-powered assistant (preview).

In this post, we show you how to bring Amazon Q, Business, to users in Slack. (If you use Microsoft Teams, refer to Deploy a Microsoft Teams gateway for Amazon Q Business.)

You’ll be able converse with Amazon Q using Slack direct messages (DMs) to ask questions and get answers based on company data, get help creating new content such as email drafts, summarize attached files, and perform tasks.

You can also invite Amazon Q to participate in your team channels. In a channel, users can ask it questions in a new message, or tag it in an existing thread at any point, to provide additional data points, resolve a debate, or summarize the conversation and capture the next steps. One important consideration when using Amazon Q in team channels is that all users in the channel will see responses from Amazon Q. Therefore, if your Amazon Q application has data sources with content that is restricted to users or groups, you may not want to consider the implications of enabling the app in Slack.

Solution overview

Amazon Q is amazingly powerful. Check out the following demo—seeing is believing!

In the demo, our Amazon Q application is populated with a set of AWS whitepapers. You can populate your own Amazon Q Business application with your own company’s documents and knowledge base articles, so it will be able to answer your questions!

Everything you need is provided as open source in our GitHub repo.

In this post, we walk you through the process to deploy Amazon Q in your AWS account and add it to your Slack workspace. When you’re done, you’ll wonder how you ever managed without it!

The following are some of the things it can do:

  • Respond to messages – In DMs, it responds to all messages. In channels, it responds only to @mentions and responds in a conversation thread.
  • Render answers containing markdown – This includes headings, lists, bold, italics, tables, and more.
  • Track sentiment – It provides thumbs up and thumbs down buttons to track user sentiment.
  • Provide source attribution – It provides references and hyperlinks to sources used by Amazon Q.
  • Understand conversation context – It tracks the conversation and responds based on the context.
  • Stay aware of multiple users – When it’s tagged in a thread, it knows who said what, and when, so it can contribute in context and accurately summarize the thread when asked.
  • Process attached files – It can process up to five attached files for document question answering, summaries, and more.
  • Start new conversations – You can reset and start new conversations in DM channels by using /new_conversation.

Slack example

In the following sections, we show how to deploy the project to your own AWS account and Slack workspace, and start experimenting!

Prerequisites

The following prerequisites are required to deploy this demo solution.

  1. You need to have an AWS account and an AWS Identity and Access Management(IAM) role and user with permissions to create and manage the necessary resources and components for this application. If you don’t have an AWS account, see How do I create and activate a new Amazon Web Services account?
  2. You need to have an Okta Workforce Identity Cloud account. If you haven’t signed up yet, see Signing up for Okta.
  3. You need to configure SAML and SCIM with Okta and IAM Identity Center. If you haven’t configured yet, see Configuring SAML and SCIM with Okta and IAM Identity Center.
  4. You also need to have an existing, working Amazon Q Business application. If you haven’t set one up yet, see Creating an Amazon Q application.
  5. You need to have users subscribed to your Amazon Q Business application, and are able to access Amazon Q Web Experience. If you haven’t subscribed users to an application yet, see Subscribing users to an Amazon Q application.
  6. Lastly, you need a Slack account and access to create and publish apps to your Slack organization. If you don’t have one, see if your company can create a Slack sandbox organization for you to experiment, or go to slack.com to create a free Slack account and workspace.

1. Setup Okta and IAM Identity Center

1.1 Create an OIDC app integration in Okta for the Slack gateway

Create the app integration in Okta as a ‘Web app’ with OIDC as the sign-in method.

Give your application a name and enable the Refresh Token grant type.

For Controlled access, enable Allow everyone in your organization to access and ensure that Federation Broker Mode is also enabled.

Leave all other fields with default values; we will update the redirect URI later (in step 3). Choose Save to create the application.

1.2 Create Trusted token issuer in IAM Identity Center

Create trusted token issuer to trust tokens generated by your Okta application. To obtain the OIDC issuer URL, go to Okta account console, choose API under Security in the left navigation, and copy the whole Issuer URI.

Follow Using applications with a trusted token issuer to configure the trusted token issuer in the AWS console. Alternatively, you can run the below script which is included in the GitHub repository associated with this blog post. For this script, you will need the OIDC issuer URL and the AWS region in which you created your Amazon Q Business application.

Substitute your region and OIDC issuer URL values for the placeholders below.

$ export AWS_DEFAULT_REGION=<YOUR_REGION_HERE>
$ OIDC_ISSUER_URL=<YOUR_OIDC_ISSUER_HERE>
$ bin/create-trusted-token-issuer.sh $OIDC_ISSUER_URL

The script will output trusted token issuer ARN (TTI_ARN) which you will use in the next step.

1.3 Create Customer managed application in IAM Identity Center

Next, create the customer managed application in IAM Identity Center by running the below script which is also included in the GitHub repository. For the script, you will need the OIDC client ID, trusted token issuer ARN, and the AWS region in which you have your Amazon Q Business application.

To retrieve the OIDC client ID, go to the Okta account console. Select Applications under the  Applications menu, and select on the application you created in Step 1.1.

  • Copy the Client ID.
  • For TTI_ARN, you can use the output from the previous step.
  • Substitute your region, client ID, and TTI ARN values for the placeholders below.
$ export AWS_DEFAULT_REGION=<YOUR_REGION_HERE>
$ OIDC_CLIENT_ID=<YOUR_OIDC_CLIENT_ID_HERE>
$ TTI_ARN=<YOUR_TTI_ARN_HERE>
$ bin/create-idc-application.sh $OIDC_CLIENT_ID $TTI_ARN

The script will output the gateway IDC application ARN (GATEWAY_IDC_ARN) which you will use in the next step.

Deploy the solution resources

We’ve provided pre-built AWS CloudFormation templates that deploy everything you need in your AWS account.

If you’re a developer and you want to build, deploy, or publish the solution from code, refer to the Developer README.

Complete the following steps to launch the CloudFormation stack:

  1. Log in to the AWS Management Console.
  2. Choose one of the following Launch Stack buttons for your desired AWS Region to open the AWS CloudFormation console and create a new stack.
  3. Enter the following parameters:
    • Stack Name: Name your App, e.g. AMAZON-Q-SLACK-GATEWAY.
    • AmazonQAppId: Your existing Amazon Q Application ID (copy from Amazon Q Business console).
    • AmazonQRegion: Choose the region where you created your Amazon Q Business application (us-east-1 or us-west-2).
    • OIDCIdPName: The name of the OIDC external identity provider. Specify ‘Okta’. Cognito is also supported.
    • OIDCClientId: The client ID of OIDC client you created in step 1.1.
    • OIDCIssuerURL: The issuer URL of the OIDC client you created in step 1.1.
    • GatewayIdCAppARN: The application ARN of the IdC customer managed application you created in step 1.3.
    • ContextDaysToLive: the length of time to keep conversation metadata cached in Amazon DynamoDB(you can leave this as the default)
Region Launch Stack
N. Virginia (us-east-1)
Oregon (us-west-2)

When your CloudFormation stack status is CREATE_COMPLETE, choose the Outputs tab, and keep it open—you’ll need it in later steps.

3. Update OIDC Client Redirect URI

On the Outputs tab from the CloudFormation stack that you just deployed, find the output parameter with the key ending with OIDCCallbackEndpointExportedName and copy its value to your clipboard. Then open the Okta administrative panel in another browser tab/window and browse to the Okta application you created earlier in Step 1.1. Scroll down to the General Settings section and choose Edit. Paste the callback endpoint URL into the Sign-in redirect URIs field and choose Save.

4. Configure your Slack application

4.1 Create your app

Now you can create your app in Slack. Complete the following steps:

  1. From the CloudFormation Outputs tab in the previous step, find the output parameter with the key name of SlackAppManifest, and copy the entire value to your clipboard. The value should be a block of JSON.
  2. Create a Slack app at https://api.slack.com/apps by selecting to create an app from an app manifest.
  3. Replace the placeholder manifest JSON with the JSON on your clipboard. Click Next and Create to create the Slack app.
  4. Choose Features from the navigation pane and scroll down to the section Show Tabs. Enable Messages Tab and check the box to “Allow users to send Slash commands and messages from the messages tab”. This step is required to enable your users to send messages to your app.

4.2 Add your app in your Slack workspace

Next let’s add your app to your Slack workspace. This is required to generate the Bot User OAuth Token value that will be needed in the next step.

  1. From api.slack.com, go to OAuth & Permissions for your app and click Install to Workspace, this will generate the OAuth token.
  2. In Slack, go to your workspace.
  3. Click on your workspace name and select Manage Apps under Tools and settings. This will open a browser window to the Slack app directory for your workspace.
  4. Click on your newly created app.
  5. In the right pane, click on Open in App Directory.
  6. Click Open in Slack.

4.3 Configure Slack and OIDC secrets in AWS Secrets Manager

Let’s configure your Slack and Okta OIDC secrets in order to verify the signature of each request and post on behalf of your Amazon Q bot.

In this example, we are not enabling Slack token rotation. You can enable it for a production app by implementing rotation via AWS Secrets Manager. Create an issue (or, better yet, a pull request) in the GitHub repo if you want this feature added to a future version.

Complete the following steps to configure the Slack secrets in Secrets Manager:

  1. On the AWS CloudFormation console, navigate to your stack Outputs tab and click the link. for SlackSecretConsoleUrl to be redirected to the Secrets Manager console.
  2. Choose Retrieve secret value.
  3. Choose Edit.
  4. Replace the values of SlackSigningSecret and SlackBotUserOAuthToken using the values in the Slack application configuration under Basic Information and OAuth & Permissions.

Be careful you don’t accidentally copy Client Secret instead of Signing Secret.

Next, configure OIDC Client Secret in order to exchange the code for a token:

  1. On the AWS CloudFormation console, navigate to your stack Outputs tab and click the link for OIDCClientSecretConsoleUrl to be redirected to the Secrets Manager.
  2. Choose Retrieve secret value.
  3. Choose Edit.
  4. Replace the value of OIDCClientSecret with the value in the Okta app client settings from step 1.1.

Start using Amazon Q

Complete the following steps to start using Amazon Q in Slack:

  1. Open your Slack workspace.
  2. Under Apps, Manage, add your new Amazon Q app.
  3. Optionally, add your Amazon Q app to team channels.
  4. In the app DM channel, enter Hello.

Say hello

You have now deployed a powerful new AI assistant into your sandbox Slack environment.

Play with it, try all the features discussed in this post, and copy the things you saw in the demo video. Most importantly, you can ask about topics related to the documents that you have ingested into your own Amazon Q Business application. But don’t stop there. You can find additional ways to make it useful, and when you do, let us know by posting a comment.

Once you are convinced how useful it is, talk to your Slack admins (and show them this post) and work with them to deploy it in your company’s Slack workspaces. Your fellow employees will thank you!

Clean up

When you’re finished experimenting with this solution, delete your app in Slack (https://api.slack.com/apps) and clean up your AWS resources by opening the AWS CloudFormation console and deleting the AMAZON-Q-SLACK-GATEWAY stack that you deployed. This deletes the resources that you created by deploying the solution.

Conclusions

This sample Amazon Q slack application discussed in this post is provided as open source—you can use it as a starting point for your own solution, and help us make it better by contributing back fixes and features via GitHub pull requests. Explore the code, choose Watch in the GitHub repo to be notified of new releases, and check back for the latest updates. We’d also love to hear your suggestions for improvements and features.

For more information on Amazon Q, refer to What is Amazon Q (For Business Use)?

About the Authors

Gary Benattar is a Senior Software Development Manager in AWS HR. Gary started at Amazon in 2012 as an intern, focusing on building scalable, real-time outlier detection systems. He worked in Seattle and Luxembourg and is now based in Tel Aviv, Israel, where he dedicates his time to building software to revolutionize the future of Human Resources. He co-founded a startup, Zengo, with a focus on making digital wallets secure through multi-party computation. He received his MSc in Software Engineering from Sorbonne University in Paris.

Bob StrahanBob Strahan is a Principal Solutions Architect in the AWS Language AI Services team.

James Jory is a Principal Solutions Architect in Applied AI with AWS. He has a special interest in personalization and recommender systems and a background in ecommerce, marketing technology, and customer data analytics. In his spare time, he enjoys camping and auto racing simulations.

Harshavardhan Malipatel is a Senior Software Development Engineer in Amazon Q Business. Previously, he worked in AWS EC2 Networking, building AWS Client VPN service and VPC core features. Outside of work, he enjoys traveling and creating memories with his family.