正文

ToolJet User Authentication Guide for Developers How to Secure Your ToolJet Apps with Built-in Auth Options ToolJet Authentication Setup Tutorial for Internal Tools Configuring User

/0 浏览量
0925

Let’s be honest for a second: building a dashboard or an internal tool is the easy part. The hard part? Making sure that the only people seeing your data are actually the people you want to see it. I’ve seen too many “internal tools” end up as accidental public websites because the auth layer was an afterthought—or worse, hardcoded with an API key that leaked on GitHub.

If you’re using ToolJet, you’ve made a solid choice for rapid development, but you need to treat authentication with the same gravity as your frontend logic. ToolJet doesn’t just offer a single switch for “on/off security.” It gives you a spectrum of options, from simple email/password to enterprise-grade SSO and MFA. Today, I’m going to walk you through exactly how to wire this up, not just as a list of settings, but as a coherent strategy for securing your apps.

The Foundation: Internal Database Authentication

For most internal tools—say, a CRM for your sales team or an inventory tracker for your warehouse—the simplest and most secure starting point is ToolJet’s built-in Internal Database. This isn’t just “basic” auth; it’s a robust, managed identity layer where ToolJet handles the hashing, storage, and session management for you.

Why Start Here?

You don’t need to manage a separate user table. You don’t need to worry about bcrypt implementation errors. You just create users, and they’re ready to go.

How to Set It Up

  1. Navigate to the Builder: Open your specific app in the ToolJet Editor.
  2. Access Settings: Click on the Settings icon (usually a gear) in the top right corner.
  3. Go to “Users & Permissions”: Here, you’ll see the authentication methods available.
  4. Select “Internal Database”: Toggle it on. You can configure whether new users can self-register (useful for low-security internal tools) or if only admins can invite users (critical for sensitive data).

The Developer’s Workflow: Managing Users Programmatically

While the UI is great for manual setup, you’ll often need to manage users via code, especially if you’re seeding your database or integrating with HR systems. ToolJet exposes endpoints for this.

Here’s how you might handle user invitation via a simple script (assuming you have CLI access or a backend service):

# Example: Inviting a user via ToolJet's CLI or API
# This creates a user in the internal database and sends an invite email

tooljet user invite \
  --email "sarah.jones@yourcompany.com" \
  --role "user" \
  --app-id "your-app-id"

Once invited, Sarah receives an email with a link to set her password. She’s now authenticated against your internal user store. No complex OAuth flows, no SAML certificates—just clean, simple access.

Taking It Further: SSO with SAML and OIDC

Now, imagine your company is 500+ people strong. You don’t want Sarah logging into ToolJet with a separate password. She already logs into your internal portal with Okta, Azure AD, or Google Workspace. This is where Single Sign-On (SSO) becomes non-negotiable.

ToolJet supports two major protocols: SAML 2.0 and OIDC (OpenID Connect). Choosing between them depends on your identity provider (IdP).

SAML vs. OIDC: What’s the Difference?

  • SAML: Older, enterprise-heavy. The gold standard for large corporations using Okta, Azure AD, or OneLogin. It’s XML-based and robust.
  • OIDC: Newer, more developer-friendly. Built on top of OAuth 2.0. Ideal if you’re using Google Workspace, Auth0, or newer cloud-native identity systems.

Configuring SAML SSO

Let’s say you’re using Azure AD. Here’s what that process looks like in ToolJet:

  1. Get Your IdP Metadata: In Azure AD, go to Enterprise Applications > Your App > SAML Certificates. Download the App Federation Metadata XML. This contains all the URLs and certificates ToolJet needs.
  2. ToolJet Side Configuration:
    • Go to Settings > Users & Permissions > SSO.
    • Choose SAML.
    • Upload the XML file or manually paste the Entity ID, ACS URL, and X.509 Certificate.
    • Crucial Step: Map your User Attributes. Ensure that email or userprincipalname from Azure AD maps to the email field in ToolJet. If this mapping is wrong, users will log in but won’t see their data or permissions.

Configuring OIDC (e.g., with Auth0 or Google)

OIDC is simpler because it’s JSON-based.

  1. In Your IdP: Create a new application. Set the Redirect URI to https://your-tooljet-domain.com/auth/oidc/callback.
  2. In ToolJet:
    • Go to Settings > Users & Permissions > SSO.
    • Choose OIDC.
    • Enter the Client ID, Client Secret, Issuer URL, and Authorization Endpoint.
    • ToolJet will handle the token exchange.

Code Example: Handling the Callback Securely

While ToolJet handles the heavy lifting, if you’re building custom widgets or API calls that need to verify the user’s identity post-login, you might interact with the session token.

// In a ToolJet Query (Database or API), you can access the current user's context
// This ensures you only fetch data relevant to the logged-in user

const userId = tooljet.getCurrentUser().id;
const userEmail = tooljet.getCurrentUser().email;

// Example: Fetching only the user's own tasks from a connected database
const tasks = await db.query(`
  SELECT * FROM tasks 
  WHERE assigned_to = :userEmail 
  ORDER BY created_at DESC
`, { userEmail });

return tasks;

This pattern is vital. Even with SSO, you must ensure your queries are row-level secure. SSO authenticates the user; it doesn’t automatically authorize them to see all data in your database.

The Extra Layer: Multi-Factor Authentication (MFA)

SSO solves the password fatigue problem, but it doesn’t solve the “compromised credentials” problem. If an attacker phishes Sarah’s password and she’s already logged into Azure AD, they have access to ToolJet too. This is why MFA is your safety net.

ToolJet’s built-in auth supports TOTP (Time-based One-Time Password) for the Internal Database. For SSO, MFA is typically enforced at the IdP level (e.g., Azure AD Conditional Access policies or Okta Verify).

Enforcing MFA for Internal Database Users

  1. Go to Settings > Users & Permissions > Internal Database.
  2. Toggle on Require MFA.
  3. When users log in, they’ll be prompted to scan a QR code with Google Authenticator, Authy, or Microsoft Authenticator.

Why This Matters for Developers

When designing your app’s UI, you need to account for the MFA challenge. ToolJet handles the redirect, but if you’re using custom login pages or embedding ToolJet in an iframe, ensure your layout can accommodate the extra step.

Pro Tip: If you’re using OIDC, check if your IdP supports Adaptive Authentication. You can configure it to only require MFA when a user logs in from a new device or location. This balances security and user experience perfectly.

Security Best Practices: Beyond the Settings

Here’s where I see most developers stumble. They configure SSO and call it a day. But security is a habit, not a setting.

1. Principle of Least Privilege

Just because someone can log in doesn’t mean they should see everything. Use ToolJet’s Permissions system aggressively.

  • Admin: Can edit the app, manage users, and see all data.
  • User: Can view and interact with data but cannot change app configurations.
  • Custom Roles: Define granular permissions. For example, a “Sales Manager” might see all sales data, but a “Sales Rep” only sees their own.
// Always filter data by user context in your queries
const userRole = tooljet.getCurrentUser().role;

if (userRole === 'admin') {
  return await db.query(`SELECT * FROM all_customers`);
} else {
  return await db.query(`SELECT * FROM customers WHERE manager_id = :managerId`, {
    managerId: tooljet.getCurrentUser().manager_id
  });
}

2. Session Management

ToolJet has default session timeouts, but if you’re handling sensitive data (PII, financial records), tighten these up.

  • Set a shorter Session Timeout in Settings.
  • Enable Secure Cookies (HTTP-only and Secure flags) to prevent XSS attacks from stealing session tokens.

3. Audit Logging

You need to know who did what and when. ToolJet provides audit logs for user actions.

  • Enable Audit Logs in Settings.
  • Regularly review logs for suspicious activity, like multiple failed login attempts or access from unusual IP addresses.

4. Protect Your API Keys

If your ToolJet app connects to external services (Stripe, Twilio, Salesforce), never hardcode API keys in your queries. Use ToolJet’s Secrets feature.

  • Go to Settings > Secrets.
  • Store your keys there.
  • Reference them in queries using {{ secret.key_name }}.

This prevents keys from leaking into version control or appearing in error logs.

Common Pitfalls and How to Avoid Them

Pitfall 1: The “Email Mismatch” Problem When setting up SSO, ensure the email in your IdP matches the email in your ToolJet user base. If Azure AD sends sarah.j@company.com but ToolJet has sarah.jones@company.com, the login will fail or create duplicate accounts. Solution: Use consistent email domains and enforce unique emails in User Settings.

Pitfall 2: Over-Reliance on SSO Without Row-Level Security You’ve set up SSO, so you think you’re safe. But if your queries don’t filter by user, every employee can see every record. Solution: Treat SSO as an authentication layer, not an authorization layer. Always add user-specific filters to your database queries.

Pitfall 3: Ignoring Mobile Experience MFA on mobile can be clunky if not tested. Ensure your QR codes are scannable and your app layout works on smaller screens. Solution: Test the full login flow on a mobile device before rolling out to your team.

Conclusion: Security as a Feature

Securing your ToolJet apps isn’t about ticking boxes; it’s about building trust. When your internal tools are secure, your team works faster without fear of data leaks. When you implement SSO, you respect your users’ time. When you enforce MFA, you protect the company.

Start with the Internal Database for simple tools. Graduate to SSO as you scale. Layer on MFA for sensitive data. And always, always write your queries with the current user in mind.

ToolJet gives you the tools. It’s up to you to use them wisely. If you have questions about a specific IdP integration or need help debugging a permission issue, the ToolJet community is active and helpful. But remember: the best security is the security you’ve thought through, tested, and implemented before your app goes live.

-- 展开阅读全文 --