Hello everyone! 
Here is a step by step guide on how to create External Apps with a custom login page. External apps are available on the Business plan or above. If you'd like to explore whether this plan meets your organization's needs, feel free to book a demo here.
- Enable external apps.
- Create a custom login page.
- Create a landing page.
- Manage user permissions.
- Troubleshooting
Setup
The first step is to enable external apps. We can do this by going to Settings -> External Apps -> Enable external apps.
Then, specify the domains we'll use for internal users:
After clicking 'Continue,' we'll see the External Users Permission Group:
As well as the External Apps folder:
Now that our org is set up for external apps and users, let's create our custom login page!
Custom Login Page
The login page is part of Branding. We can choose to keep the Retool managed page or create a custom one. For the latter, we must create a public app, and we can do this from the Branding settings page. Go to Settings -> Branding and click 'Manage.'
Select an existing public app or create a new one:
Note: I decided to go for
mydomain.retool.com/app/login but we can customize it to our preference.
This will create a great template for us to build on top:
The template will include a Resource query:
As we can see in the settings for this Resource, the email and password fields are already set to the values of the input components on the form. If we created an app from scratch, we would have to add the necessary components and a Resource query with 'User Action' as the resource, 'Account' for the type and 'Log in' for the action.
Do not add an event handler to navigate the user after a successful login. We'll set a custom landing page for our external users instead.
Users of any org can decide if they want to login with email & password credentials, or with Google. The button to sign in with Google already has an event handler configured:
If we have a custom domain, we should replace login.retool.com with our domain to ensure that the Google sign-in page displays our domain instead of Retool.com.
External App
For the first external app, we'll create the landing page, where external users will be redirected after login.
If we'd like a template, we can get it by going to Settings -> External apps -> Create a landing page -> Create a new app.
Here is the template:
I personally prefer to start from scratch. If you prefer this as well, go to Apps -> /External Apps and create an app in that folder:
Here is an example:
Note: Here is the JSON for this app if you would like to build yours on top of mine:
External App example.json (72.9 KB)
Removing the Retool branding/menu located at the bottom left of the UI is now possible on a Business plan or above. To do this, go to Settings -> Branding -> User menu -> Hide menu
Back on the app, in order to make it easier for my users to logout, I added a button with an event handler that triggers this Resource query:
To make this app the home page for our external users, go back to Settings -> External apps -> Create a landing page and select the newly created app:
Permissions
The last piece of the puzzle is managing User Permissions. As of right now, if an external user went to mydomain.retool.com, they'd see the custom login page and then get redirected to the landing page. However, if after login they went to mydomain.retool.com, they would see this:
This happens due to the 'All Users' permissions group, which automatically includes all users and, by default, grants them permissions to edit all apps:
My recommendation is to remove all permissions for this group, and set granular permission for all other groups. To do this, select 'Define specific app access' and don't forget to save changes as these are not automatically saved.
Note: Make necessary permission changes to Resources and Workflows.
Then go to the 'External Users' group and provide use-only access to the apps inside the external apps folder:
This should already be the default. The half filled squared means that these apps are inheriting the use only permission because they belong to this folder (default, definitely ok to keep). If we wanted more granular permission, we could select use permission for specific apps.
Troubleshooting
1. External user is stuck on the login page.
Make sure that the custom login page isn't using an event handler to 'Go to App' after the success of a login query, especially when using "Sign in with Google." This can cause users to see the login page multiple times after logging in. The issue occurs because signing in with Google triggers a redirect to Google's sign-in page (success = redirect). At this point, the user hasn’t been authenticated yet, but they’re redirected to the new app while still going through the login process. Since they aren’t signed in, they’re then sent back to the login page, which is what they’ll see after completing the Google sign-in.
2. Can't access the login page as an editor.
Be careful with page load events that navigate users to other apps. Specially if we are referencing the current_user. For example, if we add this logic to the login page:
if (current_user){
utils.openApp("uuid-of-landing-page")
}
We may not be able to access the login page as an admin or editor because we are also logged in when editing apps.
