Skip to content

docs(mssql): connect to SQL Server with Windows (Kerberos) authentication - #3107

Open
salevine wants to merge 2 commits into
mainfrom
docs/app-16568-mssql-kerberos
Open

salevine wants to merge 2 commits into
mainfrom
docs/app-16568-mssql-kerberos

Conversation

@salevine

Copy link
Copy Markdown
Contributor

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:

  • New guide: connect-data/how-to-guides/connect-sql-server-with-windows-authentication. It covers:
    • where Windows authentication works and where it does not (hosting, SQL Server types, account types, NTLM, keytab, Cloud);
    • prerequisites: the AD account, the SQL Server login, SPN registration, network access and clock sync;
    • how to give Appsmith krb5.conf on Docker Compose, Docker and Kubernetes (Helm), or with APPSMITH_JAVA_ARGS;
    • creating the datasource, and how Appsmith uses the account, including the retry wait that prevents lockout;
    • limits: export and Git, password changes, one krb5.conf per server, downgrading;
    • troubleshooting, with every error message the feature shows.
  • SQL Server reference page:
    • the new Authentication type and Server SPN parameters, and Username guidance for each type;
    • a row in "Differences between versions";
    • a troubleshooting row;
    • a See also link.
  • Sidebar: the new guide is listed under Connect Data → How-to Guides.

🤖 Generated with Claude Code

…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>
@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
appsmith-docs Ready Ready Preview Nov 18, 2026 5:50pm UTC

Request Review

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

1 active deployment
Preview — 7cb8100c Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant