[SEO Subhead]
This Guidance demonstrates a custom authentication flow with Amazon Cognito. Using a decentralized web application (dApp), you can authenticate with your digital wallet through Amazon Cognito to be granted temporary AWS credentials. These credentials then give you access to AWS services so you can securely proxy API calls to third-party APIs. This Guidance offers two different authorization methods, allowing you to choose the method most convenient for you.
Please note: [Disclaimer]
Architecture Diagram
[Architecture diagram description]
Step 1
Download the dApp from the web by connecting to the Amazon CloudFront distribution endpoint, which uses an Amazon Simple Storage Service (Amazon S3) bucket as Origin.
Step 2
You will be asked to sign a generated message using your digital wallet and private key. Then, the dApp sends the signature to Amazon Cognito for verification.
Step 3
Amazon Cognito validates if the signature has been correctly signed by your wallet. If yes, a new session is established, and temporary AWS credentials are vended to the application.
Step 4
Using the valid credentials, the dApp is now authorized to call the Amazon API Gateway endpoint to connect to a third-party API.
Step 5
An AWS Lambda function can be used as backend integration for complex logic or if you need to make multiple underlying API calls to the third-party APIs.
Step 6
Direct proxy calls can be made through API Gateway. No Lambda function is executed. API Keys* are injected impromptu using the Mapping Template.
* The private API Keys of our Web3 providers are never exposed to the dApp and remain on the backend.
Step 7
Graphical assets are stored on InterPlanetary File System (IPFS) or HTTP.**
** IPFS is a storage protocol that is ideal for serving non-fungible tokens (NFTs) assets. HTTP is not ideal to serve NFTs assets, as it ties them to your host and domain name. You can also host the dApp itself on IPFS.
Step 1
Download the dApp from the web by connecting to the Amazon CloudFront distribution endpoint, which uses an Amazon Simple Storage Service (Amazon S3) bucket as Origin.
Step 2
You will be asked to sign a generated message using your digital wallet and private key. Then, the dApp sends the signature to Amazon Cognito for verification.
Step 3
Amazon Cognito validates if the signature has been correctly signed by your wallet. If yes, a new session is established, and temporary AWS credentials are vended to the application.
Step 4
Using the valid credentials, the dApp is now authorized to call the Amazon API Gateway endpoint to connect to a third-party API.
Step 5
An AWS Lambda function can be used as backend integration for complex logic or if you need to make multiple underlying API calls to the third-party APIs.
Step 6
Direct proxy calls can be made through API Gateway. No Lambda function is executed. API Keys* are injected impromptu using the Mapping Template.
* The private API Keys of our Web3 providers are never exposed to the dApp and remain on the backend.
Step 7
Graphical assets are stored on InterPlanetary File System (IPFS) or HTTP.**
** IPFS is a storage protocol that is ideal for serving non-fungible tokens (NFTs) assets. HTTP is not ideal to serve NFTs assets, as it ties them to your host and domain name. You can also host the dApp itself on IPFS.
Well-Architected Pillars
The AWS Well-Architected Framework helps you understand the pros and cons of the decisions you make when building systems in the cloud. The six pillars of the Framework allow you to learn architectural best practices for designing and operating reliable, secure, efficient, cost-effective, and sustainable systems. Using the AWS Well-Architected Tool, available at no charge in the AWS Management Console, you can review your workloads against these best practices by answering a set of questions for each pillar.
The architecture diagram above is an example of a Solution created with Well-Architected best practices in mind. To be fully Well-Architected, you should follow as many Well-Architected best practices as possible.
-
Operational ExcellenceRead the Operational Excellence whitepaper
This Guidance uses the AWS Serverless Application Model (SAM) to define, build, and deploy architecture resources. If Lambda functions and API Gateway encounter failures or errors, you can set up Amazon CloudWatch alarms to address unexpected issues. Review this blog post for more information: How to get notified on specific Lambda function error patterns using CloudWatch.
-
SecurityRead the Security whitepaper
This Guidance employs a custom authentication flow where users sign a generated message with their digital wallet (crypto wallet) to answer an Amazon Cognito custom challenge, creating identities in the User Pool. Additionally, this Guidance demonstrates two authorization methods for API Gateway: using Amazon Cognito User Pool identity token or Amazon Cognito Identity Pool and AWS Identity and Access Management (IAM) roles for authenticated and unauthenticated users.
You can securely proxy API calls to third-party Web3 provider APIs, a principle applicable to any third-party API. API Gateway secures access to the backend by providing different authorization mechanisms. Data from third-party Web3 APIs is encrypted in transit as it travels through API Gateway to the client decentralized web dApp.
-
ReliabilityRead the Reliability whitepaper
This Guidance uses the highly available managed services, Amazon Cognito and API Gateway. Both services generate CloudWatch metrics that can invoke alarms, and detailed API Gateway logs provide visibility into received HTTP requests. These observability features help you monitor the health of the AWS Region in which you deploy the Guidance to support overall reliability of your workloads.
-
Performance EfficiencyRead the Performance Efficiency whitepaper
The source code available on GitHub and the SAM template provided in the backend folder can serve as a boilerplate for your own project. You can then configure API Gateway to point to the desired backend API or to run your chosen Lambda function.
-
Cost OptimizationRead the Cost Optimization whitepaper
This Guidance uses Amazon Cognito and API Gateway, both serverless services that offer a free tier for getting started. Amazon Cognito charges are based on the number of monthly active users (MAU) in your User Pool, while API Gateway charges are based on the number of API calls received and the volume of data transferred out.
-
SustainabilityRead the Sustainability whitepaper
Wherever possible, this Guidance proxies API requests directly to backend integrations instead of initiating Lambda functions, reducing resource consumption. The Lambda functions involved run only for the required duration. This approach enables a sustainable and cost-effective solution, consuming resources only when necessary.
Implementation Resources
A detailed guide is provided to experiment and use within your AWS account. Each stage of building the Guidance, including deployment, usage, and cleanup, is examined to prepare it for deployment.
The sample code is a starting point. It is industry validated, prescriptive but not definitive, and a peek under the hood to help you begin.
Related Content
[Title]
Disclaimer
The sample code; software libraries; command line tools; proofs of concept; templates; or other related technology (including any of the foregoing that are provided by our personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.
References to third-party services or organizations in this Guidance do not imply an endorsement, sponsorship, or affiliation between Amazon or AWS and the third party. Guidance from AWS is a technical starting point, and you can customize your integration with third-party services when you deploy the architecture.