AWS Cognito User Management Kit

A comprehensive Vue 3 starter application with AWS Cognito integration for user authentication and management. This project provides a running-ready foundation for building secure web applications with user registration, authentication, and protected routes.

Author: Marco Chirico
Version: 1.0.0
License: MIT

Overview

This starter kit combines a modern Vue 3 application built with Vite and AWS Cognito for robust user authentication. The included CloudFormation template automates the creation of necessary AWS resources, making it easy to deploy and manage user pools and application clients.

Features

• Complete Authentication Flow: Sign up, email confirmation, login, and logout functionality
• Protected Routes: Route guards for authenticated users
• AWS Cognito Integration: Seamless integration with AWS Cognito User Pools
• CloudFormation Infrastructure: Automated AWS resource provisioning
• Environment Configuration: Flexible configuration through environment variables
• Modern Vue 3 Setup: Built with Composition API and Vue Router

Application Screenshots

🏠 Home Page

Welcome page with navigation to authentication flows

📝 Sign Up Page

User registration form with email verification

🔐 Sign In Page

User login form with authentication

🛡️ Protected Dashboard

Authenticated user dashboard with user information

Project Structure

├── src/
│   ├── aws-config.js          # AWS Amplify configuration
│   ├── components/            # Vue components
│   ├── views/                 # Page components
│   └── router/                # Vue Router configuration
├── cloudformation/
│   └── cognito.yml           # AWS CloudFormation template
├── .env.example              # Environment variables template
└── README.md                 # This file

Prerequisites

• Node.js 16+ and npm
• AWS CLI configured with appropriate permissions
• Basic knowledge of Vue 3 and AWS Cognito

Installation and Setup

1. Environment Configuration

Copy the environment template and configure your variables:

cp .env.example .env

Edit .env with your AWS region and other configuration values.

2. Install Dependencies

npm install

3. Deploy AWS Resources

Deploy the CloudFormation stack to create your Cognito User Pool and App Client:

aws cloudformation deploy \
  --template-file cloudformation/cognito.yml \
  --stack-name cognito-auth-kit \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    UserPoolName=my-user-pool \
    AppClientName=my-app-client

4. Update Configuration

After successful deployment, update your .env file with the CloudFormation outputs:

• VITE_USER_POOL_ID
• VITE_USER_POOL_CLIENT_ID
• VITE_REGION

5. Start Development Server

npm run dev

The application will be available at http://localhost:5173.

Configuration Options

AWS Cognito Settings

The CloudFormation template creates a User Pool with the following default settings:

• Email verification required
• Standard password policy
• No application client secret (public client)

You can customize these settings by modifying the cloudformation/cognito.yml template before deployment.

Environment Variables

Variable	Description	Required
VITE_USER_POOL_ID	Cognito User Pool ID	Yes
VITE_USER_POOL_CLIENT_ID	Cognito App Client ID	Yes
VITE_REGION	AWS Region	Yes

Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build

Customization

The application is structured for easy customization:

• Modify authentication flows in src/views/
• Update styling in component files
• Extend AWS configuration in src/aws-config.js

Deployment

Production Build

npm run build

AWS Amplify Hosting

This project is compatible with AWS Amplify hosting. Connect your repository to Amplify Console for automatic deployments.

Other Platforms

The built application can be deployed to any static hosting service:

• Netlify
• Vercel
• GitHub Pages
• S3 + CloudFront

Security Considerations

• Never commit .env files to version control
• Use appropriate IAM roles and policies
• Consider implementing additional security measures for production
• Review and customize the password policy as needed

Troubleshooting

Common Issues

1. CORS Errors: Ensure your Cognito App Client is configured for your domain
2. Authentication Failures: Verify environment variables are correctly set
3. CloudFormation Deployment Failures: Check AWS CLI permissions and region settings

Getting Help

• Review AWS Cognito documentation
• Check Vue 3 and Vite documentation
• Examine CloudFormation template for resource configuration

Contributing

This is a starter template designed for immediate use. For customizations and improvements, consider:

• Adding additional authentication methods
• Implementing user profile management
• Extending the CloudFormation template for additional AWS services

License

MIT License - see LICENSE file for details.

---

Note: This starter kit is designed for educational and development purposes. For production use, ensure proper security review and testing of all authentication flows.