ServiceAccount¶

The ServiceAccount resource creates Active Directory service accounts. Two account types are supported:

aduser (default) — a standard AD user account with an auto-generated password. Used by applications that authenticate with username + password.
gmsa — a Group Managed Service Account. The password is managed by AD and retrieved transparently by authorized computer accounts. Used by Windows services that should run under a managed identity without a stored password.

Structure¶

- type: serviceAccount
  name: svcapp                               # unique identifier within the RGT
  accounttype: aduser                        # optional, "aduser" (default) or "gmsa"
  svcName: "myapp-{{deployment.shortid}}"    # AD account name (supports expressions)
  memberOf:                                  # optional, AD groups to add the account to
    - "yourdomain\\.serveradmins-{{computenode.vmapp}}"

Key	Required	Description
`type`	Yes	Must be `serviceAccount`
`name`	Yes	Unique identifier within the RGT (used in expressions)
`accounttype`	No	`aduser` (default) or `gmsa`. Selects the AD account type.
`svcName`	Yes	The actual AD account name (SamAccountName). Supports expressions.
`memberOf`	No	List of AD groups this account should be a member of. Supports expressions.
`allowed_to_retrieve_password`	Yes (gmsa)	gMSA only. Principal(s) authorized to retrieve the gMSA password. Accepts a single string or a list. Computer accounts must be suffixed with `$` (e.g., `{{computenode.vm}}$`); AD groups are referenced by `domain\group`.

Naming Format¶

The final AD account name is determined by combining the AD_SERVICEACCOUNT_FORMAT variable with svcName:

Format variable: AD_SERVICEACCOUNT_FORMAT uses {0} as a placeholder for the svcName value
Default: {0} (the svcName is used as-is)
Example: If AD_SERVICEACCOUNT_FORMAT is svc-{{deployment.shortid}}-{0} and svcName is foo, the final name is svc-0fa0bb-foo

The account is created in the AD_USER_RESOURCE_OU organizational unit.

SamAccountName length limit

The final AD account name (SamAccountName) has a maximum length set by Active Directory:

aduser: 20 characters
gmsa: 15 characters (gMSAs share the pre-Windows 2000 computer-name limit)

Plan svcName and AD_SERVICEACCOUNT_FORMAT together so the combined result stays within the limit — e.g., a 4-character format prefix like svc- leaves 16 characters of svcName budget for an aduser, but only 11 for a gmsa.

gMSA (Group Managed Service Accounts)¶

Set accounttype: gmsa to create a Group Managed Service Account instead of a standard AD user. gMSAs are used by Windows services to run under a managed identity — AD generates and rotates the password automatically, and authorized hosts retrieve it transparently via Kerberos.

- type: serviceaccount
  accounttype: gmsa
  name: svc
  svcName: "{{resourcegroup.shortid}}"
  allowed_to_retrieve_password:                # single string or list
    - "{{computenode.vm1}}$"                   # computer account (trailing $)
    - "{{computenode.vm2}}$"
    - "yourdomain\\grp-gmsa-retrievers"        # AD group
  memberOf:
    - "yourdomain\\.serveradmins-{{computenode.vm1}}"
  dependsOn:
    - computenode.vm1
    - computenode.vm2

Key differences from aduser:

allowed_to_retrieve_password is required. It specifies which principal(s) — computer accounts and/or AD groups — are allowed to retrieve the managed password. Accepts a single string (one principal) or a list (multiple principals). Computer accounts must be referenced with a trailing $, e.g., {{computenode.vm}}$.
No usable password is stored. The svcpassword reference exists but should not be passed to services — gMSAs authenticate via Kerberos.
Reference with a $ suffix when used as an identity. When using a gMSA as the RunAs account for a service, suffix it with $, e.g., yourdomain\{{serviceaccount.svc}}$.
Requires AD_NETBIOS_DOMAIN_NAME in the ActiveDirectoryServices ResourceProvider config to construct the DNS suffix for the gMSA.
Add dependsOn for retrievers. If allowed_to_retrieve_password references a compute node, declare dependsOn on that resource so the host exists before the gMSA is staged.

Reference Format¶

Use {{serviceaccount.<name>.<property>}} to reference a service account in expressions.

Given a service account with name: svcfoo, svcName: foo, and AD_SERVICEACCOUNT_FORMAT: svc-{{deployment.shortid}}-{0}:

Expression	Type	Example output
`{{serviceaccount.svcfoo}}`	string	`svc-0fa0bb-foo`
`{{serviceaccount.svcfoo.svcname}}`	string	`svc-0fa0bb-foo`
`{{serviceaccount.svcfoo.svcpassword}}`	string	`fj2b00bgn24FF4f42$$`

Note

The password is auto-generated by Dune. Use svcpassword to pass it to config tasks that need to configure the service.

Modifiers (Variables)¶

Variable	Type	Required	Level	Default	Description
`DEFAULT_AD_RESOURCEPROVIDER`	string	Yes	Variable	—	Identifier of the Active Directory resource provider
`AD_SERVICEACCOUNT_FORMAT`	string	No	ResourceProvider	`{0}`	Naming format. `{0}` is replaced by `svcName`. Supports expressions.
`AD_USER_RESOURCE_OU`	string	Yes	ResourceProvider	—	OU path (DistinguishedName) where the account is created
`AD_NETBIOS_DOMAIN_NAME`	string	Yes (gmsa)	ResourceProvider	—	NetBIOS domain name used as the DNS suffix for gMSAs

Examples¶

`aduser` — nginx with a standard service account¶

A service account for an nginx service, configured on the VM via a PowerShell script:

resources:
  - type: computeNode
    computeType: virtualMachine
    name: vmapp
    image: win2022
    cpu: 4
    memory: 8
    domain: yourdomain.local
    config:
      - name: package
        variables:
          name:
            - nginx
      - name: invoke-psscript
        variables:
          script: |
            sc.exe config "nginx" obj= "{{serviceaccount.svcapp.svcname}}" password= "{{serviceaccount.svcapp.svcpassword}}"
            Get-Service nginx | Restart-Service
  - type: serviceAccount
    name: svcapp
    svcName: "nginx-{{deployment.shortid}}"
    memberOf:
      - "yourdomain\\.serveradmins-{{computenode.vmapp}}"

`gmsa` — Windows service running under a gMSA on a single host¶

Provision a VM and a gMSA, then set the gMSA as the RunAs identity of the Spooler service via a post-config task. The VM's computer account is authorized to retrieve the gMSA password.

resources:
  - type: serviceaccount
    accounttype: gmsa
    name: svc
    svcName: "{{resourcegroup.shortid}}"
    allowed_to_retrieve_password: "{{computenode.vm}}$"
    memberOf:
      - "yourdomain\\.serveradmins-{{computenode.vm}}"
    dependsOn:
      - computenode.vm
  - type: computeNode
    computeType: virtualMachine
    name: vm
    image: win2025
    size: standard_d4s_v5
    domain: yourdomain.local
postConfig:
  - name: set-service-runas
    limit: "{{computenode.vm.fqdn}}"
    variables:
      service_name: spooler
      runas_account: "yourdomain\\{{serviceaccount.svc}}$"
      force_dependent_services: true

Note

The $ suffix on {{computenode.vm}}$ (in allowed_to_retrieve_password) and on {{serviceaccount.svc}}$ (in runas_account) is required — AD identifies computer and gMSA principals with a trailing $.

`gmsa` — shared across multiple hosts¶

When the same gMSA is used by services on more than one host, list every host that needs to retrieve the password. A single string only works for one principal; lists let you authorize multiple computer accounts and/or AD groups at once.

resources:
  - type: serviceaccount
    accounttype: gmsa
    name: svcsql
    svcName: "sql-{{resourcegroup.shortid}}"
    allowed_to_retrieve_password:
      - "{{computenode.vmsql1}}$"
      - "{{computenode.vmsql2}}$"
      - "yourdomain\\grp-sql-gmsa-retrievers"
    memberOf:
      - "yourdomain\\.sqladmins"
    dependsOn:
      - computenode.vmsql1
      - computenode.vmsql2
  - type: computeNode
    computeType: virtualMachine
    name: vmsql1
    image: win2025
    size: standard_d4s_v5
    domain: yourdomain.local
  - type: computeNode
    computeType: virtualMachine
    name: vmsql2
    image: win2025
    size: standard_d4s_v5
    domain: yourdomain.local

Next: RbacResourceGroup