Sign in with Slack using Cognito User Pools

Takahiro Iwasa

Aug 12, 2024

11 min read

Cognito OIDC

Amazon Cognito User Pools provides a feature to federate with OpenID Connect. This allows your application users to sign in using their third-party accounts.

docs.aws.amazon.com

Using OIDC identity providers with a user pool - Amazon Cognito

Describes how to add OIDC identity providers to a user pool.

Slack can be used as an OpenID Connect provider for Cognito, which is built on top of OAuth 2.0.

api.slack.com

Sign in with Slack setup

Our OAuth-based sign-in flow uses the OpenID Connect protocol to let users sign into your service using Slack.

This post shows you how to configure Cognito User Pools and Slack using AWS CDK and how to build a React/Next.js application using AWS Amplify. You can clone the example from my GitHub repository.

This post creates the following project structure.

/
|-- cdk/
|   |-- bin/
|   |   `-- cdk.ts
|   |-- lib/
|   |   `-- cdk-stack.ts
|   |-- node_modules/
|   |-- test/
|   |   `-- cdk.test.ts
|   |-- .gitignore
|   |-- .npmignore
|   |-- biome.json
|   |-- cdk.json
|   |-- jest.config.js
|   |-- package.json
|   |-- package-lock.json
|   |-- README.md
|   `-- tsconfig.json
|-- my-app/
|   |-- node_modules/
|   |-- public/
|   |-- src/
|   |   |-- app/
|   |   |   |-- globals.css
|   |   |   |-- layout.tsx
|   |   |   `-- page.tsx
|   |   `-- auth.ts
|   |-- .env.local
|   |-- .gitignore
|   |-- biome.json
|   |-- next.config.mjs
|   |-- next-env.d.ts
|   |-- package.json
|   |-- package-lock.json
|   |-- postcss.config.mjs
|   |-- README.md
|   |-- tailwind.config.ts
|   `-- tsconfig.json
|-- node_modules/
|-- .gitignore
|-- package.json
`-- package-lock.json

First of all, bootstrap your AWS CDK environment.

docs.aws.amazon.com

Getting started with the AWS CDK - AWS Cloud Development Kit (AWS CDK) v2

Get started with the AWS Cloud Development Kit (AWS CDK) by creating an AWS account, configuring the AWS CDK Command Line Interface (AWS CDK CLI) and creating your first CDK app.

In this post, we install AWS CDK locally to avoid polluting the global npm environment.

npm i -D aws-cdk
npx cdk bootstrap aws://<AWS_ACCOUNT_ID>/<AWS_REGION>

To initialize your CDK project, run the following command.

mkdir cdk && cd cdk
npx cdk init app --language typescript

To install React/Next.js, run the following command.

react.dev

Start a New React Project – React

The library for web and native user interfaces

npx create-next-app@latest

✔ What is your project named? … my-app
✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … No
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to customize the default import alias (@/*)? … No
Creating a new Next.js app in sign-in-with-slack-using-cognito-user-pools/my-app.

Using npm.

Initializing project with template: app-tw


Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- typescript
- @types/node
- @types/react
- @types/react-dom
- postcss
- tailwindcss


added 138 packages, and audited 139 packages in 17s

31 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
Success! Created my-app at sign-in-with-slack-using-cognito-user-pools/my-app

AWS Amplify allows us to interact easily with Cognito. Run the following command to install.

www.npmjs.com

aws-amplify

AWS Amplify is a JavaScript library for Frontend and mobile developers building cloud-enabled applications.. Latest version: 6.5.0, last published: 5 days ago. Start using aws-amplify in your project by running `npm i aws-amplify`. There are 599 other projects in the npm registry using aws-amplify.

cd my-app
npm i aws-amplify

Create a new Slack app to interact with Cognito User Pool according to the following steps.

Open your workspace menu and navigate to the Manage apps.

Press the Build button on the Slack app directory page.

Press the Create an App button on your apps page.

In this post, choose the From an app manifest.

api.slack.com

Create and configure apps with manifests

Use our app manifest system to create, configure, and clone Slack apps with ease.

Use the app manifest system to quickly create, configure, and reuse Slack app configurations.

Choose your workspace.

Enter the app name which you like. In this post, Sign in with Slack is used. Leave the other fields default.

Finish the step to press the Create button.

The Slack app credentials are needed for a Cognito user pool which will be created later. Check the following values.

• Client ID
• Client Secret

To store those credentials in your Secrets Manager, run the following command.

aws secretsmanager create-secret \
--name sign-in-with-slack \
--secret-string '{"clientId": "<YOUR_CLIENT_ID>", "clientSecret": "<YOUR_CLIENT_SECRET>"}'

Paste the following code to cdk/bin/cdk.ts. The environment variables SLACK_SECRET_ARN (line 8) and COGNITO_DOMAIN_PREFIX (line 9) are passed at runtime.

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { CdkStack } from '../lib/cdk-stack';

const app = new cdk.App();
new CdkStack(app, 'CdkStack', {
  slackSecretArn: process.env.SLACK_SECRET_ARN ?? '',
  cognitoDomainPrefix: process.env.COGNITO_DOMAIN_PREFIX ?? '',
});

Then, paste the following code to cdk/lib/cdk-stack.ts.

The key points here are:

• That the UserPoolClient.oAuth.scopes must include OAuthScope.COGNITO_ADMIN (line 55) to use the Amplify fetchUserAttributes function.
  • For more information, please refer to the official documentation.
• That the Slack app credentials are looked up for from the Secrets Manager secret (line 65-69) which has been created above.
• That the Slack app credentials are set without them exposed (line 75-82).

import * as cdk from 'aws-cdk-lib';
import type { Construct } from 'constructs';
import {
  OAuthScope,
  ProviderAttribute,
  UserPool,
  UserPoolClient,
  UserPoolClientIdentityProvider,
  UserPoolDomain,
  UserPoolIdentityProviderOidc,
} from 'aws-cdk-lib/aws-cognito';
import { Secret } from 'aws-cdk-lib/aws-secretsmanager';

export class CdkStack extends cdk.Stack {
  constructor(
    scope: Construct,
    id: string,
    props?: cdk.StackProps & {
      slackSecretArn: string;
      cognitoDomainPrefix: string;
    },
  ) {
    super(scope, id, props);

    // Cognito User Pool
    const userPool = new UserPool(this, 'user-pool', {
      userPoolName: 'sign-in-with-slack-user-pool',
    });

    // Cognito User Pool Domain
    new UserPoolDomain(this, 'user-pool-domain', {
      userPool,
      cognitoDomain: {
        domainPrefix: props?.cognitoDomainPrefix ?? '',
      },
    });

    // Cognito User Pool Client
    new UserPoolClient(this, 'user-pool-client', {
      userPool,
      userPoolClientName: 'client',
      oAuth: {
        flows: {
          authorizationCodeGrant: true,
        },
        callbackUrls: [
          'https://example.com/', // Cognito app client default
          'http://localhost:3000/',
        ],
        logoutUrls: ['http://localhost:3000/'],
        scopes: [
          OAuthScope.OPENID,
          OAuthScope.EMAIL,
          OAuthScope.PROFILE,
          OAuthScope.COGNITO_ADMIN,
        ],
      },
      supportedIdentityProviders: [
        UserPoolClientIdentityProvider.COGNITO,
        UserPoolClientIdentityProvider.custom('Slack'),
      ],
    });

    // Slack app credentials stored in your Secrets Manager
    const slackSecret = Secret.fromSecretCompleteArn(
      this,
      'slack-secret',
      props?.slackSecretArn ?? '',
    );

    // Cognito User Pool Identity Provider (OIDC)
    new UserPoolIdentityProviderOidc(this, 'slack-oidc', {
      userPool,
      name: 'Slack',
      clientId: slackSecret
        .secretValueFromJson('clientId')
        .unsafeUnwrap()
        .toString(),
      clientSecret: slackSecret
        .secretValueFromJson('clientSecret')
        .unsafeUnwrap()
        .toString(),

      // See https://api.slack.com/authentication/sign-in-with-slack#request
      // > Which permissions you want the user to grant you.
      // > Your app will request openid, the base scope you always need to request in any Sign in with Slack flow.
      // > You may request email and profile as well.
      scopes: ['openid', 'email', 'profile'],

      // See https://api.slack.com/authentication/sign-in-with-slack#discover
      issuerUrl: 'https://slack.com',

      // The following endpoints do not need to be configured because the Cognito can find them by the issuer url.
      // endpoints: {
      //   authorization: 'https://slack.com/openid/connect/authorize',
      //   token: 'https://slack.com/api/openid.connect.token',
      //   userInfo: 'https://slack.com/api/openid.connect.userInfo',
      //   jwksUri: 'https://slack.com/openid/connect/keys',
      // },

      attributeMapping: {
        email: ProviderAttribute.other('email'),
        profilePage: ProviderAttribute.other('profile'),
      },
    });
  }
}

Finally, deploy the resources to your AWS. Before running the following command, replace SLACK_SECRET_ARN and COGNITO_DOMAIN_PREFIX with your actual values.

export SLACK_SECRET_ARN=arn:aws:secretsmanager:<AWS_REGION>:<AWS_ACCOUNT_ID>:secret:sign-in-with-slack-<SUFFIX>
export COGNITO_DOMAIN_PREFIX=<ANY_PREFIX_YOU_LIKE>
npx cdk deploy

✨  Synthesis time: 3.98s

CdkStack:  start: Building 3cbdfe791ed2ca2eec7e43ea613065781d765bb7b2597870810a2b4b38e03f6a:current_account-current_region
CdkStack:  success: Built 3cbdfe791ed2ca2eec7e43ea613065781d765bb7b2597870810a2b4b38e03f6a:current_account-current_region
CdkStack:  start: Publishing 3cbdfe791ed2ca2eec7e43ea613065781d765bb7b2597870810a2b4b38e03f6a:current_account-current_region
CdkStack:  success: Published 3cbdfe791ed2ca2eec7e43ea613065781d765bb7b2597870810a2b4b38e03f6a:current_account-current_region
CdkStack: deploying... [1/1]
CdkStack: creating CloudFormation changeset...

 ✅  CdkStack

✨  Deployment time: 16.72s

Stack ARN:
arn:aws:cloudformation:<AWS_REGION>:<AWS_ACCOUNT_ID>:stack/CdkStack/<UUID>

✨  Total time: 20.7s

Navigate to the OAuth & Permissions page, and configure your Slack app OAuth.

Press the Add New Redirect URL button, enter the following value, and press the Save URLs button to complete.

https://<COGNITO_DOMAIN_PREFIX>.auth.ap-northeast-1.amazoncognito.com/oauth2/idpresponse

docs.aws.amazon.com

Using OIDC identity providers with a user pool - Amazon Cognito

Describes how to add OIDC identity providers to a user pool.

Register your user pool domain URL with the /oauth2/idpresponse endpoint with your OIDC IdP.

If you do not know your cognito domain, you can find it in the Cognito App Integration tab.

Add the OAuth scope users:read to User Token Scopes.

Finally, to install your Slack app, press the Install to <WORKSPACE> button.

You can test the sign in with Slack feature using the Cognito Hosted UI.

Go to the Cognito app client page, and press the View Hosted UI button.

Press the Slack button.

Enter your workspace name and press the Continue button.

Complete the sign-in process to the Slack workspace.

Press the Allow button to proceed.

You will be redirected to the callback url which can be configured in the Cognito app client.

In this time, the URL https://example.com/ is used by default.

To confirm the federated user, run the following command. You would see the user federated to your Cognito User Pool.

aws cognito-idp list-users \
--user-pool-id <COGNITO_USER_POOL_ID>

{
    "Users": [
        {
            "Username": "Slack_U07G7NBRPN2",
            "Attributes": [
                {
                    "Name": "email",
                    "Value": "<SLACK_USER_EMAIL>"
                },
                {
                    "Name": "email_verified",
                    "Value": "false"
                },
                {
                    "Name": "sub",
                    "Value": "<UUID>"
                },
                {
                    "Name": "identities",
                    "Value": "<SLACK_IDENTITIES>"
                }
            ],
            "UserCreateDate": "2024-08-12T15:12:47.047000+09:00",
            "UserLastModifiedDate": "2024-08-12T15:12:47.047000+09:00",
            "Enabled": true,
            "UserStatus": "EXTERNAL_PROVIDER"
        }
    ]
}

Create the ./my-app/.env.local with the following values, and replace those with your actual ones.

NEXT_PUBLIC_USER_POOL_ID=<COGNITO_USER_POOL_ID>
NEXT_PUBLIC_USER_POOL_CLIENT_ID=<COGNITO_USER_POOL_CLIENT_ID>
NEXT_PUBLIC_OAUTH_DOMAIN=<COGNITO_DOMAIN_PREFIX>.auth.ap-northeast-1.amazoncognito.com

Create auth helper functions and save them to the ./my-app/src/auth.ts.

The key points here are:

• That the oauth.scopes must include aws.cognito.signin.user.admin (line 27) if you are going to use the fetchUserAttributes function.
  • For more information, please refer to the official documentation.
• That the oauth.redirectSignIn and oauth.redirectSignOut (line 31-32) must completely match the Cognito app client configuration including the trailing slash.

import { Amplify } from 'aws-amplify';
import {
  type AuthSession,
  fetchAuthSession,
  fetchUserAttributes,
  getCurrentUser,
  signInWithRedirect,
  signOut,
} from 'aws-amplify/auth';
import type { AuthConfig } from '@aws-amplify/core';
import type { AuthUser } from '@aws-amplify/auth';
import type { AuthUserAttributes } from '@aws-amplify/auth/dist/esm/types';

const authConfig: AuthConfig = {
  Cognito: {
    userPoolId: process.env.NEXT_PUBLIC_USER_POOL_ID ?? '',
    userPoolClientId: process.env.NEXT_PUBLIC_USER_POOL_CLIENT_ID ?? '',
    loginWith: {
      oauth: {
        // DO NOT START WITH `https://`
        domain: process.env.NEXT_PUBLIC_OAUTH_DOMAIN ?? '',
        scopes: [
          'openid',
          'email',
          'profile',
          // Needed for the `fetchUserAttributes` function
          'aws.cognito.signin.user.admin',
        ],
        providers: [{ custom: 'Slack' }],
        // URLs must completely match the Cognito app client configuration including the trailing slash.
        redirectSignIn: ['http://localhost:3000/'],
        redirectSignOut: ['http://localhost:3000/'],
        responseType: 'code',
      },
    },
  },
};
Amplify.configure({ Auth: authConfig });

export async function authSession(): Promise<AuthSession> {
  return await fetchAuthSession();
}

export async function authCurrentUser(): Promise<AuthUser> {
  return await getCurrentUser();
}

export async function fetchAttributes(): Promise<AuthUserAttributes> {
  // This requires the `aws.cognito.signin.user.admin` scope.
  return await fetchUserAttributes();
}

export async function authSignIn(): Promise<void> {
  await signInWithRedirect({
    provider: { custom: 'Slack' },
  });
}

export async function authSignOut(): Promise<void> {
  await signOut();
}

Paste the following code to the ./my-app/src/app/page.tsx.

'use client';

import { useEffect, useState } from 'react';
import {
  authSession,
  authSignOut,
  authSignIn,
  authCurrentUser,
  fetchAttributes,
} from '@/auth';
import type { AuthUser } from '@aws-amplify/auth';
import type { AuthUserAttributes } from '@aws-amplify/auth/dist/esm/types';

export default function Home() {
  const [user, setUser] = useState<AuthUser>();
  const [attributes, setAttributes] = useState<AuthUserAttributes>();

  useEffect(() => {
    (async () => {
      const session = await authSession();
      if (session.tokens) {
        setUser(await authCurrentUser());
        setAttributes(await fetchAttributes());
      } else {
        await authSignIn();
      }
    })();
  }, []);

  return (
    <div className="flex flex-col items-center w-full h-screen max-w-screen-md mx-auto mt-8">
      <div className="flex flex-col gap-4">
        <div className="flex gap-2">
          <div className="w-20">Username:</div>
          <div>{user?.username}</div>
        </div>

        <div className="flex gap-2">
          <div className="w-20">User ID:</div>
          <div>{user?.userId}</div>
        </div>

        <div className="flex gap-2">
          <div className="w-20">Email:</div>
          <div>{attributes?.email}</div>
        </div>

        <div className="self-end">
          <button
            type="button"
            className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
            onClick={authSignOut}
          >
            Sign out
          </button>
        </div>
      </div>
    </div>
  );
}

To launch the local server, run the following command.

npm run dev

> [email protected] dev
> next dev

  ▲ Next.js 14.2.5
  - Local:        http://localhost:3000
  - Environments: .env.local

 ✓ Starting...
 ✓ Ready in 1507ms

Accessing to it, you would see the Slack sign-in page. After signing in successfully, you would see the app page displaying the user information.

More and more enterprises have introduced Slack for their employees and customers. The “Sign in with Slack” feature can significantly improve your application’s user experience (UX).

By using Amazon Cognito, developers can avoid implementing complex authentication and authorization logic. This allows them to focus more on their applications, delivering more value to users.

If you want to implement authentication using AWS Amplify with Amazon Cognito and Azure Entra ID (Azure AD), you might also like the following post.

wasabee.dev

Authenticating using AWS Amplify with Amazon Cognito and Azure Entra ID (Azure AD) | wasabee.dev

Personal notes taken in daily development work

I hope you will find this post useful.