Repository navigation
Conversation
…tion Adds a setup guide and the new Authentication type and Server SPN parameters. Linear: APP-16568. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
salevine
added a commit
to appsmithorg/appsmith
that referenced
this pull request
Nov 21, 2026
…tion (#42652) ## Description > [!TIP] > **TL;DR:** SQL Server datasources can now sign in with a Windows (Active Directory) account through Kerberos. Choose **Authentication type → Windows (Kerberos)** and enter the account as `user@REALM` with its password. This works on self-hosted Appsmith that has Kerberos settings (krb5.conf) and can reach the domain controller. SQL Server login stays the default, and existing datasources do not change. Many on-premises SQL Servers allow only Windows authentication. Until now, Appsmith could connect to them only with a SQL Server login. This PR adds Kerberos with a domain service account's user name and password. It is the first of three options: - **Option A (this PR):** one service account per datasource. - **Option B (later):** each Appsmith user's own Windows account, through Kerberos delegation. - **Option C (later):** each user's own Microsoft Entra ID account. Decisions: - Kerberos only. NTLM is not supported, because it is often blocked and Microsoft is phasing it out. - Community Edition. - No keytab upload for now. A keytab is a file made from the account's password, and it is no safer than a stored password. It can be added if a customer needs it. Fixes https://linear.app/appsmith/issue/APP-16568 Depends on #42639 (driver 13.6.2, merged). ### How it works 1. The plugin logs in to the domain controller itself, with the datasource's user name and password. It never reads or writes a Kerberos ticket cache. So a ticket cached on the Appsmith server, for example after someone ran `kinit`, can never be used by a datasource. 2. It gives the driver the resulting credential (`gsscredential`). The driver gets a service ticket for `MSSQLSvc/host:port` and signs in to SQL Server with it. The password never goes to SQL Server. 3. The credential is reused until 5 minutes before it expires, so a pool of 10 connections logs in once. 4. When the domain controller refuses the username or password, the plugin waits before it tries that username and password again: 1 minute, then 2, 4 and 8, then every 15 minutes. Without the wait, the pool's retries could lock out the AD account. - The refusal is recorded once for the whole Appsmith server, keyed by the account and a keyed hash of the password. So a rebuilt pool, such as after a stale connection or for each **Test**, still waits. - A different password is tried at once. - Other failures, such as an unreachable domain controller, don't start a wait. Two mssql-jdbc 13.6 behaviours shaped this. Both were checked in the driver source: - The driver forgets a supplied credential after each logon attempt, but retries once by default. The retry would then run without the credential and hide SQL Server's real error. So Kerberos datasources set `connectRetryCount=0;transparentNetworkIPResolution=false`. - The driver's own Kerberos login reads a JVM-wide JAAS file, or a ticket cache with `useDefaultJaasConfig`. Kerberos datasources point it at a JAAS entry that does not exist, so it can never run. ### Where it works and where it does not ✅ means supported by design and covered by the automated tests, up to SQL Server receiving the ticket. Accepting the ticket needs a real domain. That is the manual checklist under Testing, and it is not done yet. | Case | Works? | Notes | |---|---|---| | Self-hosted Appsmith (Docker, Docker Compose, Kubernetes/Helm) | ✅ Yes | Needs krb5.conf and network access, see below. | | On-premises SQL Server 2019, 2022 or 2025 joined to Active Directory | ✅ Yes | The SQL Server service account needs a registered SPN, `MSSQLSvc/<host>:<port>`. | | SQL Server on a Linux host or container joined to AD | ✅ Yes | The same SPN and keytab setup that Microsoft documents for SQL Server on Linux. | | SQL Server on an Azure or AWS VM joined to AD | ✅ Yes | Same as on-premises. | | Default instance on port 1433 | ✅ Yes | | | Named instance on a fixed port | ✅ Yes | Enter the port. The SPN must name that port. | | Always On listener, DNS alias or IP address | ✅ Yes | Enter the registered name in **Server SPN**. | | Username `user@REALM`, such as `svc_appsmith@CORP.EXAMPLE.COM` | ✅ Yes | The realm is upper-cased automatically. | | Username with no `@REALM` | ✅ Yes | Uses `default_realm` from krb5.conf. | | Account in a trusted domain or another forest |⚠️ Not tested | Needs `[capaths]` or `[domain_realm]` in krb5.conf. | | Named instance on a dynamic port (SQL Browser) |⚠️ Not tested | Use a fixed port. | | Username as `DOMAIN\user` | ❌ No | Refused with a hint to use `user@REALM`. | | NTLM | ❌ No | Not supported, by decision. | | Local Windows accounts (not domain accounts) | ❌ No | Kerberos needs a domain account. | | Keytab or gMSA instead of a password | ❌ Not yet | Can be added if a customer needs it. | | Each Appsmith user signing in as themselves | ❌ Not yet | Options B and C. | | Appsmith Cloud | ❌ No | Cloud has no krb5.conf and cannot reach a customer's domain controller. | | Azure SQL Database and Azure SQL Managed Instance | ❌ No | They do not accept on-premises Kerberos. Microsoft Entra ID is planned (option C). | | Amazon RDS for SQL Server |⚠️ Not tested | Needs RDS joined to AWS Managed Microsoft AD. | **What the admin must set up** - **krb5.conf:** put it at `/etc/krb5.conf` in the Appsmith container, or set `APPSMITH_JAVA_ARGS=-Djava.security.krb5.conf=<path>`. Use a path without spaces. - On Docker, mount the file. - On Helm, use a ConfigMap with `extraVolumes` and `extraVolumeMounts`. No chart change is needed. - The file is read again on each login. - **Network:** the Appsmith server must reach the domain controller on port 88 (TCP and UDP), resolve the AD domain in DNS, and keep its clock within 5 minutes of the domain controller. - **SQL Server:** the account needs a SQL Server login and access to the database. **Known limits** - Export and Git import: the authentication type is cleared along with the credentials. Choose Windows (Kerberos) again after import. - All Kerberos datasources on one Appsmith server share its krb5.conf. - Password expiry: when the account's password expires or changes, the datasource fails until someone updates the password in it. - Rollback: an older Appsmith version ignores the authentication type. Kerberos datasources then fail with "Login failed" until they are switched to a SQL Server login. ### Errors Common failures show a plain hint instead of the raw Kerberos text: - wrong user name or password, or a disabled or locked-out account; - expired password; - clock skew; - unknown realm; - no krb5.conf; - domain controller unreachable; - SPN not registered; - SQL Server refused the ticket; - no SQL Server login for the account. Every "wrong account" answer from the domain controller (codes 6, 14, 18, 24 and 31, with or without detail text after the code) shows the same message. So the **Test** button cannot be used to find out which accounts exist. If the JVM setting `sun.security.krb5.principal` names a different account, the login is refused, because Java would otherwise sign in as that account instead of the datasource's. ### Stored data The authentication type and server SPN are stored in `datasourceConfiguration.properties`. `DBAuth` is unchanged and there is no migration. A datasource without the setting uses a SQL Server login, as before. The editor fills in a form's default values only for new datasources, so when someone edits an older datasource, the value can arrive without its key. The plugin then reads the value from the form's slot. A test checks that the slots in `form.json` match. ## Automation /ok-to-test tags="@tag.All" ## Testing - [ ] Client unit tests - [x] Server unit tests - [x] Cypress - [ ] Playwright - [ ] Deploy preview - [ ] Not applicable Suggested Cypress tags or specs: `@tag.Datasource` (MsSQL_Basic_Spec, MsSQLDataSourceStub_spec, Port_Number_Placeholder_Spec) **Automated** The full SQL Server plugin suite runs on SQL Server 2022 with 0 failures. New tests: - `MssqlKerberosLoginTest`: runs against a real Kerberos server inside the test (Apache Kerby, test scope only). It covers the right password, a wrong password, an unknown account, the default realm, getting a service ticket, and that no ticket cache or keytab is used. - `MssqlKerberosConnectionTest`: runs the whole plugin with Kerby and a SQL Server 2022 container. - The container is not joined to a domain, so its answer, "untrusted domain" (error 18452), shows that the plugin logged in, got a service ticket and sent it to SQL Server. - A wrong password fails at the Kerberos login and never reaches SQL Server. - SQL Server login still connects. - `MssqlKerberosDataSourceTest`: credential reuse and renewal; the wait after a refusal, kept across a rebuilt pool and skipped for a new password or for other failures; error text without the password; and the driver settings. - `MssqlKerberosFailuresTest`: the growing wait, the password hash key, and that old records are dropped. - `MssqlKerberosErrorsTest`: each error hint, and the shared message for a bad account. - `MssqlKerberosValidationTest`: validation, reading a value without its key, and the default for older datasources. - `MssqlFormSlotsTest`: `form.json` slots match the code. **Manual: needs a real domain** - [ ] A domain-joined SQL Server accepts a correct account, and queries run. - [ ] A wrong password shows the hint. Repeated **Test** clicks do not lock the account. - [ ] A custom Server SPN, such as an alias, connects. - [ ] Run `kinit` as another user on the Appsmith host. The datasource still connects as its own account. - [ ] An existing SQL Server datasource opens with "SQL Server login" selected, and saves and works unchanged. - [ ] After an Appsmith restart, a saved Kerberos datasource reconnects. ## Communication Should the DevRel and Marketing teams inform users about this change? - [x] Yes - [ ] No Docs: appsmithorg/appsmith-docs#3107 ## Release note ```release-note SQL Server datasources can now sign in with a Windows (Active Directory) account, using Kerberos with the account's username and password. Set **Authentication type** to **Windows (Kerberos)** and enter the account as `user@REALM`. Existing SQL Server datasources do not change. This works on self-hosted Appsmith only. The Appsmith server needs your Kerberos settings in `/etc/krb5.conf` (or a path set with `APPSMITH_JAVA_ARGS=-Djava.security.krb5.conf=<path>`) and must reach your domain controller on port 88. NTLM, keytab files, group Managed Service Accounts, Azure SQL Database and Appsmith Cloud are not supported. See [Connect to SQL Server with Windows Authentication](https://docs.appsmith.com/connect-data/how-to-guides/connect-sql-server-with-windows-authentication). ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: Cypress test results --> > [!TIP] > 🟢 🟢 🟢 All cypress tests have passed! 🎉 🎉 🎉 > Workflow run: <https://github.com/appsmithorg/appsmith/actions/runs/44833219386> > Commit: f95c766 > <a href="https://internal.appsmith.com/app/cypress-dashboard/rundetails-65890b3c81d7400d08fa9ee5?branch=master&workflowId=44833219386&attempt=1" target="_blank">Cypress dashboard</a>. > Tags: `@tag.All` > Spec: > <hr>Fri, 20 Nov 2026 23:38:22 UTC <!-- end of auto-generated comment: Cypress test results --> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents Windows (Kerberos) authentication for the Microsoft SQL Server datasource. Linear: APP-16568.
Merge when appsmithorg/appsmith#42652 ships. The pages say "from Appsmith v2.8". Change the version if the feature ships in a later release.
What changes:
connect-data/how-to-guides/connect-sql-server-with-windows-authentication. It covers:krb5.confon Docker Compose, Docker and Kubernetes (Helm), or withAPPSMITH_JAVA_ARGS;krb5.confper server, downgrading;🤖 Generated with Claude Code