# How to Implement Authentication in a Retool Application

- Tool: Retool
- Difficulty: Beginner
- Time required: 20-30 min
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

Retool handles app authentication at the organization level — configure SSO via Settings → Authentication. Once a user logs in, access their identity anywhere in the app using {{ current_user.email }}, {{ current_user.fullName }}, and {{ current_user.groups }}. Use group membership to show/hide components or restrict query execution. Custom login pages are available for embedded apps on Business plans.

## Authentication in Retool: Platform-Level, Not App-Level

Unlike traditional web apps where you build a login page and manage sessions, Retool handles authentication at the platform level. Users authenticate once to your Retool organization — then all apps they have permission to access are available without additional login steps.

Retool supports multiple authentication methods: email/password (basic), Google SSO (easy setup), SAML 2.0 (enterprise SSO with Okta, Azure AD, etc.), and OIDC (custom identity providers). On Business plans, you can also use Google Workspace for domain-based access control.

Once authenticated, the current_user object is available in every app — it contains the user's email, name, group memberships, and custom metadata from your SSO provider.

## Before you start

- Admin access to Retool Settings
- For SSO setup: access to your identity provider (Google Admin Console, Okta, Azure AD, or your OIDC provider)
- Understanding of Retool groups and permissions (recommended)

## Step-by-step guide

### 1. Configure Google SSO for your Retool organization

Navigate to Settings → Authentication in your Retool org. Click 'Add authentication' or find the Google SSO section. For Google Workspace, enable 'Restrict to specific domains' and enter your company's Google Workspace domain (e.g., yourcompany.com). This allows any user with a @yourcompany.com Google account to log in. Users see a 'Sign in with Google' button on the Retool login page. After Google SSO is enabled, new users signing in with Google are automatically created as Retool users in the 'All Users' default group.

**Expected result:** Users can log in to Retool using their Google account. Domain restriction prevents unauthorized sign-ups.

### 2. Configure SAML 2.0 SSO for enterprise identity providers

For Okta, Azure AD, or other enterprise IdPs, use SAML 2.0. In Settings → Authentication, select 'SAML 2.0'. Retool provides its Service Provider metadata (ACS URL, Entity ID) for you to enter in your IdP. Copy the IdP metadata XML or URL from your identity provider and paste it into Retool's 'IdP metadata URL' or 'IdP metadata XML' field. Configure attribute mappings: email (required), firstName, lastName, and any custom attributes you want available in current_user.metadata. Test the flow before locking out password-based login.

**Expected result:** Users can authenticate via your enterprise IdP. Retool groups are auto-assigned based on IdP group claims.

### 3. Use the current_user object in your app

After authentication is configured, access user identity anywhere in your app using the current_user object. The key properties are: current_user.email (user's email address), current_user.fullName (display name), current_user.id (Retool internal user ID), current_user.groups (array of group names the user belongs to), current_user.metadata (custom attributes from SSO provider). Use these in queries (personalized SQL filters), component visibility conditions, and text components.

```
// Personalized SQL query using current user
SELECT *
FROM work_orders
WHERE assigned_to = {{ current_user.email }}
ORDER BY due_date ASC;

// Welcome message in a Text component
Welcome back, {{ current_user.fullName.split(' ')[0] }}!

// Show admin panel only to admins:
// Component Hidden property:
{{ !current_user.groups.includes('Admins') }}

// Show username in page title:
Support Queue — {{ current_user.fullName }}
```

**Expected result:** App personalizes content based on the logged-in user's identity and group membership.

### 4. Restrict query execution based on user groups

For sensitive operations, add a guard condition in JS Queries that checks group membership before running a write operation. This provides defense-in-depth beyond just hiding UI elements — even if someone finds a way to trigger the query, the JS check will block unauthorized execution.

```
// JS Query: deleteRecord
// Guarded to allow only Admin group members

if (!current_user.groups.includes('Admins')) {
  utils.showNotification({
    title: 'Access denied',
    description: 'Only administrators can delete records.',
    notificationType: 'error',
  });
  return;
}

if (!confirm(`Delete record ID ${table1.selectedRow.data.id}? This cannot be undone.`)) {
  return;
}

await deleteFromDb.trigger();
await refreshList.trigger();

utils.showNotification({
  title: 'Record deleted',
  notificationType: 'success',
});
```

**Expected result:** Delete operation is blocked for non-admin users even if they somehow trigger the query.

### 5. Set up a custom login page for embedded apps

When embedding Retool apps in external websites using Retool's Embed feature (Business plan), you may want a branded login experience instead of Retool's default login page. Navigate to Settings → Embedding → Custom login. Configure a custom login URL that your users are redirected to. After successful authentication on your platform, generate a Retool embed URL with a JWT embed token containing the user's identity. Retool validates the JWT and creates a Retool user session automatically — users never see Retool's login page.

**Expected result:** Embedded Retool apps use your custom login flow. Users see your branded login, not Retool's.

## Complete code example

File: `SQL Query: getPersonalizedData`

```sql
-- Personalized query using current_user for multi-tenant data isolation
-- Only returns records belonging to the current user's team

SELECT
  r.id,
  r.title,
  r.status,
  r.priority,
  r.due_date,
  r.created_at,
  u.full_name AS assignee_name
FROM requests r
JOIN users u ON r.assignee_id = u.id
WHERE
  -- Filter by team based on current user's group membership
  r.team_id = (
    SELECT team_id FROM users WHERE email = {{ current_user.email }}
  )
  -- Admins can see all records, regular users see only their own
  AND (
    {{ current_user.groups.includes('Admins') }}
    OR r.assignee_email = {{ current_user.email }}
  )
ORDER BY r.priority DESC, r.due_date ASC
LIMIT 200;
```

## Common mistakes

- **Hiding UI elements with current_user.groups as the only access control for sensitive operations** — undefined Fix: CSS visibility and Hidden properties can be bypassed. Add server-side checks in SQL WHERE clauses (AND user_email = {{ current_user.email }}) and JavaScript guards (if (!current_user.groups.includes('Admins')) return;) for any write operation.
- **Enabling SSO without first testing it with a non-admin account, then getting locked out** — undefined Fix: Before enforcing SSO, test the full login flow with a test account. Keep password-based login as a fallback for at least one admin account until SSO is confirmed working.
- **Using current_user.email in SQL queries without parameterization, creating SQL injection risk** — undefined Fix: Retool automatically parameterizes {{ }} expressions in SQL queries using prepared statements. This is safe. Avoid string concatenation like 'WHERE email = \'' + current_user.email + '\'' — always use the {{ }} syntax.

## Best practices

- Use Retool's built-in SSO integration rather than building custom authentication — it's more secure and easier to maintain
- Always configure both UI-level hiding (Hidden property) AND query-level guards for sensitive operations
- Map your IdP groups to Retool groups during SAML/OIDC setup to automate permission management
- Test authentication setup with a non-admin test account before going live to verify that regular users see the correct experience
- For embedded apps, always generate embed JWTs server-side — the embed secret must never reach the browser
- Log authentication events: Retool's audit log records login events, SSO changes, and permission modifications

## Frequently asked questions

### Can Retool apps be accessed without logging in (public access)?

Yes — in app Settings, enable 'Public access' to make an app accessible without a Retool account. Public apps cannot use {{ current_user }} since there is no authenticated user. Public access is suitable for external-facing dashboards but not for internal tools handling sensitive data.

### What is current_user.metadata and how do I populate it?

current_user.metadata contains custom attributes forwarded from your SSO provider. Configure attribute mapping in your SAML or OIDC settings: map IdP attributes (like department, employeeId, costCenter) to Retool metadata fields. Access them as {{ current_user.metadata.department }}. Email/password accounts don't have SSO metadata.

### How does Retool handle authentication for self-hosted deployments?

Self-hosted Retool supports all the same authentication methods (email/password, Google SSO, SAML, OIDC) configured in the same Settings UI. The only difference is that the SSO callback URLs point to your self-hosted domain instead of Retool Cloud. Some authentication features (like Retool's managed identity verification) require network access to Retool's auth services.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-implement-authentication-in-a-retool-application
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-implement-authentication-in-a-retool-application