alusru/amazon-cognito-example-for-multi-tenant

Use Amazon Cognito with SAML to support a multi-tenant business to business application with a single User Pool

Overview

This sample is the companion code to the blog post “Learn to use SAML with Amazon Cognito to support a multi-tenant application with a single User Pool“. This example can be used as a starting point for deploying a single Cognito User Pool together with multiple external identity providers (IdP).

With this sample your customers can use the same URL to access your application. You set up each new customer by configuring Security Assertion Markup Language (SAML)integration with your customer’s external identity provider (IdP). By controlling access to your application using an external identity store, such as Google Workspace, OKTA, or Active Directory Federation Service (AD FS) your customers can create, manage, and revoke access for their users.

Once SAML integration is configured, the user authentication process creates a JSON web token (JWT) in the user’s browser containing attributes the application can use for authorization and access control. The token contains claims about the identity of the authenticated user, such as name and email. You can use this identity information inside your application. You can also add custom attributes to be populated in the JWT such as tenantName and usergroups.

It contains all that is needed in order to create a serverless web application with Amazon Cognito, Amazon API Gateway, AWS Lambda and Amazon DynamoDB.

• Amazon API Gateway: Amazon API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. Combined with Amazon Cognito User Pools Authorizer - it handles validation of the user's tokens.
• AWS Lambda: AWS Lambda lets you run code without provisioning or managing servers. You pay only for the compute time you consume - there is no charge when your code is not running. This is the serverless compute service that runs the backend of our app (behind Amazon API Gateway). requests are only forwarded if the user is authenticated and has a valid JWT token.
• Amazon Cognito User Pools: Amazon Cognito lets you add user sign-up, sign-in, and access control to your web and mobile apps quickly and easily. Amazon Cognito scales to millions of users and supports sign-in with social identity providers, such as Facebook, Google, and Amazon, and enterprise identity providers via SAML 2.0.
• Amazon DynamoDB: Amazon DynamoDB is a serverless key-value and document database that delivers single-digit millisecond performance at any scale. It is used as the persistence storage layer for our example application.

Modules

The sample contains the following modules within these sub-folders:

/cloudformationtemplate

This example can be deployed using AWS CloudFormation.

You may deploy this template in your AWS account and it will create all the resources needed in order to create the sample application. When prompted please enter a stack name and a unique bucket name for a new bucket that will be created by the stack.

Once the CloudFormation script is successfully executed, you will be able to capture all the output parameters that you would need to complete the setup.

Here are the key output parameters that you need to test the example application.

UI Url: This is the URL you can open in your browser to test the application.

CognitoDomainOutput and UserPoolIdOutput: These are needed for IdP configuration.

Additional setup is required. For complete instructions please refer to the blog post referenced above.

/ui-react

A simple React frontend that connects to the backend API. It employs AWS Amplify that provides react and other components for simpler integration with various AWS services from web and mobile applications. AWS Amplify can manage all aspects of a project, but since AWS Cloud Development Kit (AWS CDK) was used, a manual setup process was followed.

Tenant Configuration

CloudFormattion will create three DynamoDB tables in your AWS account. You need to add tenant details in TenantTable. The TenantTable holds the tenant details where you can store mapping between the customer domain and the IdP ID Setup in Cognito. Please refer to the blog post to add the TenantDetail with IDP id, that you will create in Amazon Cognito.

IdP Configuration Instructions

• OKTA:
  • Please refer to this link to setup OKTA as a IDP provider under client application web.
• ADFS:
  • Please refer to this link to setup ADFS as a IDP provider under client application web.
• Google Workspace:
  • Please refer to this link to setup Google Workspace as a IDP provider under client application web.

Related Resources

• Role-based access control using Amazon Cognito and an external identity provider
• AWS re:Inforce 2019: Identity and Access Control for Custom Enterprise Applications (SDD412)
• Learn to use SAML with Amazon Cognito to support a multi-tenant application with a single User Pool

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.