Page Comparison

- [Introduction](#introduction)
- [Components](#components)
- [gMSA Account](#gmsa-account)
  - [Create the KDS Root Key If None Exists](#create-the-kds-root-key-if-none-exists)
  - [Create Variables](#create-variables)
  - [Create an Active Directory Security Group](#create-active-directory-security-group)
  - [Add the Saga Host to the Security Group](#add-the-saga-host-to-the-security-group)
  - [Create the gMSA Account](#create-the-gmsa-account)
- [Validate gMSA Account](#validate-gmsa-account)

## Introduction
The Saga platform requires a Group Managed Service Account (gMSA) in any of the following scenarios:
- Saga is set up with Microsoft SQL Server database.
- Saga is set up with one or more connectors that access resources over the Windows-based network (for instance by reading files from the disk of another server).
- Authority service is set up with Active Directory user authentication.
- Authority service is set up with Azure Active Directory user authentication and the *Saga AD AAD Sync* setting is enabled in the Saga install script.

In all the scenarios above, the executed functionality resides within Docker containers. Although Docker containers cannot be Active Directory domain joined, they can still use Active Directory domain identities to support various authentication scenarios. To achieve this, the Docker containers can be configured to run with a group Managed Service Account (gMSA), which is a special type of service account introduced in Windows Server 2012 and designed to allow multiple computers to share an identity without needing to know its password.

## Components
Here are some more details about each component involved in creating a gMSA account:
  - **Key Distribution Service (KDS)**: The Key Distribution Service (KDS) plays a crucial role in the management of gMSA accounts. It is responsible for renewing the randomly generated passwords that gMSA accounts rely on for authentication. The KDS Root Key, which is created as a one-time operation, is a prerequisite for the Key Distribution Service to generate and distribute these passwords securely. The KDS ensures that gMSA accounts have up-to-date and strong passwords for secure service authentication.

  - **Active Directory Service Account**: The Active Directory Service Account is the gMSA account required by Saga. It acts as a dedicated service account with controlled access rights and permissions. The gMSA account provides a secure identity for services and applications, allowing them to authenticate and interact with various resources in the Windows-based network.

  - **Active Directory Security Group**: An Active Directory Security Group is a group object within the Active Directory that helps organize and manage access permissions. In the context of gMSA accounts, an Active Directory Security Group is created to associate the gMSA account with a specific group. This Security Group acts as a container that holds and controls the membership of the gMSA account. By linking the gMSA account to a Security Group, administrators can easily manage access permissions, apply group policies, and control the resources that the gMSA account can interact with.

  - **Security Group member server (search.company.com)**: The Security Group member server refers to the Saga server, in this case named "search.company.com". This server is added as a member to the previously created Active Directory Security Group. By including the server as a member of the Security Group, the gMSA account associated with the group gains access rights and permissions to interact with resources on this server. This enables the gMSA account to authenticate and access the necessary file systems, services, or other network resources hosted on the Security Group member server. That is, all three scenarios that we listed at the start, are supported.

## gMSA Account
The steps in this section is based on the Microsoft article [Create gMSAs for Windows containers](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#one-time-preparation-of-active-directory).

This is the procedure for creating a gMSA account:
  - Create the KDS Root Key if none exists
  - Create an Active Directory Security Group.
  - Add the Saga host to the Security Group.
  - Create the gMSA account that is linked to the Security Group and have the gMSA account's DNS Host Name and Service Principle Names added.

Below we provide a manual way of creating the gMSA account. The requirements to run these PowerShell commands are:
  - One needs to be a domain administrator
  - One needs to run the PowerShell commands from the Saga host (as the variables gets information from the host server)

The PowerShell commands below are just examples that shows the most straightforward setup. It is specified which PowerShell commands that might require additional parameters and adaptation for ones Active Directory domain.

### Create the KDS Root Key If None Exists
This step is only required the very first time a gMSA account is created. To check if it exists, run this PowerShell command:
  ```
  Get-KdsRootKey
  ```

If the command above fails, then run this next command. If it does not fail, then jump to the next section of commands.
  ```
  Add-KdsRootKey -EffectiveImmediately
  ```
One needs to wait until command `Get-KdsRootKey` returns a key ID until proceeding ahead to next section. That could potentially take many hours.

### Create Variables
To avoid repetitions, create a few variables. The next lines is just to avoid having to repeat the same values over and over in the next blocks of code:

```
  $gatewayHostname = "<the Gateway Hostname set in Saga installer, for instance search.company.com>"
  $gmsaName = "<some name, for instance saga>"
  $adGroupName= "$gmsaName Authorized Hosts"
  $adGroupSamAccountName = "$($gmsaName)Hosts"
  $dnsRoot = (Get-AdDomain).DnsRoot
  $dnsHostName = "$gmsaName.$dnsRoot"
  $sagaHost = "$env:computername$"
```

### Create Active Directory Security Group
  To create the Active Directory security group, run this PowerShell command:
  ```
  New-ADGroup -Name $adGroupName -SamAccountName $adGroupSamAccountName -GroupScope DomainLocal
  ```

Additional parameters that should be considered for one's domain are:
  - Path

  For exhaustive list, see [New-AdGroup](https://learn.microsoft.com/en-us/powershell/module/activedirectory/new-adgroup).


### Add the Saga Host to the Security Group
To Add the Saga Host to the Security Group, run this PowerShell command:
  ```
  Add-ADGroupMember -Identity $adGroupSamAccountName -Members "$sagaHost"
  ```

### Create the gMSA Account
To create the gMSA account, run this PowerShell command:
  ```
  New-ADServiceAccount -Name $gmsaName -DnsHostName $dnsHostName -ServicePrincipalNames "host/$gmsaName", "host/$gmsaName.$dnsRoot", "http/$gatewayHostname" -PrincipalsAllowedToRetrieveManagedPassword $adGroupSamAccountName
  ```

Additional parameters that should be considered for ones domain are:
  - Path
  - KerberosEncryptionType
    - The Kerberos Encryption Types setting is by default not set in the domain and can thus be ignored when creating the gMSA account. However, if it is set, then the gMSA account must have a matching setting. See [Network security: Configure encryption types allowed for Kerberos](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/network-security-configure-encryption-types-allowed-for-kerberos) for default and optional values.

  For exhaustive list, see [New-ADServiceAccount](https://learn.microsoft.com/en-us/powershell/module/activedirectory/new-adserviceaccount).

After the gMSA account is created, one needs to reboot the Saga host server, before proceeding ahead to validating the gMSA account in next section.

## Validate gMSA Account
To validate the the account, runt this PowerShell command:
  ```
    Test-ADServiceAccount -Identity <gmsaName>
  ```

If one has already installed Saga one can also validate the newly created account by running this PowerShell script (the path assumes the recommended install directory):
  ```
  & "D:\Program Files\ayfie\saga\scripts\verify-gmsa-setup.ps1"
  ```