Control user access using AWS Cognito

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 sig nin 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 allow lists.
  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 in to the console, and navigate to Cognito by typing it into the Find Services search bar.

Open Cognito service in AWS by typing Cognito into the Find Services search bar

Step 2: Configure a user pool in your Cognito service 

Click Manage User Pools.  

Manager User Pools button in the Amazon Cognito dialog

Then, click Create a user pool.

Your User Pools page with Create a user pool button highlighted

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.

Create a user pool dialog with App XYZ in the Pool name field and the Step through settings link highlighted

Step 2b: Select sign in method

Select how you will allow users to sign in. AppSheet recommends having users sign in using 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.

How do you want your end users to sign in with the Email addresses or phone number item selected and the name field marked as required under Which standard attributes do you want to require?

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 up themselves.

If you allow users to sign up themselves, 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 sign in.

Maximum length is set to 8 and all options are selected under What password strength do you want to require? And Allow users to sign themselves up is selected under Do you want to allow users to sign themselves up?

Step 2d: Require user verification

Multi-factor authentication and SMS message are both optional. 

AppSheet strongly recommends verifying the user information.

Email is selected under Which attributes do you want to verify? The New Role Name field is set to AppXYZ-SMS-Role under You must provide a role to allow Amazon Cognito to send SMS messages

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.

Do you want to customize your email address? screen

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 />

Screen available for customizing email verification and user invitation messages

Step 2g: Add tags

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

Do you want to add tags for this user pool? with the Next step button highlighted and no tags added

Step 2h: Remember user's devices

Remembering a user's device is also optional. We recommend that you set this option to No. Once sign-in occurs, AppSheet remembers the user even if the app is closed or the device is restarted. It is only if the user explicitly logs off AppSheet that the Cognito authentication is requested again. At this stage, you would normally want to make sure the sign-in process occurs again. If you ask Cognito to remember the user's devices, then Cognito will short-circuit the sign-in process and automatically sign-in the existing user. This is usually not the desired behavior.

Do you want to remember your user

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.

App client name field is set to AppSheet, the Generate client secret option is selected, and Create app client button is highlighted in the Which app clients will have access to this user pool?

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 left-hand 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

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.

Select Cognito User Pool under Enabled Identity Providers, enter the callback URLs, and select Authorization code grant for Allowed OAuth Flows, and email, openid, and profile for Allowed OAuth Scopes in the What identity providers and OAuth 2.0 settings should be used for your app clients?

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 (for example, appsheettest in the example below). 

You will need the full domain that is, https://{yourdomainname}/auth/{AWS region}/amazoncognito.com) when configuring your app 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 + New Auth Domain, give your auth domain a name, and select AWS Cognito as the provider

Step 3b: Configure the domain with the Cognito information

The App Client ID and App Client Secret come from the App clients page in the left-hand menu of the Cognito settings dashboard. The Domain Endpoint comes from the Domain name page in the lefhand menu of the Cognito settings dashboard.

Add Cognito configuration dialog with App Client Id, App Client Secret, and Domain Endpoint fields hightlighted

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:

  1. Open your app in the editor.
  2. Go to the Security > Domain Authentication pane. 
  3. Enable the Require domain authentication option. 
  4. Select the domain source created in step 3 in the Authentication domain source drop-down.
Note: AppSheet does not currently support the ability to select a Restrict by domain or Authentication group when working with Cognito. These options can be left at their default values.

Step 5: Test it

Open the Share dialog and copy the browser link. See Send users a link to your app. Open a new private session in your browser (incognito in Chrome), and paste the URL. You will see the option to authenticate with Cognito.

Option to sign in with AWS Cognito

Additional UI customization

Cognito allows you to customize the look and feel of the sign in page. Access these settings by going to the UI customization page in the left-hand menu of the Cognito settings dashboard.

Was this helpful?
How can we improve it?
Search
Clear search
Close search
Google apps
Main menu
Search Help Center
false
false