正文

ToolJet user authentication guide how to set up SSO JWT and role-based access for enterprise security

/0 浏览量
0904

Hey there! If you’re looking to lock down your ToolJet instance with enterprise-grade security, you’re in the right place. Setting up authentication isn’t just about slapping a login page on your app; it’s about building a trust layer that protects your data, your users, and your business logic. Whether you’re using ToolJet Enterprise or just need robust open-source authentication patterns, this guide will walk you through SSO (Single Sign-On), JWT (JSON Web Tokens), and RBAC (Role-Based Access Control) in a way that’s actually useful for real-world deployment.

Let’s cut the fluff and get straight into how this works under the hood, with practical examples you can implement today.

1. Why Authentication Matters in ToolJet

ToolJet is a low-code platform, which means it’s often used to build internal tools that connect to sensitive databases (Postgres, MySQL, Redis, etc.). If your admin panel is accessible without proper auth, someone could accidentally delete your production table or expose customer PII.

Authentication in ToolJet happens at two levels:

  1. Platform Level: Who can log into the ToolJet instance?
  2. App Level: Who can see which components, datasets, and API endpoints within a specific app?

Enterprise security demands both. Let’s start with the platform level.

2. Setting Up SSO (Single Sign-On) with OIDC/SAML

SSO is the gold standard for enterprise security. Instead of managing passwords across five different tools, your employees log in once via your identity provider (IdP)—like Okta, Azure AD, Google Workspace, or Keycloak—and ToolJet trusts that identity.

Supported SSO Protocols

ToolJet supports OIDC (OpenID Connect) and SAML 2.0. OIDC is generally easier to configure if you’re using modern cloud providers, while SAML is common in legacy enterprise environments.

Step-by-Step: Configuring OIDC SSO

Let’s assume you’re using Okta as your IdP. If you’re using Azure AD or Google, the steps are nearly identical.

Step 1: Create an OIDC App in Your IdP

In Okta:

  1. Go to Applications → Create App Integration.
  2. Choose OIDC - OpenID Connect.
  3. Set Application type to Web Application.
  4. Set Sign-in redirect URIs to: 
    
https://your-tooljet-domain.com/auth/oidc/callback
  5. Copy the Client ID and Client Secret.

Step 2: Configure ToolJet to Use SSO

ToolJet Enterprise provides a configuration file (tooljet.env or via Kubernetes secrets) where you define SSO settings.

# ToolJet Enterprise SSO Configuration
AUTH_ENABLED=true
AUTH_STRATEGY=oidc

# OIDC Provider Settings
OIDC_ISSUER=https://your-okta-domain.okta.com/oauth2/default
OIDC_CLIENT_ID=your-client-id-from-okta
OIDC_CLIENT_SECRET=your-client-secret-from-okta

# Optional: Restrict access to specific users or groups
OIDC_SCOPE=openid profile email
OIDC_ADMIN_ROLES=["admin"]  # Only users with this role in Okta can become ToolJet admins

Note: If you’re using self-hosted ToolJet (open-source), SSO is available in Enterprise Edition. The open-source version primarily supports Email/Password and basic auth. For full SSO, RBAC, and audit logs, ToolJet Enterprise is designed for this exact use case.

Step 3: Test the Login Flow

  1. Restart your ToolJet instance.
  2. Navigate to /auth/login.
  3. You should see a Sign in with SSO button.
  4. Click it, get redirected to Okta, log in, and you’re back in ToolJet.

What About SAML?

If your organization uses Azure AD or OneLogin, SAML might be required. The configuration looks like this:

AUTH_STRATEGY=saml
SAML_ISSUER=https://your-idp.com/saml/metadata
SAML_CERT=base64-encoded-x509-cert
SAML_ENTRY_POINT=https://your-idp.com/saml/sso
SAML_CALLBACK=https://your-tooljet-domain.com/auth/saml/callback

The key here is the SAML Metadata URL. Most IdPs provide this, and you can fetch it to auto-configure some settings.

3. JWT (JSON Web Tokens) for API-Level Security

SSO handles who logs in, but what about how your apps authenticate with external APIs? This is where JWT shines.

ToolJet allows you to inject JWTs into requests, making it easy to secure API calls from your low-code apps to backend services.

How JWTs Work in ToolJet

When a user logs in via SSO, ToolJet generates a session token. You can also configure JWT secrets to sign custom tokens for API authentication.

Example: Signing a JWT for an External API

Let’s say you’re building an internal dashboard that calls a microservice requiring JWT authentication. You can use ToolJet’s JWT Plugin or write a small JavaScript query.

ToolJet Query Example:

// Query: Generate JWT for external service
const jwt = require('jsonwebtoken');

const payload = {
  userId: currentUser.email,
  role: currentUser.roles.join(','),
  exp: Math.floor(Date.now() / 1000) + (60 * 60), // 1 hour expiry
};

const secret = process.env.JWT_SECRET; // Store this in ToolJet secrets
const token = jwt.sign(payload, secret);

return { token };

Now, use this token in any API call:

// Query: Fetch data from secured API
const { token } = queries.generateJwt.data;

const response = await fetch('https://api.yourbackend.com/data', {
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
});

return response.json();

Why This Matters for Enterprise

  • Stateless Auth: JWTs don’t require server-side session storage, scaling easily.
  • Embedded Claims: You can pass user roles, email, and permissions directly in the token.
  • Security: Sign tokens with a strong secret, and validate them at the API layer.

Pro Tip: Store your JWT_SECRET in ToolJet’s Secrets Manager, never in code. This keeps your keys out of version control.

4. Role-Based Access Control (RBAC)

RBAC is how you decide what users can do. In ToolJet, RBAC operates at two layers:

  1. Platform RBAC: Who can create apps, manage settings, and view audit logs.
  2. App-Level RBAC: Who can see specific components, datasets, or API calls within an app.

Platform-Level RBAC (Enterprise)

ToolJet Enterprise supports granular roles:

  • Admin: Full access to all apps, settings, and users.
  • Developer: Can create/edit apps but not manage users.
  • Viewer: Read-only access to apps.

Configuring RBAC via IdP Groups

If you’re using OIDC/SAML, you can map IdP groups to ToolJet roles.

# Map Okta groups to ToolJet roles
OIDC_ROLE_MAPPING={
  "admin-group": "admin",
  "dev-group": "developer",
  "viewer-group": "viewer"
}

When a user logs in, ToolJet checks their group membership and assigns the corresponding role.

App-Level RBAC (Component Visibility)

This is where the magic happens for low-code security. You can hide or show components based on user roles.

Example: Hiding the Delete Button Based on Role

In ToolJet’s component properties, use a dynamic visibility expression:

// Component: DeleteDatasetButton
// Visible: 
currentUser.roles.includes('admin')

Only users with the admin role will see the delete button. Everyone else sees a read-only interface.

Example: Filtering Data Based on User Role

You can also restrict data access at the query level.

// Query: getUserData
const { role } = currentUser;

if (role === 'viewer') {
  return await db.query(`SELECT * FROM public_data`);
} else if (role === 'admin') {
  return await db.query(`SELECT * FROM all_data`);
}

This ensures that even if a viewer tries to tamper with the frontend, the backend query enforces the role-based restriction.

5. Best Practices for Enterprise Authentication

1. Enforce MFA (Multi-Factor Authentication)

Always require MFA at your IdP (Okta, Azure AD, etc.). ToolJet doesn’t enforce MFA natively, so rely on your IdP’s policies.

2. Use Short-Lived Tokens

Set JWT expiry to 15–60 minutes. Rotate refresh tokens if you’re implementing custom auth.

3. Audit Logs

ToolJet Enterprise provides audit logs. Enable them to track:

  • Who logged in
  • Which apps were accessed
  • Which queries were executed

4. Secure Your Secrets

Never hardcode JWT_SECRET or database credentials. Use ToolJet’s Secrets Manager or environment variables.

5. Test with Mock Users

Before rolling out SSO, create test users with different roles (admin, developer, viewer) and verify that:

  • Admins can access all features.
  • Developers can’t delete apps.
  • Viewers can’t see sensitive data.

6. Troubleshooting Common Issues

“SSO Login Redirected to 404”

Check your Redirect URI in the IdP. It must exactly match:

https://your-tooljet-domain.com/auth/oidc/callback

No trailing slashes, no typos.

“JWT Token Expired”

If your external API is rejecting tokens, ensure the exp claim in your JWT hasn’t passed. Extend expiry if needed:

exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60), // 24 hours

“RBAC Not Working”

  • Verify that currentUser.roles is correctly populated from your IdP.
  • Check that your role mapping in tooljet.env matches your IdP group names.

Final Thoughts

Setting up SSO, JWT, and RBAC in ToolJet isn’t just a checkbox for enterprise compliance—it’s a foundational step in building secure, scalable internal tools. By leveraging OIDC/SAML for authentication, JWTs for API security, and RBAC for access control, you ensure that only the right people see the right data.

Remember: Security is a journey, not a destination. Regularly review your auth configurations, rotate secrets, and keep your ToolJet instance updated. If you’re unsure about any step, test in a staging environment first.

You’ve got this! If you run into any snags, the ToolJet community and documentation are great resources. Stay secure, and happy building!

-- 展开阅读全文 --