> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/database-authentication.md).
# Database authentication
The three ways the JD Edwards Agent can authenticate to your database
The agent authenticates to the JD Edwards database in one of three ways. Pick one before you run the grant script. The choice decides which principal your DBA grants.
| Option | `auth_mode` | Runs on | Databases |
| ------------------------------------------------------------- | ----------- | -------------- | --------------------- |
| [A. SQL Server login](#option-a-sql-server-login) | `sql` | Linux, Windows | SQL Server and Oracle |
| [B. gMSA](#option-b-gmsa) | `windows` | Windows | SQL Server |
| [C. Domain service account](#option-c-domain-service-account) | `windows` | Windows | SQL Server |
Option A is the default: omitting `auth_mode` selects it. `auth_mode: windows` applies to the `mssql` driver only, and is rejected at startup on a non-Windows host. For B and C, the agent host and SQL Server must be in the same Active Directory domain, or in domains with a trust between them.
Whichever option you take, `config.yaml` still needs your BalkanID `tenant_id`, `tenant_key` and `tenant_secret`. See [Configuration](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#configuration). The grant scripts are installed alongside the binary; paths are listed under [Installation](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#installation).
***
### Option A: SQL Server login
Use this when the agent runs on Linux, the database is Oracle, the SQL Server is not in the agent host's domain or a trusted one, or your DBA will not create a Windows login.
#### Step 1: Prepare the grant script
Open `grant-mssql.sql` and set both principal variables at the top of the file to the login name:
```
:setvar AuditLogin "BALKANID_JDE_RO"
:setvar AuditUser "BALKANID_JDE_RO"
```
Leave section **B1** (the SQL login path) as shipped and section **B2** (the Windows path) commented out. Replace the placeholder password in B1. `DEFAULT_DATABASE` must be the JD Edwards system database.
```sql
CREATE LOGIN [$(AuditLogin)]
WITH PASSWORD = N'',
DEFAULT_DATABASE = [$(SystemDB)],
CHECK_POLICY = ON;
```
#### Step 2: Run the grant script
```powershell
sqlcmd -S jde-sql.internal.example.com -E -i grant-mssql.sql
```
On Oracle, run `grant-oracle.sql` instead. Its section B creates the user and grants `CREATE SESSION`; set the password there. Under the Oracle `DEFAULT` profile that password expires after 180 days and extraction then fails with `ORA-28001`.
#### Step 3: Configure the agent
```powershell
& "C:\Program Files\BalkanID\jde-agent\balkanid-jde-agent.exe" --configure
```
```sh
sudo balkanid-jde-agent --configure
```
The wizard tests the connection and writes the file only on success. By hand, set these keys on the instance:
```yaml
auth_mode: sql # the default; may be omitted
db_username: BALKANID_JDE_RO
db_password: ""
```
Oracle uses the same two credential keys, with `driver: oracle`, `port: 1521` and a `service_name`. There is no `auth_mode` on Oracle. `instances` is nested under `jde`; there is no top-level `instances` key.
#### Step 4: Verify
Run `balkanid-jde-agent --test-connection`. See [Verify the connection](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#verify-the-connection).
#### Rotating the password
The configuration file is read once, at startup. Stop the service before the password is changed, and start it after.
```powershell
Stop-Service BalkanIDJDEAgent
# DBA changes the password in the database
& "C:\Program Files\BalkanID\jde-agent\balkanid-jde-agent.exe" --configure
Start-Service BalkanIDJDEAgent
```
On Linux, `systemctl stop`, `balkanid-jde-agent --configure`, `systemctl start`.
***
### Option B: gMSA
Use this when the agent host runs Windows, the database is SQL Server, the domain functional level is 2012 or later, and your AD team will issue a group Managed Service Account.
Step 1 is run by your AD team, step 4 by your DBA, and the rest on the agent host by a local Administrator.
#### Step 1: Create the gMSA
The KDS root key is created once per forest. Check for an existing one with `Get-KdsRootKey`; if nothing is returned, create it and wait **10 hours** before creating any gMSA, so the key replicates to every domain controller.
```powershell
Add-KdsRootKey -EffectiveImmediately
New-ADGroup -Name 'JDE-Agent-Hosts' -GroupScope Global -GroupCategory Security
Add-ADGroupMember -Identity 'JDE-Agent-Hosts' -Members 'JDEAPP01$'
New-ADServiceAccount -Name svc_balkanid_jde `
-DNSHostName svc_balkanid_jde.contoso.com `
-PrincipalsAllowedToRetrieveManagedPassword 'JDE-Agent-Hosts'
```
`JDEAPP01$` is the agent host's computer account. The trailing `$` is required.
#### Step 2: Reboot the agent host and verify
The host's group membership takes effect at boot. After the reboot, on the agent host:
```powershell
Install-WindowsFeature RSAT-AD-PowerShell
Test-ADServiceAccount svc_balkanid_jde$
```
`True` means proceed. `False` means the computer account is not in the group, or the host has not rebooted since it was added.
#### Step 3: Grant "Log on as a service"
On the agent host: `secpol.msc` → **Local Policies** → **User Rights Assignment** → **Log on as a service** → add `CONTOSO\svc_balkanid_jde$`. In the Select Users dialog, click **Object Types** and tick **Service Accounts** before searching. Where this right is delivered by Group Policy, grant it in the GPO.
#### Step 4: Grant SQL Server access to the gMSA
In `grant-mssql.sql`, set both principal variables to the gMSA, including the trailing `$`:
```
:setvar AuditLogin "CONTOSO\svc_balkanid_jde$"
:setvar AuditUser "CONTOSO\svc_balkanid_jde$"
```
Comment out section **B1** and uncomment section **B2**. In section B2, replace the example account name in both places with your own, `$` included:
```sql
IF NOT EXISTS (SELECT 1 FROM sys.server_principals WHERE name = N'CONTOSO\svc_balkanid_jde$')
CREATE LOGIN [CONTOSO\svc_balkanid_jde$] FROM WINDOWS
WITH DEFAULT_DATABASE = [JDE_SYSTEM];
GO
```
Your DBA then runs `sqlcmd -S jde-sql.internal.example.com -E -i grant-mssql.sql`. The rest of the script is unchanged: per-table `SELECT` grants, then `DENY INSERT, UPDATE, DELETE, EXECUTE, ALTER` on all four owner schemas. You can grant a domain group instead of the account. Add the account to the group and point the variables at the group.
#### Step 5: Install, pointed at the gMSA
From an elevated PowerShell, in the directory holding the release bundle:
```powershell
.\install.ps1 -File .\balkanid-jde-agent_windows_amd64.zip -GmsaAccount 'CONTOSO\svc_balkanid_jde$'
```
There is no password to supply, and the installer will not accept one alongside `-GmsaAccount`. The installer verifies the account with `Test-ADServiceAccount` and stops if this host cannot retrieve the password.
If you run the [directory hardening block](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#hardening-windows), include the `icacls` line granting the service account modify rights on the data directory.
#### Step 6: Configure the agent
```powershell
& "C:\Program Files\BalkanID\jde-agent\balkanid-jde-agent.exe" --configure
```
By hand, set `auth_mode: windows` on the instance and omit `db_username` and `db_password` entirely.
#### Step 7: Restart the service and verify
```powershell
Restart-Service BalkanIDJDEAgent
(Get-CimInstance Win32_Service -Filter "Name='BalkanIDJDEAgent'").StartName
Get-Content "C:\ProgramData\BalkanID\jde-agent\logs\.log" -Tail 50 -Wait
```
`StartName` must be the gMSA, with the `$`. `--test-connection` run from an interactive shell authenticates as your own account, not the service account, so confirm the service's own first cycle in the log.
***
### Option C: domain service account
Use this when the agent host runs Windows and the database is SQL Server, but a gMSA is not available. Create the account, then follow Option B from step 3 with the two changes below. Steps 1 and 2 do not apply.
```powershell
New-ADUser -Name 'svc_balkanid_jde' -SamAccountName 'svc_balkanid_jde' `
-AccountPassword (Read-Host -AsSecureString 'Password') `
-PasswordNeverExpires $true -CannotChangePassword $true -Enabled $true
```
| Option B step | Change for Option C |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [Step 4: grant SQL Server access](#b-step-4) | Set `AuditLogin` and `AuditUser` to `CONTOSO\svc_balkanid_jde`, with no trailing `$`. |
| [Step 5: install](#b-step-5) | `.\install.ps1 -File .\balkanid-jde-agent_windows_amd64.zip -ServiceCredential (Get-Credential 'CONTOSO\svc_balkanid_jde')` |
Steps 3, 6 and 7 are unchanged, except that `StartName` must be `CONTOSO\svc_balkanid_jde`.
***
### Next
Continue with [Configuration](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#configuration) for the BalkanID tenant credentials, then [Verify the connection](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#verify-the-connection). Authentication faults are listed in [Service management and troubleshooting](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/service-management-and-troubleshooting.md#troubleshooting).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/database-authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.