[ad_1]
Amazon Cognito is a buyer id and entry administration resolution that scales to thousands and thousands of customers. With Cognito, you might have 4 methods to safe multi-tenant functions: person swimming pools, utility purchasers, teams, or {custom} attributes. In an earlier weblog submit titled Function-based entry management utilizing Amazon Cognito and an exterior id supplier, you discovered the way to configure Cognito authentication and authorization with a single tenant. On this submit, you’ll be taught to configure Cognito with a single person pool for a number of tenants to securely entry a business-to-business utility through the use of SAML {custom} attributes. With custom-attribute–based mostly multi-tenancy, you may retailer tenant identification knowledge like tenantName as a {custom} attribute in a person’s profile and go it to your utility. You may then deal with multi-tenancy logic in your utility and backend providers. With this method, you should use a unified sign-up and sign-in expertise to your customers. To establish the person’s tenant, your utility can use the tenantName {custom} attribute.
One Cognito person pool for a number of prospects
Clients just like the simplicity of utilizing a single Cognito person pool for his or her multi-customer utility. With this method, your prospects will use the identical URL to entry the appliance. You’ll arrange every new buyer by configuring SAML 2.0 integration with the client’s exterior id supplier (IdP). Your prospects can management entry to your utility through the use of an exterior id retailer, akin to Google Workspace, Okta, or Lively Listing Federation Service (AD FS), by which they’ll create, handle, and revoke entry for his or her customers.
After SAML integration is configured, Cognito returns a JSON net token (JWT) to the frontend through the person authentication course of. This JWT comprises attributes your utility can use for authorization and entry management. The token comprises claims in regards to the id of the authenticated person, akin to title and e-mail. You should use this id info inside your utility. You may also configure Cognito so as to add {custom} attributes to the JWT, akin to tenantName.
On this submit, we exhibit the method of conserving a mapping between a person’s e-mail area and tenant title in an Amazon DynamoDB desk. The DynamoDB desk may have an emailDomain discipline as a key and a corresponding tenantName discipline.
Cognito structure
As an example how this works, we’ll begin with a demo utility that was launched within the earlier weblog submit. The demo utility is carried out through the use of Amazon Cognito, AWS Amplify, Amazon API Gateway, AWS Lambda, Amazon DynamoDB, Amazon Easy Storage Service (Amazon S3), and Amazon CloudFront to realize a serverless structure. This structure is proven in Determine 1.
Determine 1: Demo utility structure
The workflow that occurs if you entry the net utility for the primary time utilizing your browser is as follows (the numbered steps correspond to the numbered labels within the diagram):
The client-side/frontend of the appliance prompts you to enter the e-mail that you just need to use to sign up to the appliance.
The applying invokes the Tenant Match API motion by API Gateway, which, in flip, calls the Lambda perform that takes the e-mail tackle as an enter and queries it towards the DynamoDB desk with the e-mail area. Determine 2 reveals the info saved in DynamoDB, which incorporates the tenant title and IdP ID. You may add further flexibility to this resolution by including net consumer IDs or {custom} redirect URLs. For the aim of this instance, we’re utilizing the identical redirect URL for all tenants (the consumer utility).
Determine 2: DynamoDB tenant desk
If an identical document is discovered, the Lambda perform returns the document to the AWS Amplify frontend utility.
The consumer utility makes use of the IdP ID from the response and passes it to Cognito for federated login. Cognito then reroutes the login request to the corresponding IdP. The AWS Amplify frontend utility then redirects the browser to the IdP.
On the IdP sign-in web page, you sign up with a legitimate person account (for instance, pet-app-user@okta.com or xyz@AnyOrganization.org). After you sign up efficiently, a SAML response is shipped again from the IdP to Cognito.
You may evaluation the SAML content material through the use of the directions in Methods to view a SAML response in your browser for troubleshooting, as proven in Determine 3.
Determine 3: SAML content material
Cognito handles the SAML response and maps the SAML attributes to a just-in-time person profile. The SAML teams attributes is mapped to a {custom} person pool attribute named {custom}:teams.
To establish the tenant, further attributes are populated within the JWT. After profitable authentication, a PreTokenGeneration Lambda perform is invoked, which reads the mapped {custom}:teams attribute worth from SAML, parses it, and converts it to an array. After that, the perform parses the e-mail tackle and captures the area title. It then queries the DynamoDB desk for the tenantName title through the use of the e-mail area title. Lastly, the perform units the {custom}:domainName and {custom}:tenantName attributes within the JWT, as proven following.
This attribute conversion is non-obligatory and demonstrates how you should use a PreTokenGeneration Lambda invocation to customise your JWT token claims, mapping the IdP teams to the attributes your utility acknowledges. You may also use this invocation to make further authorization selections. For instance, if person is a member of a number of teams, it’s possible you’ll select to map solely certainly one of them.
Amazon Cognito returns the JWT tokens to the AWS Amplify frontend utility. The Amplify consumer library shops the tokens and handles refreshes. This token is used to make calls to protected APIs in Amazon API Gateway.
API Gateway makes use of a Cognito person swimming pools authorizer to validate the JWT’s signature and expiration. If that is profitable, API Gateway passes the JWT to the appliance’s Lambda perform (additionally known as the backend).
The backend utility code reads the cognito:teams declare from the JWT and decides if the motion is allowed. If the person is a member of the correct group, then the motion is allowed; in any other case the motion is denied.
Implement the answer
You may implement this instance utility through the use of an AWS CloudFormation template to provision your cloud utility and AWS sources.
To deploy the demo utility described on this submit, you want the next conditions:
An AWS account.
Familiarity with navigating the AWS Administration Console or AWS CLI.
Familiarity with deploying CloudFormation templates.
To deploy the template
Select the next Launch Stack button to launch a CloudFormation stack in your account.
Be aware: The stack will launch within the N. Virginia (us-east-1) Area. To deploy this resolution into different AWS Areas, obtain the answer’s CloudFormation template from GitHub, modify it, and deploy it to the chosen Area.
The stack creates a Cognito person pool referred to as ExternalIdPDemoPoolXXXX within the AWS Area that you’ve got specified. The CloudFormation Outputs discipline comprises an inventory of values that you will want for additional configuration.
IdP configuration
The subsequent step is to configure your IdP. Every IdP has its personal process for configuration, however there are some frequent steps you want to comply with.
To configure your IdP
Present the IdP with the values for the next two properties:
Single signal on URL / Assertion Client Service URL / ACS URL (for this instance, https://<CognitoDomainURL>/saml2/idpresponse)
Viewers URI / SP Entity ID / Entity ID: (For this instance, urn:amazon:cognito:sp:<yourUserPoolID>)
Configure the sphere mapping for the SAML response within the IdP. Map the primary title, final title, e-mail, and teams (as a multi-value attribute) into SAML response attributes with the names firstName, lastName, e-mail, and teams, respectively.
Advisable: Filter the mapped teams to solely these which might be related to the appliance (for instance, by a prefix filter). There’s a 2,048-character restrict on the {custom} attribute, so filtering helps keep away from exceeding the character restrict, and in addition helps keep away from passing irrelevant info to the appliance.
In every IdP, create two demo teams referred to as pet-app-users and pet-app-admins, and create two demo customers, for instance, pet-app-user@instance.com and pet-app-admin@instance.com, after which assign one to every group, respectively.
As an example, we arrange three completely different IdPs to characterize three completely different tenants. Use the next hyperlinks for directions on the way to configure every IdP:
You will want the metadata URL or file from every IdP, as a result of you’ll use this to configure your person pool integration. For extra info, see Integrating third-party SAML id suppliers with Amazon Cognito person swimming pools.
Cognito configuration
After your IdPs are configured and your CloudFormation stack is deployed, you may configure Cognito.
To configure Cognito
Use your browser to navigate to the Cognito console, and for Consumer pool title, choose the Cognito person pool.
Determine 4: Choose the Cognito person pool
On the Signal-in expertise display screen, on the Federated id supplier sign-in tab, select Add id supplier.
Select SAML for the sign-in choice, after which enter the values to your IdP. You may both add the metadata XML file or present the metadata endpoint URL. Add mapping for the attributes as proven in Determine 5.
Determine 5: Attribute mappings for the IdP
Upon completion you will notice the brand new IdP displayed as proven in Determine 6.
Determine 6: Listing of federated IdPs
On the App integration tab, choose the app consumer that was created by the CloudFormation template.
Determine 7: Choose the app consumer
Beneath Hosted UI, select Edit. Beneath Identification suppliers, choose the Identification Suppliers that you just need to arrange for federated login, and save the change.
Determine 8: Choose id suppliers
API gateway
The instance utility makes use of a serverless backend. There are two API operations outlined on this instance, as proven in Determine 9. One operation will get tenant particulars and the opposite is the /pets API operation, which fetches info on pets based mostly on person id. The TenantMatch API operation will likely be run if you sign up together with your e-mail tackle. The operation passes your e-mail tackle to the backend Lambda perform.
Determine 9: Instance APIs
Lambda capabilities
You will notice three Lambda capabilities deployed within the instance utility, as proven in Determine 10.
Determine 10: Lambda capabilities
The primary one is GetTenantInfo, which is used for the TenantMatch API operation. It reads the info from the TenantTable based mostly on the e-mail area and passes the document again to the appliance. The second perform is PreTokenGeneration, which reads the mapped {custom}:teams attribute worth, parses it, converts it to an array, after which shops it within the cognito:teams declare. The second Lambda perform is invoked by the Cognito person pool after sign-in is profitable. So as to customise the mapping, you may edit the Lambda perform’s code within the index.js file and redeploy. The third Lambda perform is added to help the Pets API operation.
DynamoDB tables
You will notice three DynamoDB tables deployed within the instance utility, as proven in Determine 11.
Determine 11: DynamoDB tables
The TenantTable desk holds the tenant particulars the place you could add the mapping between the client area and the IdP ID setup in Cognito. This method could be expanded so as to add extra flexibility in case you need to add {custom} redirect URLs or Cognito app IDs for every tenant. You should create entries to correspond to the IdPs you might have configured, as proven in Determine 12.
Determine 12: Tenant IdP mappings desk
Along with TenantTable, there’s the ExternalIdPDemo-ItemsTable desk, which holds the info associated to the Pets utility, based mostly on person id. There may be additionally ExternalIdPDemo-UsersTable, which holds person particulars just like the username, final pressured sign-out time, and TTL required for the appliance to handle the person session.
Now you can sign up to the instance utility by every IdP by navigating to the appliance URL discovered within the CloudFormation Outputs part, as proven in Determine 13.
Determine 13: Cognito sign-in display screen
You may be redirected to the IdP, as proven in Determine 14.
Determine 14: Google Workspace sign-in display screen
The AWS Amplify frontend utility parses the JWT to establish the tenant title and supply authorization based mostly on group membership, as proven in Determine 15.
Determine 15: Utility house display screen upon profitable sign-in
If a distinct person logs in with a distinct position, the AWS Amplify frontend utility supplies authorization based mostly on particular content material of the JWT.
Conclusion
You may combine your utility together with your buyer’s IdP of selection for authentication and authorization and map info from the IdP to the appliance. By utilizing Amazon Cognito, you may normalize the construction of the JWT token that’s used for this course of, to be able to add a number of IdPs, every for a distinct tenant, by a single Cognito person pool. You are able to do all this with out altering utility code. The native integration of Amazon API Gateway with the Cognito person swimming pools authorizer streamlines your validation of the JWT integrity, and after the JWT has been validated, you should use it to make authorization selections in your utility’s backend. By following the instance on this submit, you may concentrate on what differentiates your utility, and let AWS do the undifferentiated heavy lifting of id administration to your customer-facing functions.
For the code examples described on this submit, see the amazon-cognito-example-for-multi-tenant code repository on GitHub. To be taught extra about utilizing Cognito with exterior IdPs, see the Amazon Cognito documentation. You may also be taught to construct software program as a service (SaaS) utility architectures on AWS. When you’ve got any questions on Cognito or another AWS providers, it’s possible you’ll submit them to AWS re:Submit.
When you’ve got suggestions about this submit, submit feedback within the Feedback part beneath. When you’ve got questions on this submit, begin a brand new thread on the AWS Safety, Identification, & Compliance re:Submit or contact AWS Help.
Need extra AWS Safety information? Observe us on Twitter.
Ray Zaman
A Principal Options Architect with AWS, Ray has over 30 years of expertise serving to prospects in finance, healthcare, insurance coverage, manufacturing, media, petrochemical, pharmaceutical, public utility, retail, semiconductor, telecommunications, and waste administration industries construct know-how options.
Neela Kulkarni
Neela is a Options Architect with Amazon Net Providers. She primarily serves impartial software program distributors within the Northeast US, offering architectural steering and finest follow suggestions for brand spanking new and present workloads. Exterior of labor, she enjoys touring, swimming, and spending time together with her household.
Yuri Duchovny
Yuri is a New York–based mostly Options Architect specializing in cloud safety, id, and compliance. He helps cloud transformations at massive enterprises, serving to them make optimum know-how and organizational selections. Previous to his AWS position, Yuri’s areas of focus included utility and networking safety, DoS, and fraud safety. Exterior of labor, he enjoys snowboarding, crusing, and touring the world.
Abdul Qadir
Abdul is an AWS Options Architect based mostly in New Jersey. He works with impartial software program distributors within the Northeast US and helps prospects construct well-architected options on the AWS Cloud platform.
[ad_2]
Source link
