Knowledge Base Home

Create an Enterprise Organization with Amazon Cognito

Kaleido offers compatibility with Amazon Cognito to create fully-managed Enterprise Organizations within the Kaleido platform. AWS Cognito provides integration over Open ID Connect and SAML to your Enterprise User Registry, as well as pre-built integrations for SaaS user registries such as Google Sign-In. Enterprise Orgs are directly bound to the Cognito User Pool of your choice, providing complete control over the users with access to your Kaleido resources. The Identity Providers and login schemas are entirely configurable, allowing you to implement access flows in accordance with your organizational standards. The only mandate from the Kaleido perspective is the mapping of an Identity Provider login to an email that has been registered against the Enterprise Organization. This sample flow makes use of Google Sign-In as the Identity Provider, however alternate methods such as Open ID, SAML, Facebook, etc… can be leveraged as long as they ultimately resolve to a registered email on the targeted Enterprise Org.

NOTE: Refer to the Video Tutorials section for an animated walkthrough of configuring your Enterprise Org against a Cognito Pool that leverages Google Sign-In.

Creating a Custom Cognito User Pool and Domain

These steps outline the creation of a custom user pool and domain using AWS Cognito. These AWS resources are prerequisites for creating a Kaleido Enterprise Org.

  1. Log into your AWS account and navigate to the Cognito service.
  2. Click the Manage User Pools button to create the custom user pool. If you have no existing user pools, follow the click here to create a user pool hyperlink to generate your first pool.
  3. If you prefer to leverage an existing user pool, it must be edited to require email as the username attribute. The email field is stored against the Enterprise Organization resource on the Kaleido side, ensuring that only authenticated and invited users can access the org. Invited members, identified via an email address, access the Kaleido Enterprise Organization through its unique login URL that ultimately redirects to the chosen Identity Provider schema within the Cognito user pool. The last section on this page expands on Identity Providers and demonstrates an example flow using Google Sign In. Refer to the approach in step 5 for adding the email attribute to an existing pool.
  4. Supply a name for your user pool in the Pool name box and select Review defaults as the method for pool creation.
  5. Before finalizing the pool, you need to specify email addresses as the required sign in attribute. Click the Attributes tab in the lefthand navigation panel to view the available sign in approaches. In the How do you want your end users to sign in? section select the Email address or phone number option. Make sure the Allow email addresses field is enabled. In the Which standard attributes do you want to require? section select email as your required attribute. Click Next Step at the bottom of the screen to save these configurations.
  6. Next, click the App clients tab in the lefthand navigation panel to create an application client for the pool. Click the Add an app client hyperlink to provision the client credentials. The credentials are visible once the pool has been created.
  7. Supply a name for the app client in the App client name box and leave the Generate client secret option enabled. Kaleido needs both the client ID and secret in order to securely communicate with your Cognito Pool. Click the Create app client button to finish.
  8. On the new screen click the Return to pool details hyperlink to review your settings. Ensure that email is present for the Required attributes and Username attributes fields. Click the Create pool button at the bottom of the screen to finalize your custom Cognito pool.
  9. Lastly, provision a domain for the Cognito enterprise sign in. Click the Domain name tab in the lefthand navigation and supply a prefix for the Amazon Cognito domain. Click the Check availability button to make sure the domain is available. Click Save changes to save your domain.

Generating an Enterprise Organization in the Kaleido Console

These steps outline the creation of an Enterprise Organization through the platform UI. Ensure that you have provisioned the requisite resources (User Registry, Application Client and Domain) before proceeding. Refer to the previous section for instructions on creating these cloud resources.

  1. Log into your Kaleido Organization and click the Settings tab at the top right portion of the screen. Click the Organizational Settings tab and click the + New Enterprise Org button.
  2. Supply an “Organization Name” for your Enterprise Org.
  3. Enter your “Amazon Cognito Domain” without the https:// prefix.
  4. Enter your Cognito User Pool ID. You can retrieve this value by clicking the General Settings tab in the lefthand navigation panel within your Cognito User Pool.
  5. Enter the AWS region for your User Pool. This value is the prefix of the User Pool ID. For example, us-east-2
  6. Enter the Application Client ID and Secret from your User Pool. These values can be retrieved by clicking the App clients tab in the lefthand navigation panel within your targeted Cognito User Pool.
  7. Click the Create button at the bottom of the screen once you have populated all of the mandatory fields.
  8. Take note of the Callback URL for your Enterprise Org. This value needs to be configured against your application client, allowing it to resolve with Kaleido upon the Identity Provider sign in. The next section details the steps necessary to configure the application client.
  9. Additionally take note of the new login URL for the Enterprise Org. This is the only route through which it can be accessed.
  10. Lastly, click the Add dropdown and select Organization Member. Input an email address that will map to your Cognito Identity Provider. The first user attempting to sign into the Enterprise Org MUST be registered.

NOTE: The Enterprise Org exists in “draft” stage until a successful login from a registered email address. Upon a successful login, the Enterprise Org will be detached from your standard Kaleido Org and exist under the ownership of the first logged in user. From that point the Enterprise Org is only accessible via its unique login URL and maintains no relationship with the original Kaleido Org. The next section demonstrates one potential approach via Google Sign-In for logging in and detaching the newly created org.

Configuring an External Identity Provider & Logging into your Enterprise Org

These steps outline the creation of an OAuth client using the Google Sign-In flow, and the configuration of an Identity Provider and Application Client within AWS Cognito. Note that Google is not the mandated Identity Provider. We simply use Google Sign-In as an example option because it provides a convenient schema for email attribute mapping. The email attribute is what Kaleido will ultimately verify the login attempt against. You can mirror this approach when configuring alternate Identity Providers.

  1. Visit the Integrating Google Sign-In developer site.
  2. Click the CONFIGURE A PROJECT button and supply a name for your project. Click Next
  3. Configure your OAuth Client by providing a product name to be shown on the user consent screen. Click Next
  4. Select Web browser as the scope for the OAuth Client and enter your Amazon Cognito domain as the “Authorized Javascript Origin”. Click Create to provision the client configuration. Leave the window with the credentials open. You will need to configure a redirect URL in a later step.
  5. Within your Cognito User Pool, click the Identity providers tab in the lefthand navigation panel and select Google.
  6. Input the Client ID and secret from the previous step into the appropriate fields. For the “Authorize scope” field, enumerate profile email openid and click the Enable Google button to finish.
  7. Click the Attribute mapping tab at the bottom of the lefthand navigation panel and select Googleas the external identity provider to map attributes from.
  8. Capture email as the Google attribute
  9. Expand the User pool attribute dropdown and select Email. Click the Save changes button at the bottom of the screen
  10. Next, click the App client settings and select Google as your Enabled Identity Provider.
  11. Add the callback URL from the Enterprise Org creation into the Callback URL(s) field
  12. In the Allowed OAuth Flows section enable the following: Authorization code grantemailand openid. Click the Save changes button at the bottom of the screen to configure the client.
  13. Now you’re ready to login. Follow the login URL for your new Enterprise Org. This will redirect you to Google Sign-In or whichever implementation you have selected.
  14. IMPORTANT: If using Google Sign-In, your first attempt will fail with the following error – Error: redirect_uri_mismatch. Copy the supplied redirect URL in the body of the error message and access the configuration for the OAuth client. With Google Sign-In this can be done by accessing the developers API console. The pop-up window exposing your OAuth client ID/secret also contains a hyperlink to the console. Click the Credentials tab in the lefthand navigation and select the OAuth client ID that has been configured in Cognito. Paste the redirect URL in the Authorized redirect URLs field and click Save.
  15. Now refresh your enterprise login window. Supply the email/password combination (alternatively supply a username/password combination that resolves to a registered email on the Kaleido Enterprise Org) and proceed to log into the new org. Note that the user with the first successful login will become the owner of the org.
Prev Private Connections via VPC PrivateLink Endpoints Next Provisioning a Node with AWS Integrations