Hey there! If you’ve landed on this page, you’re likely the kind of person who prefers keeping their data on-premise. You’re building a workflow automation app using ToolJet, but you’ve hit that critical wall: “Who gets in, and how do I trust them?”
Setting up authentication in a self-hosted environment is significantly more flexible than using the cloud version, but it can also feel like walking through a minefield of SAML metadata, client secrets, and environment variables. Don’t worry. I’ve been there, and I’m going to walk you through it step-by-step, just like we’re sitting at the same desk.
By the end of this guide, you’ll have a fully secured ToolJet instance with Single Sign-On (SSO) via SAML/OIDC and Social Logins (like GitHub, Google, or LinkedIn) ready to roll. Let’s dive in.
Why Bother with Self-Hosted Auth?
Before we touch a single line of config, let’s remember why we’re doing this. When you self-host ToolJet, you own the data. But “owning” the data means you’re also responsible for the gatekeepers.
- Security Compliance: If you’re handling internal HR, finance, or engineering data, you likely need audit trails and strict access controls.
- Unified Identity: Your employees already have a login for Okta, Azure AD, or Google Workspace. Why make them remember another password?
- Cost Control: Cloud SSO providers can get expensive as you scale. Self-hosted ToolJet lets you connect to your existing identity provider without per-seat fees.
Think of it this way: Auth is the bouncer at the club. You want a bouncer who knows your VIP list (SSO) and also lets in the cool kids who have their own social clout (Social Login).
Prerequisites: Getting Your House in Order
Before we configure anything in ToolJet, you need to prepare your Identity Provider (IdP). This is the system that will verify who the user is.
1. Choose Your Identity Provider
For SSO, you’ll need one of the following:
- Okta: Very common in enterprises.
- Azure AD (Microsoft Entra ID): Standard for Microsoft-centric shops.
- Google Workspace: Great for modern, cloud-first teams.
- Keycloak: If you want to self-host your own IdP (open-source and free).
- Auth0: A popular cloud-based IdP with generous free tiers.
For Social Login, you’ll need developer accounts on:
- GitHub
- Twitter/X (though deprecated for OAuth 2.0, use caution)
2. Gather Your Credentials
For each IdP, you’ll need to create an application (often called a “Client” or “Integration”). From there, collect:
- Client ID (or Application ID)
- Client Secret (Keep this very secret!)
- Issuer URL (The base URL of your IdP)
- Discovery Document URL (Often
/.well-known/openid-configuration) - Callback/Redirect URL (This is your ToolJet URL +
/auth/sso/callback)
Pro Tip: Always set the Redirect URL to
https://your-tooljet-domain/auth/sso/callback. Never uselocalhostin production.
Part 1: Setting Up Single Sign-On (SSO)
SSO is the gold standard for enterprise apps. It allows users to log in using their existing corporate credentials. ToolJet supports SAML 2.0 and OpenID Connect (OIDC). OIDC is generally easier to set up and more modern, so we’ll focus on that, but the principles are similar for SAML.
Step 1: Configure Your Identity Provider
Let’s assume you’re using Azure AD as an example. The steps are similar for Okta and Google:
- Log into your Azure AD Admin Portal.
- Go to Enterprise Applications > New Application.
- Search for “ToolJet” (if available) or create a “Non-gallery” application.
- Set the Single Sign-On mode to OIDC.
- Note down the Issuer URL and Login URL.
- Set the Reply URL (Redirect URI) to
https://your-tooljet-domain/auth/sso/callback. - Create a Client Secret and save it securely.
Step 2: Configure ToolJet Environment Variables
ToolJet’s authentication settings are controlled via environment variables in your .env file (or Docker Compose). This is where the magic happens.
Open your .env file and add the following:
# SSO Configuration
AUTH_SSO_ENABLED=true
AUTH_SSO_PROVIDER=oidc
AUTH_SSO_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0
AUTH_SSO_CLIENT_ID=your-azure-client-id
AUTH_SSO_CLIENT_SECRET=your-azure-client-secret
AUTH_SSO_SCOPE=openid profile email
AUTH_SSO_REDIRECT_URL=https://your-tooljet-domain/auth/sso/callback
Important: If you’re using SAML instead of OIDC, you’ll use different variables like
AUTH_SSO_PROVIDER=samland provideAUTH_SSO_METADATA_URLinstead ofISSUER.
Step 3: Restart Your ToolJet Instance
After saving the .env file, restart your ToolJet containers:
docker-compose down
docker-compose up -d
Step 4: Test the SSO Flow
- Navigate to your ToolJet instance.
- You should now see a “Sign in with SSO” button on the login page.
- Click it. You’ll be redirected to your IdP (e.g., Azure AD login page).
- Enter your corporate credentials.
- You’ll be redirected back to ToolJet, logged in as yourself!
Troubleshooting Tip: If you get a “redirect_uri_mismatch” error, double-check that the Redirect URL in your IdP matches exactly what’s in your
.envfile. Include or exclude the trailing slash consistently.
Part 2: Setting Up Social Login
Social login is perfect for startups, open-source projects, or any scenario where you want users to authenticate with their existing social accounts. It’s faster for users (no new password to remember) and easier to set up than SSO.
Step 1: Create OAuth Applications on Social Platforms
GitHub
- Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App.
- Set the Homepage URL to
https://your-tooljet-domain. - Set the Authorization callback URL to
https://your-tooljet-domain/auth/social/callback/github. - Copy the Client ID and Client Secret.
- Go to Google Cloud Console > APIs & Services > Credentials.
- Create an OAuth 2.0 Client ID.
- Set the Authorized redirect URIs to
https://your-tooljet-domain/auth/social/callback/google. - Copy the Client ID and Client Secret.
- Go to LinkedIn Developers > Apps > Create App.
- Set the Authorized redirect URLs to
https://your-tooljet-domain/auth/social/callback/linkedin. - Copy the Client ID and Client Secret.
Step 2: Configure ToolJet Environment Variables
Add the following to your .env file:
# GitHub OAuth
AUTH_SOCIAL_ENABLED=true
AUTH_SOCIAL_GITHUB_ENABLED=true
AUTH_SOCIAL_GITHUB_CLIENT_ID=your-github-client-id
AUTH_SOCIAL_GITHUB_CLIENT_SECRET=your-github-client-secret
# Google OAuth
AUTH_SOCIAL_GOOGLE_ENABLED=true
AUTH_SOCIAL_GOOGLE_CLIENT_ID=your-google-client-id
AUTH_SOCIAL_GOOGLE_CLIENT_SECRET=your-google-client-secret
# LinkedIn OAuth
AUTH_SOCIAL_LINKEDIN_ENABLED=true
AUTH_SOCIAL_LINKEDIN_CLIENT_ID=your-linkedin-client-id
AUTH_SOCIAL_LINKEDIN_CLIENT_SECRET=your-linkedin-client-secret
Note: You can enable as many social providers as you want by adding their respective variables.
Step 3: Restart and Test
Restart your ToolJet instance:
docker-compose down
docker-compose up -d
Now, when users visit your ToolJet login page, they’ll see buttons for GitHub, Google, and LinkedIn. Clicking any of these will initiate the OAuth flow, and upon successful authentication, the user will be logged in and associated with their ToolJet account.
Part 3: Advanced Configuration – Role-Based Access Control (RBAC)
Now that users can log in, you need to decide what they can do. ToolJet supports basic role-based access control, but for more granular control, you can leverage claims from your SSO provider.
Mapping SSO Claims to Roles
If you’re using OIDC (e.g., Azure AD or Okta), you can map specific claims to ToolJet roles.
For example, in Azure AD, you can add a custom claim that sends a role attribute (e.g., admin, viewer). In ToolJet, you can then configure your environment to use this claim for role assignment.
Add this to your .env:
# Map the 'role' claim from SSO to ToolJet roles
AUTH_SSO_ROLE_CLAIM=role
This means: “Whoever logs in with the ‘admin’ role in Azure AD should be an admin in ToolJet.”
User Groups and Permissions
ToolJet allows you to create Teams and assign Permissions to them. Here’s how to do it:
- Log in as an admin.
- Go to Settings > Teams.
- Create a new team (e.g., “Engineering”).
- Add users to the team (they’ll appear automatically if they’ve logged in via SSO).
- Assign permissions to the team (e.g., “Can create workflows,” “Can view dashboards”).
Best Practice: Avoid giving “Admin” rights to everyone. Only grant admin access to your core team members.
Part 4: Securing Your Setup – Best Practices
Setting up auth is step one. Keeping it secure is step two. Here are some critical best practices:
1. Use HTTPS Everywhere
Never expose your ToolJet instance over HTTP. SSL/TLS is non-negotiable for authentication flows. Use a reverse proxy like Nginx or Traefik with Let’s Encrypt certificates.
2. Enable Two-Factor Authentication (2FA)
While ToolJet itself doesn’t have built-in 2FA for all login methods, your IdP (like Azure AD or Okta) can enforce MFA. Configure your IdP to require 2FA for all users.
3. Regularly Rotate Client Secrets
Update your OAuth client secrets periodically, especially if you suspect any compromise.
4. Monitor Login Logs
ToolJet provides logs for authentication events. Check them regularly for suspicious activity (e.g., multiple failed login attempts from unusual IPs).
5. Limit User Registration
By default, ToolJet may allow anyone to sign up if they have a valid email. In a self-hosted enterprise environment, you likely want to disable public registration and only allow users invited by admins.
Add this to your .env:
# Disable public registration
AUTH_ALLOW_SIGNUP=false
Part 5: Troubleshooting Common Issues
Even with the best plans, things can go wrong. Here are some common pitfalls and how to fix them.
Issue 1: “Invalid Grant” Error
This usually means your Client Secret is wrong or expired.
- Fix: Regenerate the Client Secret in your IdP and update your
.envfile.
Issue 2: Redirect URI Mismatch
The URL you configured in your IdP doesn’t match what ToolJet expects.
- Fix: Ensure the Redirect URI in your IdP is exactly
https://your-tooljet-domain/auth/sso/callback(or/auth/social/callback/github, etc.).
Issue 3: Users Can’t See the SSO Button
Check if AUTH_SSO_ENABLED is set to true in your .env.
- Fix: Set
AUTH_SSO_ENABLED=trueand restart ToolJet.
Issue 4: SSO Login Fails but Social Login Works
This suggests an issue with your OIDC/SAML configuration, not your network.
- Fix: Check the Issuer URL and Discovery Document. For Azure AD, ensure you’re using the correct tenant ID.
Conclusion: You’re Now Authenticated!
Congratulations! You’ve just set up a robust, enterprise-grade authentication system for your self-hosted ToolJet instance. You now have:
- SSO for seamless corporate logins.
- Social Login for quick, frictionless access.
- RBAC for controlling who can do what.
- Security best practices to keep your data safe.
Remember, authentication is not a “set it and forget it” task. Regularly review your user logs, update your secrets, and keep your IdP configurations current. Your users will thank you for the smooth experience, and your security team will breathe a sigh of relief.
If you run into any specific issues, the ToolJet community on Discord and GitHub is incredibly helpful. Happy automating!
Quick Reference: Essential Environment Variables
| Variable | Description | Example |
|---|---|---|
AUTH_SSO_ENABLED |
Enable SSO | true |
AUTH_SSO_PROVIDER |
SSO Protocol | oidc or saml |
AUTH_SSO_ISSUER |
IdP Issuer URL | https://login.microsoftonline.com/... |
AUTH_SSO_CLIENT_ID |
OAuth Client ID | your-client-id |
AUTH_SSO_CLIENT_SECRET |
OAuth Client Secret | your-client-secret |
AUTH_SOCIAL_ENABLED |
Enable Social Login | true |
AUTH_SOCIAL_GITHUB_ENABLED |
Enable GitHub | true |
AUTH_SOCIAL_GOOGLE_ENABLED |
Enable Google | true |
AUTH_ALLOW_SIGNUP |
Allow Public Registration | false |