AWS Cognito is a service provided by Amazon Web Services, and is available in AppSheet Business Subscriptions. It allows you to set up your own authentication source. You can provision users with explicit passwords or using one of their existing social signin accounts, and you utilize Cognito to control secure access to your AppSheet apps. There are three reasons to do this: 

  1. You would like to manage user access control at a scale that goes beyond simple whitelists.
  2. You want to be able to provision and manage the users, control password policy, and utilize other richer characteristics of an authentication source.
  3. You cannot use your corporate domain controller as an auth source, because your users come from outside your corporate domain.

Using AWS Cognito requires that you set up an AWS account. This is not part of the AppSheet service. This article explains the basics of setting up a Cognito service and configuring it to be accessible from your AppSheet account.

Step 1: Open the Cognito service in AWS

Go to http://aws.amazon.com, sign into the console, and navigate to Cognito by typing it into the Find Services search bar.

Step 2: Configure a User Pool in your Cognito service 

Click "Manage User Pools."  

Then click "Create a user pool."

In the next few steps, we will create and configure a User Pool. The users in the  User Pool will define the people who have access to your app. 

Step 2a: Give your app a name

You can create as many user pools as you need. Some app creators choose to make a user pool for each app. Others choose to apply a single user pool to multiple apps. Whatever your use case, choose a name that will help you know what app(s) this user pool applies to. Then click "Step through settings."

Step 2b: Select sign in method

Select how you will allow users to sign in. AppSheet recommends having users sign in via email. Since email addresses are unique, they work really well inside apps as unique identifiers. The email each user signs up with will be accessible inside your app using the USEREMAIL() formula.

You can require users to enter additional information under "Which standard attributes do you want to require?" These standard attributes will be visible in the Cognito User Pool. However, the standard attributes are not accessible from inside AppSheet apps.

Step 2c: Set password requirements

On this screen you can choose what requirements to apply to passwords. Also, you can choose whether users can sign themselves up.

If you allow users to sign themselves up, then new users will see a sign up link the first time they access the app. Clicking the link will take them to a sign up page where they can create a user profile. This would allow anyone with a link to the app to sign up.

If you only allow administrators to create users, then the sign up link will be hidden. An admin with access to the AWS Cognito account will need to add the user to the User Pool. This will send an automatic email to the user with their temporary password. The user will be prompted to change their password on first login.

Step 2d: Require user verification

Multi-factor authentication and SMS message are both optional. 

AppSheet strongly recommends verifying the user information.

Step 2e: Email address customization

You can customize the email address from which automated emails will be sent. This is optional, but recommended by AWS as a best practice

Step 2f: Email message customization

You can customize the automated email messages. These fields accept standard html tags. If you want to add a line break, you can use the html tag: <br />

Step 2g: Tags

Tags are optional and not used for basic setups. For more information about tags, please see the Amazon help doc here.

Step 2h: Remember user's devices

Remembering a user's device is also optional. Doing so will significantly improve the app user experience so users don't have to repeatedly sign in.

Step 2i: Add an App Client

Click to "Add an app client." When you define an app "client" in Cognito, you are telling Cognito to expect AppSheet to interact with it to ask users to sign in. 

Give your App Client a name and check the box to generate client secret. Then click "Create app client." Cognito will create a Client Id and a Client Secret, which you can access after setup is complete. You will need this information when configuring your app back in AppSheet.

It is important that you do not check the second option ("Only allow ...."). This will prevent the standard OAuth2.0 authentication process from succeeding.

Step 2j: Triggers

Triggers are an advanced option that allow you to further customize the authentication process. They are optional and not required for the basic setup.

Step 2k: Review

Review your settings and click "Create pool"

Step 2l: Set the callback URLs

Navigate to "App client settings" in the lefthand menu. These settings allow us to tell Cognito how to respond when AppSheet interacts with it. 

Copy the following callback URLs and paste them in the Callback URL(s) field. They are case sensitive and must be separated by a comma and a space.
https://www.appsheet.com/Account/ELC, http://localhost:53519/Account/ELC

Please note the second callback url is not strictly required --- it is only necessary if you request AppSheet to debug your application at some point in the future.

Step 2m: Define the Domain for your Cognito User Pool

Navigate to "Domain name" in the lefthand menu. You can assign a real domain or a fake domain (eg: 'appsheettest' in the example below). 

You will need the full domain (e.g. https://{yourdomainname}/auth/{AWS region}/amazoncognito.com) when configuring your app back in AppSheet.

Step 3: Configure your AppSheet account

Now that you have set up your Cognito User Pool, you need to register it in your AppSheet account. Do so from the My Account > Integrations > Auth Domains pane.

Step 3a: Add a new auth domain

Click "+ Add Auth Domain," give your auth domain a name, and select AWS Cognito as the provider

Step 3b: Configure it with the Cognito information

The App Client ID and App Client Secret come from the "App clients" page in the lefthand menu of the Cognito settings dashboard. The Domain Endpoint comes from the "Domain name" page in the lefthand menu of the Cognito settings dashboard.

Step 4: Configure your app

You can now use this domain auth source in any of your apps. To connect your app to the auth source, go to the Security > Domain Authentication page. 

Toggle the "Require domain authentication" option on. 

Then choose the Authentication domain source. The name you see here corresponds to what you setup in step 3a above.

Please note that when AppSheet does not currently support the ability to select an Authentication domain or Authentication group when working with Cognito. These options can be left at their default values as seen above.

Step 5: Test it out

Navigate to the Users > Links page and grab the Browser Link. Open a new private session in your browser (incognito in Chrome), and paste the url. You will see the option to authenticate with Cognito!

Additional UI Customization

Cognito allows you to customize the look and feel of the login page. Access these settings by going to the "UI customization" page in the lefthand menu of the Cognito settings dashboard.

Did this answer your question?