ToolJet user authentication setup guide for beginners and developers

Let me walk you through setting up authentication in ToolJet from scratch. ToolJet is an open-source low-code framework that lets you build internal tools quickly, and authentication is usually the first thing you want to get right so your app stays secure.

We’ll cover the built-in authentication system (email/password, SSO, social login) as well as custom authentication if you need something more specific.

1. Understanding ToolJet’s Authentication Options

ToolJet supports several ways to authenticate users:

Built-in auth – email/password with login, signup, password reset
Single Sign-On (SSO) – SAML, OAuth2, OIDC
Social logins – Google, GitHub, etc.
LDAP/Active Directory – for enterprise environments
Custom auth – bring your own auth backend

For a quick start, the built-in system is the easiest and most common path.

2. Setting Up Built-In Authentication (Step-by-Step)

Step 1: Enable Authentication in ToolJet

If you’re running ToolJet on-premises (not ToolJet Cloud), you need to configure authentication in your environment variables.

Open your .env file or your docker-compose configuration and set these:

TOOLJET_AUTH_ENABLED=true
TOOLJET_AUTH_SESSION_SECRET=your-random-secret-here

You can generate a strong secret with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Step 2: Create Your First User

ToolJet provides a CLI to create users. Run this from the ToolJet server directory:

npx tooljet create-user --email admin@example.com --password YourStrongPassword123

This creates the first admin user. The first user automatically becomes an admin.

Step 3: Test the Login Flow

Start your ToolJet app and navigate to:

http://localhost:3000/login

You should see a login screen. Enter the credentials you just created.

3. Configuring OAuth/Social Login

ToolJet supports several social login providers. Here’s how to set up Google login as an example.

Google OAuth Setup

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google Identity APIs
Go to Credentials → Create Credentials → OAuth client ID

Set the authorized redirect URI to:


http://your-tooljet-domain/auth/oauth/google/callback

Note your Client ID and Client Secret

Then configure ToolJet:

TOOLJET_AUTH_GOOGLE_CLIENT_ID=your-google-client-id
TOOLJET_AUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

Restart ToolJet and you should see the Google login button on the login page.

4. Setting Up SAML/SSO for Enterprise

SAML is common in enterprise environments. Here’s a minimal example using Okta as the identity provider.

Okta SAML Configuration

In Okta:

Create a new SAML 2.0 app integration

Set the Single sign-on URL to:


http://your-tooljet-domain/auth/saml/acs

Set the Audience URI (Entity ID) to:


http://your-tooljet-domain/auth/saml/metadata

Download the Federation Metadata XML

In ToolJet, you’ll configure the SAML settings in your .env:

TOOLJET_AUTH_SAML_ENABLED=true
TOOLJET_AUTH_SAML_ISSUER=your-tooljet-domain
TOOLJET_AUTH_SAML_CALLBACK_URL=http://your-tooljet-domain/auth/saml/acS
TOOLJET_AUTH_SAML_CERT=<paste-the-xml-content>

Note: ToolJet’s exact SAML configuration may vary depending on your version. Check the ToolJet documentation for the latest schema.

5. Building Custom Authentication

Sometimes you need to use your own auth system. ToolJet lets you do this with custom middleware.

Example: Custom JWT Authentication

Let’s say you have an existing API that issues JWT tokens. You can set up ToolJet to trust those tokens.

Step 1: Create a custom auth middleware

In ToolJet, you can add custom middleware by creating a file like server/middleware/custom-auth.js:

const jwt = require('jsonwebtoken');

module.exports = async (req, res, next) => {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'No token provided' });
  }

  const token = authHeader.split(' ')[1];

  try {
    const decoded = jwt.verify(token, 'your-jwt-secret-key');
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(403).json({ error: 'Invalid token' });
  }
};

Step 2: Register the middleware in ToolJet

In your ToolJet app, go to Settings → Authentication and select Custom. Then point it to your middleware.

Step 3: Use the authenticated user

Once authenticated, you can access the user info in your ToolJet queries:

// In a ToolJet query
const user = queryOptions.user;
return {
  userId: user.id,
  email: user.email
};

6. Managing Users and Permissions

Creating Users Programmatically

You can create users via the ToolJet API:

curl -X POST http://localhost:3000/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "email": "newuser@example.com",
    "password": "SecurePassword123",
    "role": "user"
  }'

Assigning Roles

ToolJet has basic roles: admin, user, and viewer.

Admin – full access, can manage apps and users
User – can use apps but can’t manage the instance
Viewer – read-only access

Set the role when creating a user or update it later:

curl -X PUT http://localhost:3000/api/v1/users/user-id \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{"role": "admin"}'

7. Securing Your ToolJet Instance

Authentication is only part of the story. Here are essential security tips:

Use HTTPS in Production

Never run ToolJet over plain HTTP in production. Use a reverse proxy like Nginx with SSL:

server {
    listen 443 ssl;
    server_name tooljet.yourcompany.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Restrict Access by IP (Optional)

If only your team should access ToolJet, add IP restrictions:

allow 192.168.1.0/24;
allow 10.0.0.0/8;
deny all;

Keep ToolJet Updated

Security patches are regularly released. Always run the latest version:

git pull
docker-compose up -d

8. Troubleshooting Common Issues

“Invalid credentials” on login

This usually means the user doesn’t exist or the password is wrong. Double-check:

The email is registered
You’re using the correct password
Caps lock isn’t on

OAuth callback fails

Common causes:

Redirect URI doesn’t match exactly (including http vs https)
Client ID/secret are incorrect
The OAuth provider hasn’t approved your app (for some providers)

SAML assertion errors

Check:

The SAML XML is properly formatted
The Issuer matches what you configured
The certificate hasn’t expired

9. Advanced: Multi-Tenant Authentication

If you’re building ToolJet for multiple organizations, you’ll want to isolate users by tenant.

Approach: Add a tenant_id to users

Extend your user model (or use ToolJet’s custom auth) to include a tenant identifier:

// Custom auth middleware
const user = await db.users.findByToken(token);
if (user.tenant_id !== req.tenant_id) {
  return res.status(403).json({ error: 'Access denied' });
}

Approach: Domain-based routing

Route users based on their email domain:

john@acme.com → acme.tooljet.yourcompany.com
jane@widget.io → widget.tooljet.yourcompany.com

10. Quick Reference Cheat Sheet

Task	Command/Config
Enable auth	`TOOLJET_AUTH_ENABLED=true`
Create admin user	`npx tooljet create-user --email admin@example.com --password SecurePass123`
Set session secret	`TOOLJET_AUTH_SESSION_SECRET=<your-secret>`
Enable Google OAuth	`TOOLJET_AUTH_GOOGLE_CLIENT_ID=...` + `TOOLJET_AUTH_GOOGLE_CLIENT_SECRET=...`
Enable SAML	`TOOLJET_AUTH_SAML_ENABLED=true` + SAML config vars
API to create user	`POST /api/v1/users`
Update user role	`PUT /api/v1/users/:id`

Wrapping Up

Authentication in ToolJet is flexible enough to handle everything from a simple internal tool to a complex enterprise deployment. The built-in system gets you started in minutes, and the custom auth hooks give you full control when you need it.

The biggest takeaway: get HTTPS set up early, use strong passwords, and test your auth flow before deploying to production. Nothing kills productivity faster than a broken login page on a Monday morning.

If you run into any specific issues, the ToolJet community on GitHub and their documentation are excellent resources. Happy building!

正文