ToolJet user authentication guide login setup social auth security for beginners

So, you’ve decided to build something amazing with ToolJet. Maybe it’s an internal dashboard for your team, a customer support portal, or a management tool that saves everyone hours of work every day. That’s fantastic! But before you invite anyone in, there’s one critical door you need to make sure is locked tight: Authentication.

Let’s be honest—setting up login systems can feel like looking at a maze when you’re just starting out. You see terms like “OAuth,” “JWT,” “Social Auth,” and “SSO,” and your brain immediately wants to check out. But here is the good news: ToolJet has made this way more approachable than it used to be. In this guide, we’re going to walk through setting up user authentication step-by-step, from the basics to some cooler social login options, all without needing a computer science degree.

Think of this as sitting down with a friendly neighbor who knows their way around a workshop. We’ll take it slow, we’ll explain why we’re doing things, and by the end, you’ll have a secure, working login system.

Part 1: Why Bother? The “Front Door” of Your App

Before we touch any settings, let’s talk about why authentication matters. Imagine you built a beautiful house (your ToolJet app). If you leave the front door wide open, anyone can walk in. They might look around, sure, but they might also move your furniture, steal your TV, or just generally make a mess.

In the world of apps:

Authorization (who can do what) depends on Authentication (who you are).
Without login, your sensitive data—customer emails, sales figures, personal info—is exposed to the whole internet.
Even for internal tools, you want to know who is looking at what for compliance and security reasons.

ToolJet offers several ways to identify users. We’ll start with the simplest and most common method: Email/Password.

Part 2: Setting Up Email/Password Authentication (The Basics)

This is the bread and butter of web apps. You’ve probably used it a thousand times. “Enter email, enter password, click log in.” It’s reliable, straightforward, and ToolJet supports it out of the box with a few configurations.

Step 1: Enable Authentication in Your ToolJet Instance

First, you need to make sure your ToolJet instance (whether it’s the cloud version or self-hosted) has authentication turned on.

Go to your ToolJet instance’s Admin Panel.
Look for the Authentication or Settings section.
You should see options for enabling authentication methods. For now, ensure Email/Password is toggled ON.

Note for Self-Hosted Users: If you’re running your own ToolJet server, you’ll need to set up environment variables related to authentication in your .env file. Common variables include TOOLJET_AUTH_ENABLED=true. Check the specific documentation for your deployment method (Docker, Kubernetes, etc.) to ensure your backend can send emails for password resets, as this is crucial for user experience.

Step 2: Creating User Accounts

There are two main ways users get into your system:

Invitation-Only (Best for Internal Tools): You, as the admin, create accounts or send invites. This is great for company dashboards because you control who gets in.
- Go to the Admin Panel -> Users.
- Click Add User.
- Enter the user’s email and assign a role (e.g., Admin, Editor, Viewer).
- The user will receive an invitation email with a link to set their password.
Self-Registration (For Public-Facing Apps): Allow people to sign up on their own.
- In the Admin Panel, look for Sign-up settings.
- Enable Allow self-registration.
- You might want to add a verification step (email confirmation) to prevent spam accounts.

Step 3: Building the Login UI

Now, let’s make it possible for users to actually log in. ToolJet has a built-in Auth Page component, but you can also customize it.

Option A: Using the Built-in Auth Page ToolJet automatically generates a login page if you have authentication enabled. Usually, it’s accessible at /login or via a specific route you configure in your app’s settings.

In your app editor, go to App Settings -> Pages.
Ensure you have a page designated for login, or ToolJet will redirect unauthenticated users there by default.

Option B: Custom Login Form (More Control) If you want the login form to look exactly like your brand, you can build it yourself using components.

Create a new page called Login.
Add Form Components:
- A Text Input for Email (set its name to email).
- A Password Input for Password (set its name to password).
- A Button for “Log In”.
Add Actions:
- When the button is clicked, you’ll want to call the Auth API.
- In ToolJet, you can use the built-in Auth query type.
- Create a new query, select Auth as the type, and choose Login.
- Map the query parameters to your form fields:
  - email: {{ form1.values.email }}
  - password: {{ form1.values.password }}
Handle Success/Failure:
- On success, redirect the user to your home page: app.router.navigateTo('/dashboard').
- On failure, show an error message using a Toast component or update a text label.

// Example of a simple login action in ToolJet's query editor
// Query Name: loginUser

// Method: POST
// Endpoint: /api/v1/auth/login (This is handled internally by ToolJet's Auth query type)

// Form Data:
email: {{ form1.values.email }}
password: {{ form1.values.password }}

// On Success:
app.router.navigateTo('/dashboard')

// On Error:
showToast({
  message: "Invalid email or password",
  type: "error"
})

Step 4: Protecting Your Pages

Now that users can log in, you need to make sure they can’t just wander into private pages.

Go to App Settings -> Access Control (or similar, depending on your ToolJet version).
For each page that should be private (like Dashboard, User Profile), set the Access Level to Authenticated.
For public pages (like Landing Page or Pricing), you can leave them Public.

This is the magic part: When a user tries to navigate to a protected page without being logged in, ToolJet automatically redirects them to the login page. No extra code needed!

Part 3: Leveling Up with Social Authentication (OAuth)

Email/password is fine, but have you ever thought how annoying it is to remember another password? This is where Social Auth comes in. It allows users to log in using existing accounts from providers like Google, GitHub, or Microsoft.

Why Use Social Auth?

Convenience: Users love one-click logins.
Trust: People trust brands like Google.
Reduced Friction: Higher sign-up conversion rates.

How It Works (The Simple Explanation)

Think of Social Auth as a trust handshake. When a user clicks “Login with Google,” ToolJet says, “Hey Google, is this person really who they say they are?” Google checks the user’s account, and if everything looks good, it tells ToolJet, “Yes, this is Alice, and here’s her name and email.” ToolJet then logs Alice in without her ever having to create a new password.

Setting Up Google OAuth in ToolJet

Let’s walk through setting up Google Sign-In, as it’s the most common.

Step 1: Get Credentials from Google Cloud Console You can’t just ask Google for access; you need to register your app with them.

Go to the Google Cloud Console.
Create a new project (or use an existing one).
Navigate to APIs & Services -> Credentials.
Click Create Credentials -> OAuth client ID.
Choose Web application as the application type.
Important: Add your ToolJet domain to Authorized JavaScript origins and Authorized redirect URIs.
- If you’re on ToolJet Cloud, your domain might be https://app.tooljet.io.
- If self-hosted, it’s your custom domain (e.g., https://dashboards.yourcompany.com).
- The redirect URI is usually something like https://your-domain.com/auth/google/callback. Check ToolJet’s docs for the exact callback URL format.
Click Create. You’ll get a Client ID and Client Secret. Save these!

Step 2: Configure ToolJet Now, go back to your ToolJet Admin Panel.

Go to Authentication settings.
Find the Social Auth or OAuth section.
Toggle Google to ON.
Paste your Client ID and Client Secret into the respective fields.
Save changes.

Step 3: Add the Google Login Button Back in your app editor:

On your login page, drag a Button component.
Style it to look like a “Sign in with Google” button (you can use Google’s brand colors or assets).
Add an Action to the button.
Choose the Auth query type and select Login with Google (or similar, depending on the UI).
- Some versions might require you to link this to a specific OAuth endpoint. If so, the endpoint is typically /api/v1/auth/google.
Test it! Click the button, and you should be redirected to Google’s login screen.

Other Providers: GitHub and Microsoft

The process is very similar for other providers:

GitHub: Go to GitHub Developer Settings -> OAuth Apps -> Create a new app. Get your Client ID and Secret, then add them to ToolJet.
Microsoft (Azure AD): Go to the Azure Portal -> Azure Active Directory -> App registrations. Create a new app, note down the Client ID and Tenant ID. You’ll need to configure this in ToolJet’s Microsoft OAuth settings.

Pro Tip: You can enable multiple providers! A user might prefer to log in with GitHub if they’re a developer, or Google if it’s a casual user. Having both options is great UX.

Part 4: Security Best Practices – Keeping the Baddies Out

You’ve got your login set up. Great! But are you safe? Authentication is only as strong as its weakest link. Let’s talk about security without getting too technical or scary.

1. Enforce Strong Passwords

If you’re using email/password auth, don’t let users pick “password123.”

In ToolJet’s Auth settings, enable Password Strength Validation.
Set a minimum length (e.g., 8 characters).
Require a mix of uppercase, lowercase, numbers, and symbols.

2. Enable Two-Factor Authentication (2FA)

2FA adds an extra layer of security. Even if someone steals a user’s password, they can’t log in without the second factor (like a code from an app on their phone).

ToolJet supports TOTP (Time-based One-Time Password).
Go to Admin Panel -> Authentication -> Two-Factor Authentication.
Enable it. You can make it mandatory for all users or optional (let users choose to enable it).
For sensitive internal tools, I highly recommend making it mandatory.

3. Use HTTPS Everywhere

Never, ever serve your ToolJet app over HTTP. HTTPS encrypts the data between the user’s browser and your server. If you’re self-hosting, make sure you have an SSL certificate installed (Let’s Encrypt is a free and easy option).

4. Set Session Timeouts

You don’t want a user to leave their laptop open at a coffee shop and have someone else use their session for hours.

Configure your Session Lifetime in the Auth settings.
A common setting is 30 minutes to 1 hour of inactivity.
ToolJet will automatically log users out after this period.

5. Audit Logs

Keep track of who is logging in and when. This is crucial for investigating suspicious activity.

Check if your ToolJet instance has Audit Logging enabled.
Review logs periodically for unusual login attempts (e.g., multiple failed logins from different countries).

Part 5: Managing Users and Roles – Who Gets What?

Authentication is about who is logging in. Authorization is about what they can do. Let’s connect the two.

Understanding Roles

ToolJet typically uses a role-based access control (RBAC) system. Common roles include:

Admin: Can manage users, settings, and all apps.
Editor: Can create and edit apps and dashboards.
Viewer: Can view apps and dashboards but cannot edit them.

Assigning Roles

When you create a user (manually or via invite), assign them a role.

Admins should be limited to a small group of trusted IT staff.
Editors are usually team leads or power users.
Viewers are the general audience.

Restricting Access to Specific Apps or Pages

You don’t have to give everyone access to everything.

Go to App Settings -> Team or Access Control.
You can restrict access to the entire app by role (e.g., only Admins and Editors can access this app).
For more granular control, you can use Row-Level Security or Page-Level Security within your queries.

Example: Securing a Sensitive Dashboard

Let’s say you have a “Financial Reports” dashboard that only Finance Managers should see.

Create a role called “Finance Manager.”
Assign the relevant users to this role.
On the “Financial Reports” app/page, set the access control to only allow “Finance Manager” and “Admin” roles.
Now, even if a regular “Viewer” knows the URL, they’ll be blocked from accessing it.

Part 6: Advanced – Custom Authentication with LDAP/SSO

For larger organizations, managing individual user accounts in ToolJet can become a headache. This is where LDAP (Lightweight Directory Access Protocol) or SSO (Single Sign-On) comes in.

What is SSO?

SSO allows users to log in once with their corporate credentials (like their work email and password) and then access multiple applications (like ToolJet, Salesforce, Slack) without logging in again.

Setting Up SSO in ToolJet

ToolJet supports SAML 2.0 for SSO. This is a bit more complex than Google OAuth, but it’s powerful.

Choose an Identity Provider (IdP): Common choices are Okta, Azure AD, OneLogin, or Auth0.
Configure ToolJet as a Service Provider (SP):
- In your IdP, create a new SAML application.
- Set the ACS (Assertion Consumer Service) URL to your ToolJet instance’s SSO endpoint (usually https://your-domain.com/auth/saml/callback).
- Set the Entity ID as your ToolJet domain.
Configure ToolJet:
- In the Admin Panel, go to Authentication -> SSO/SAML.
- Upload the metadata XML from your IdP, or manually enter the IdP’s metadata URL.
- Map the user attributes (email, name) from the SAML response to ToolJet’s user fields.
Test Thoroughly: SSO configurations can be tricky. Test with a small group first.

When to Use LDAP vs. SSO?

LDAP: Better for older, on-premise systems where user accounts are stored in an Active Directory.
SSO (SAML/OIDC): Better for modern, cloud-based environments and user-friendly experiences.

Part 7: Troubleshooting Common Authentication Issues

Even with the best setup, things can go wrong. Here are some common problems and how to fix them.

Problem 1: “Invalid Login Credentials” When I Know I’m Right

Check Caps Lock: It’s a silly one, but it happens.
Password Reset: The user might have forgotten their password. Send a reset link.
Case Sensitivity: Ensure the email is entered correctly (though usually, emails are case-insensitive).
Account Locked: Too many failed attempts might have locked the account. Check admin logs.

Problem 2: “Redirect Loop” After Login

HTTPS Mismatch: If your app is on HTTPS but the redirect URI is HTTP (or vice versa), you’ll get stuck in a loop. Ensure consistency.
Cookie Settings: Check if cookies are enabled in the user’s browser. Sometimes, third-party cookie blocking (especially in Safari or with privacy extensions) can interfere with OAuth flows.
CORS Issues: If you’re self-hosted, ensure your CORS settings allow requests from your domain.

Problem 3: Google OAuth “Invalid Redirect URI”

Double-Check the URI: Go back to your Google Cloud Console and verify the redirect URI matches exactly what ToolJet is sending. Including trailing slashes can matter.
Environment: Make sure you’re using the correct Client ID for the correct environment (e.g., don’t use a production Client ID for a staging instance).