Skip to content

Commit 168b3d4

Browse files
Sanjai1994Sanjai1994
committed
feat: Add SCIM + SSO JIT provisioning support for Entra ID
feat: Add SCIM + SSO JIT provisioning support for Entra ID feat: Add SCIM + SSO JIT provisioning support for Entra ID - Fix NullPointerException in createSCIMUserAndAddToOrg endpoint - Support placeholder user creation via SCIM for compliance - Enable JIT provisioning on first SSO login with correct auth source - Add comprehensive documentation for Entra ID integration - Prevent auth source mismatch between SCIM and SSO authentication This allows organizations to use SCIM for user pre-provisioning while maintaining proper SSO authentication with Entra ID (Azure AD).
1 parent ec6539d commit 168b3d4

File tree

4 files changed

+393
-0
lines changed

4 files changed

+393
-0
lines changed

‎docs/setup-and-run/self-hosting/JIT_PROVISIONING_WITH_ENTRA_ID.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# JIT (Just-In-Time) Provisioning with Entra ID (Azure AD)
2+
3+
This guide explains how to set up JIT user provisioning with Microsoft Entra ID (formerly Azure AD) for Lowcoder.
4+
5+
## Overview
6+
7+
**JIT Provisioning** automatically creates user accounts in Lowcoder when users authenticate via SSO for the first time. This eliminates the need for manual user creation or SCIM provisioning for basic SSO scenarios.
8+
9+
## How It Works
10+
11+
1. User clicks **"Sign in with Entra ID"** on Lowcoder login page
12+
2. User authenticates with Microsoft Entra ID
13+
3. Entra ID redirects back to Lowcoder with authentication details
14+
4. Lowcoder automatically:
15+
- Creates a new user account (if doesn't exist)
16+
- Sets up the correct auth connection (Entra ID, not EMAIL)
17+
- Adds user to the organization
18+
- Logs user in
19+
20+
## Prerequisites
21+
22+
- Lowcoder instance running (self-hosted or cloud)
23+
- Admin access to Lowcoder
24+
- Microsoft Entra ID (Azure AD) tenant
25+
- Admin access to Azure Portal
26+
27+
## Step 1: Configure Application in Azure Portal
28+
29+
### 1.1 Register a New Application
30+
31+
1. Go to [Azure Portal](https://portal.azure.com)
32+
2. Navigate to **Azure Active Directory** → **App registrations**
33+
3. Click **New registration**
34+
4. Configure:
35+
- **Name**: `Lowcoder SSO`
36+
- **Supported account types**: Choose based on your needs
37+
- Single tenant (most common for enterprise)
38+
- Multi-tenant (if needed)
39+
- **Redirect URI**:
40+
- Platform: `Web`
41+
- URI: `https://your-lowcoder-domain.com/api/auth/oauth2/callback`
42+
5. Click **Register**
43+
44+
### 1.2 Configure API Permissions
45+
46+
1. In your app registration, go to **API permissions**
47+
2. Click **Add a permission**
48+
3. Select **Microsoft Graph**
49+
4. Choose **Delegated permissions**
50+
5. Add these permissions:
51+
- `openid`
52+
- `profile`
53+
- `email`
54+
- `User.Read`
55+
6. Click **Add permissions**
56+
7. Click **Grant admin consent** (if you have admin rights)
57+
58+
### 1.3 Create Client Secret
59+
60+
1. Go to **Certificates & secrets**
61+
2. Click **New client secret**
62+
3. Description: `Lowcoder SSO Secret`
63+
4. Expires: Choose appropriate duration (12-24 months recommended)
64+
5. Click **Add**
65+
6. **IMPORTANT**: Copy the secret **Value** immediately (you won't see it again!)
66+
67+
### 1.4 Note Your Configuration Details
68+
69+
From **Overview** page, note:
70+
71+
- **Application (client) ID**: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
72+
- **Directory (tenant) ID**: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
73+
74+
## Step 2: Configure Entra ID Provider in Lowcoder
75+
76+
### 2.1 Access Admin Settings
77+
78+
1. Log in to Lowcoder as **admin**
79+
2. Go to **Settings** → **Authentication** (or Admin panel)
80+
3. Click **Add Authentication Provider**
81+
82+
### 2.2 Configure Generic OAuth Provider
83+
84+
Fill in the following details:
85+
86+
| Field | Value |
87+
| -------------------------- | --------------------------------------------------------------------- |
88+
| **Provider Name** | `Entra ID` or `Azure AD` |
89+
| **Auth Type** | `GENERIC` (Generic OAuth2) |
90+
| **Client ID** | `<Application (client) ID from Azure>` |
91+
| **Client Secret** | `<Client secret value from Azure>` |
92+
| **Authorization Endpoint** | `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize` |
93+
| **Token Endpoint** | `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token` |
94+
| **User Info Endpoint** | `https://graph.microsoft.com/v1.0/me` |
95+
| **Scope** | `openid profile email User.Read` |
96+
| **Enable Registration** | ✅ **TRUE** (This enables JIT provisioning!) |
97+
98+
Replace `{tenant-id}` with your actual tenant ID.
99+
100+
### 2.3 Configure User Attribute Mappings
101+
102+
Set up how Entra ID user attributes map to Lowcoder user fields:
103+
104+
```json
105+
{
106+
"uid": "id",
107+
"username": "userPrincipalName",
108+
"email": "mail",
109+
"avatar": "photo"
110+
}
111+
```
112+
113+
Or if email field is sometimes null:
114+
115+
```json
116+
{
117+
"uid": "id",
118+
"username": "userPrincipalName",
119+
"email": "userPrincipalName",
120+
"avatar": "photo"
121+
}
122+
```
123+
124+
### 2.4 Save Configuration
125+
126+
Click **Save** or **Enable** to activate the provider.
127+
128+
## Step 3: Test JIT Provisioning
129+
130+
### 3.1 Test User Login
131+
132+
1. **Log out** from Lowcoder (if logged in)
133+
2. Go to Lowcoder login page
134+
3. You should see **"Sign in with Entra ID"** button
135+
4. Click the button
136+
5. You'll be redirected to Microsoft login
137+
6. Enter credentials and authenticate
138+
7. You'll be redirected back to Lowcoder
139+
8. **User account is automatically created** ✅
140+
141+
### 3.2 Verify User Creation
142+
143+
As admin:
144+
145+
1. Go to **Settings** → **Members** or **Users**
146+
2. You should see the newly created user
147+
3. Check user details:
148+
- Auth Source should be **"Entra ID"** (not EMAIL)
149+
- Email should match the Entra ID account
150+
- User should be active
151+
152+
## SCIM + JIT Combined Approach (Optional)
153+
154+
If you need both SCIM provisioning AND SSO authentication:
155+
156+
### Use Case
157+
158+
- SCIM pre-provisions users (for compliance/audit)
159+
- Users still authenticate via SSO
160+
- JIT adds auth connection on first login
161+
162+
### How It Works with Updated Code
163+
164+
The updated `createSCIMUserAndAddToOrg` endpoint now:
165+
166+
1. **Creates a placeholder user** via SCIM (no auth connection)
167+
2. **On first SSO login**, JIT provisioning adds the Entra ID auth connection
168+
3. **Subsequent logins** work normally via SSO
169+
170+
### Configure Entra ID SCIM Provisioning
171+
172+
1. In Azure Portal, go to your **Enterprise Application**
173+
2. Navigate to **Provisioning**
174+
3. Set **Provisioning Mode**: `Automatic`
175+
4. Configure:
176+
- **Tenant URL**: `https://your-lowcoder-domain.com/api/v1/organizations/{orgId}/scim/users`
177+
- **Secret Token**: Your API token
178+
5. **Mappings**: Map Azure AD attributes to SCIM attributes
179+
6. **Save** and **Start Provisioning**
180+
181+
## Troubleshooting
182+
183+
### Issue: "Sign in with Entra ID" button doesn't appear
184+
185+
**Solution**:
186+
187+
- Verify the auth provider is **enabled** in settings
188+
- Check that `enableRegister` is set to `true`
189+
- Clear browser cache and reload
190+
191+
### Issue: User login fails with "LOG_IN_SOURCE_NOT_SUPPORTED"
192+
193+
**Solution**:
194+
195+
- Verify Authorization, Token, and User Info endpoints are correct
196+
- Check that tenant ID is properly replaced in URLs
197+
- Verify client ID and secret are correct
198+
199+
### Issue: User created but with wrong auth source (EMAIL instead of Entra ID)
200+
201+
**Solution**:
202+
203+
- This means SCIM endpoint was used with old code
204+
- With updated code, SCIM creates placeholder users
205+
- JIT adds correct auth connection on first SSO login
206+
- Rebuild Docker image with the fix
207+
208+
### Issue: "EMAIL_PROVIDER_DISABLED" error
209+
210+
**Solution**:
211+
212+
- This error occurs if trying to create EMAIL-based users when EMAIL auth is disabled
213+
- Use SSO with JIT provisioning instead
214+
- Don't use the old SCIM implementation that creates EMAIL users
215+
216+
## Security Considerations
217+
218+
1. **Client Secret**: Store securely, rotate regularly
219+
2. **Redirect URI**: Must exactly match what's configured in Azure
220+
3. **Scope**: Request minimum permissions needed
221+
4. **Enable Registration**: Only enable if you want JIT provisioning
222+
5. **Organization**: Configure which organization new users join
223+
224+
## Advanced Configuration
225+
226+
### Multi-Organization Support
227+
228+
If you have multiple organizations:
229+
230+
- Configure separate OAuth providers per organization
231+
- Or use organization domains to auto-assign users
232+
233+
### Custom User Roles
234+
235+
To assign custom roles on JIT provisioning:
236+
237+
- Modify `AuthenticationApiServiceImpl.onUserLogin()`
238+
- Add logic to check Entra ID groups/roles
239+
- Map to Lowcoder roles accordingly
240+
241+
### Email Verification
242+
243+
JIT-provisioned users are automatically verified since they authenticated via SSO.
244+
245+
## Comparison: SCIM vs JIT
246+
247+
| Feature | SCIM Provisioning | JIT Provisioning |
248+
| -------------------- | ---------------------------- | ---------------------- |
249+
| **User Creation** | Pre-provisioned via SCIM | Created on first login |
250+
| **Setup Complexity** | High | Low |
251+
| **Auth Source** | EMAIL (with old code) | Correct SSO source |
252+
| **Works with SSO** | Requires fix | ✅ Native support |
253+
| **Audit Trail** | Full provisioning audit | Login-based audit |
254+
| **Use Case** | Compliance, pre-provisioning | Simple SSO |
255+
256+
## Recommendation
257+
258+
For most use cases: **Use JIT Provisioning** (simpler, works correctly with SSO)
259+
260+
For compliance requirements: **Use SCIM + JIT Combined** (with updated code)
261+
262+
## References
263+
264+
- [Microsoft Entra ID OAuth2 Documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow)
265+
- [Lowcoder Authentication Documentation](../../../workspaces-and-teamwork/oauth/)
266+
- [Generic OAuth Provider Setup](../../../workspaces-and-teamwork/oauth/generic-oauth-provider.md)

‎docs/setup-and-run/self-hosting/JIT_QUICK_START.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Quick Start: Enable JIT Provisioning with Entra ID
2+
3+
## What is JIT Provisioning?
4+
5+
**Just-In-Time (JIT) Provisioning** automatically creates user accounts when they first login via SSO. No manual user creation or SCIM needed!
6+
7+
## Why Use JIT?
8+
9+
✅ **Simple** - Minimal configuration
10+
✅ **Secure** - Users authenticated via Entra ID
11+
✅ **Correct** - Proper auth source (not EMAIL)
12+
✅ **Fast** - Users created on first login
13+
14+
## 5-Minute Setup
15+
16+
### 1. Azure Portal Setup (3 minutes)
17+
18+
1. Go to [Azure Portal](https://portal.azure.com) → **App registrations** → **New registration**
19+
2. Name: `Lowcoder SSO`, Redirect URI: `https://your-domain.com/api/auth/oauth2/callback`
20+
3. Create a **Client Secret** (save the value!)
21+
4. Add permissions: **API permissions** → **Microsoft Graph** → `User.Read`, `email`, `profile`, `openid`
22+
5. Note your **Client ID** and **Tenant ID**
23+
24+
### 2. Lowcoder Configuration (2 minutes)
25+
26+
Login as admin → **Settings** → **Authentication** → **Add Provider**:
27+
28+
```yaml
29+
Provider Name: Entra ID
30+
Auth Type: GENERIC
31+
Client ID: <from Azure>
32+
Client Secret: <from Azure>
33+
Authorization Endpoint: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
34+
Token Endpoint: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
35+
User Info Endpoint: https://graph.microsoft.com/v1.0/me
36+
Scope: openid profile email User.Read
37+
Enable Registration: ✅ TRUE # ← This enables JIT!
38+
```
39+
40+
**User Mappings**:
41+
42+
```json
43+
{
44+
"uid": "id",
45+
"username": "userPrincipalName",
46+
"email": "mail"
47+
}
48+
```
49+
50+
### 3. Test (30 seconds)
51+
52+
1. Logout from Lowcoder
53+
2. Click **"Sign in with Entra ID"**
54+
3. Authenticate with Microsoft
55+
4. ✅ User automatically created and logged in!
56+
57+
## That's It!
58+
59+
No SCIM needed. No manual user creation. Users are provisioned automatically on first login with the correct authentication source.
60+
61+
## Need SCIM?
62+
63+
If you need SCIM for compliance, see the full guide: [JIT_PROVISIONING_WITH_ENTRA_ID.md](./JIT_PROVISIONING_WITH_ENTRA_ID.md)
64+
65+
## Troubleshooting
66+
67+
**Can't see "Sign in with Entra ID" button?**
68+
69+
- Check `Enable Registration` is ✅ TRUE
70+
- Verify provider is enabled in settings
71+
72+
**Login fails?**
73+
74+
- Verify redirect URI matches exactly
75+
- Check client ID and secret are correct
76+
- Verify tenant ID in endpoints
77+
78+
## Support
79+
80+
For detailed documentation, see: [JIT_PROVISIONING_WITH_ENTRA_ID.md](./JIT_PROVISIONING_WITH_ENTRA_ID.md)

0 commit comments

Comments
 (0)