Configure Shinydocs Pro Control Center for Azure Files (Azure file share)

If your organization is using traditional Active Directory Domain Controllers, you'll run a PowerShell script to integrate the Azure file share with Active Directory. You can integrate using either a service logon account or a computer account.

Additional requirements for this scenario:

• A domain-connected Windows server with the following software installed:

  • .NET Framework 4.7.2 runtime or above

  • Windows PowerShell

  • Azure PowerShell Module

  • Active Directory PowerShell Module (add via Server Manager > Add Roles and Features > Remote Server Administration Tools) (more info: https://learn.microsoft.com/en-us/powershell/azure/install-azps-windows?view=azps-11.5.0&tabs=windowspowershell&pivots=windows-psgallery)

  • AzFilesHybrid Module (download from Microsoft)

• Domain rights to create a computer account in Active Directory

• Azure Reader role on the Resource Group containing the storage account

• Azure Contributor role on the Storage Account

• The following information:

  • Azure subscription ID

  • Resource Group name

  • Storage Account name

  • SamAccountName - name for the account you will create (15 characters or less)

  • DomainAccountType - either ComputerAccount or ServiceLogonAccount

  • OuDistinguishedName - the location in Active Directory for the account (e.g., CN=Computers,DC=contoso,DC=com)

Steps:

1. Extract the AzFilesHybrid.zip file to a folder on your domain-connected Windows server

2. Create a file called Join-AzStorageAccount.ps1 in the same directory as the extracted files

3. Paste the following script into the file:

   POWERSHELL

   # Change the execution policy to unblock importing AzFilesHybrid.psm1 module
   Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
   
   # Navigate to where AzFilesHybrid is unzipped and stored and run to copy the files into your path
   .\CopyToPSPath.ps1 
   
   # Import AzFilesHybrid module
   Import-Module -Name AzFilesHybrid
   
   # Login to Azure using a credential that has either storage account owner or contributor Azure role 
   # assignment. If you are logging into an Azure environment other than Public (ex. AzureUSGovernment) 
   # you will need to specify that.
   # See https://learn.microsoft.com/azure/azure-government/documentation-government-get-started-connect-with-ps
   # for more information.
   Connect-AzAccount
   
   # Define parameters
   # $StorageAccountName is the name of an existing storage account that you want to join to AD
   # $SamAccountName is the name of the to-be-created AD object, which is used by AD as the logon name 
   # for the object. It must be 15 characters or less and has certain character restrictions.
   # Make sure that you provide the SamAccountName without the trailing '$' sign.
   # See https://learn.microsoft.com/windows/win32/adschema/a-samaccountname for more information.
   $SubscriptionId = "<your-subscription-id-here>"
   $ResourceGroupName = "<resource-group-name-here>"
   $StorageAccountName = "<storage-account-name-here>"
   $SamAccountName = "<sam-account-name-here>"
   $DomainAccountType = "<ComputerAccount|ServiceLogonAccount>" # Default is set as ComputerAccount
   # If you don't provide the OU name as an input parameter, the AD identity that represents the 
   # storage account is created under the root directory.
   $OuDistinguishedName = "<ou-distinguishedname-here>"
   # Encryption method is AES-256 Kerberos.
   
   # Select the target subscription for the current session
   Select-AzSubscription -SubscriptionId $SubscriptionId 
   
   # Register the target storage account with your active directory environment under the target OU 
   # (for example: specify the OU with Name as "UserAccounts" or DistinguishedName as 
   # "OU=UserAccounts,DC=CONTOSO,DC=COM"). You can use this PowerShell cmdlet: Get-ADOrganizationalUnit 
   # to find the Name and DistinguishedName of your target OU. If you are using the OU Name, specify it 
   # with -OrganizationalUnitName as shown below. If you are using the OU DistinguishedName, you can set it 
   # with -OrganizationalUnitDistinguishedName. You can choose to provide one of the two names to specify 
   # the target OU. You can choose to create the identity that represents the storage account as either a 
   # Service Logon Account or Computer Account (default parameter value), depending on your AD permissions 
   # and preference. Run Get-Help Join-AzStorageAccountForAuth for more details on this cmdlet.
   
   Join-AzStorageAccount `
           -ResourceGroupName $ResourceGroupName `
           -StorageAccountName $StorageAccountName `
           -SamAccountName $SamAccountName `
           -DomainAccountType $DomainAccountType `
           -OrganizationalUnitDistinguishedName $OuDistinguishedName
   
   # You can run the Debug-AzStorageAccountAuth cmdlet to conduct a set of basic checks on your AD configuration 
   # with the logged on AD user. This cmdlet is supported on AzFilesHybrid v0.1.2+ version. For more details on 
   # the checks performed in this cmdlet, see Azure Files Windows troubleshooting guide.
   Debug-AzStorageAccountAuth -StorageAccountName $StorageAccountName -ResourceGroupName $ResourceGroupName -Verbose

4. Update the script, replacing all placeholder values (shown in angle brackets) with your actual values

5. Open Windows PowerShell as Administrator and navigate to the directory where you saved the script

6. Execute the script:

   CODE

   .\Join-AzStorageAccount.ps1

7. Follow any prompts to complete the script execution

8. Confirm the account exists in Active Directory by opening Active Directory Users and Computers and searching for the SamAccountName you used

9. Ensure you can mount the drive locally using your domain credentials

Setting Up Kerberos Delegation to the file share

Computer Account Kerberos Delegation

Once the computer account is configured, setup kerberos delegation in the same manner you would to a on premise file server using the instructions in the expander-panel below:

Setting SPNs and Authorizations

1. Set Shinydocs Control Center service to start as the service account

   1. In Windows, open Services

   2. Right-click on the Shinydocs Control Center service > Properties > Log On

   3. Select This account. Then browse for the Shinydocs service account and enter the password

      

   4. Click OK when complete

2. Give the service account local permissions to the default certificate that comes with Shinydocs Pro

   1. On the Shinydocs Pro server, open certlm.msc.

   2. In the left panel, expand Certificates (Local Computer).

   3. Navigate to Personal > Certificates.

   4. Right-click the certificate named localhost.localdomain.

   5. Choose All Tasks > Manage Private Keys.

   6. In the dialog, select Add.

   7. Find and select your service account.

   8. Under the Allow column, check Read.

   9. Click Apply, then OK to save.

3. Register SPNs to allow permission checking

   1. Open CMD as administrator

   2. Run the following command
      Replace <hostname> with your server’s hostname.
      Replace <domain>\<serviceAccount> with your domain and the name of the Shinydocs service account.

      CODE

      setspn -S HTTP/<hostname> <domain>\<serviceAccount>

   3. Verify that the SPNs were set correctly by running the command

      CODE

      setspn -l <domain>\<serviceAccount>

4. Authorize your file share(s) for Kerberos double-hop. On one of your domain controllers or a computer with Get-ADComputer PowerShell module installed (included in Active Directory installation). If you have multiple file shares, this will need to be configured for each:

   1. On the computer with Get-ADComputer, open PowerShell

   2. Check if there are existing authorizations:

      CODE

      Get-ADComputer <FileShareServerName> -Properties PrincipalsAllowedToDelegateToAccount

      1. If there are existing entries in the PrincipalsAllowedToDelegateToAccount key, copy the hostnames for the next step.

   3. Run the following command:

      CODE

      $Server1 = Get-ADComputer -Identity <ShinydocsSearchServerName OR valid FQDN>

      1. IF there were existing authorizations with Get-ADComputer, add them separately and one at a time like this, run each on its own:

         CODE

          $Server2 = Get-ADComputer -Identity <ExistingAuthorizationHostName1>

         CODE

          $Server3 = Get-ADComputer -Identity <ExistingAuthorizationHostName2>

      2. IF Shinydocs Search is load balanced on additional machines, you will need to also add the other Shinydocs Search hostnames or FQDNs:

         CODE

          $Server4 = Get-ADComputer -Identity <<ShinydocsSearchServer2Name OR valid FQDN>>

   4. Now you’re ready to submit the request to set the PrincipalsAllowedToDelegateToAccounton all of the above machines via PowerShell. Note that the $Server1 variable you set previously is used in the command:

      1. Scenario 1:
         1 Shinydocs Search instance, no existing authorizations

         CODE

         Set-ADComputer <FileShareHostName or FQDN> -PrincipalsAllowedToDelegateToAccount $Server1

      2. Scenario 2:
         Multiple Shinydocs Search instances (load balanced) and/or existing authorizations
         Note: You need to change the list of $Server variables in this command to match how many you have set up in the previous steps

         CODE

         Set-ADComputer FILESHARE-01 -PrincipalsAllowedToDelegateToAccount @($Server1, $Server2, $Server3, $Server4)

   5. Verify it was set by running the following in PowerShell:

      CODE

      Get-ADComputer <FileShareServerName> -Properties PrincipalsAllowedToDelegateToAccount

      You will see the Shinydocs servers listed in principalsAllowedToDelegateToAccount

      

The Set-ADComputer example commands above overwrite the current PrincipalsAllowedToDelegateToAccount values on a FileShareServerName. To remove a PrincipalsAllowedToDelegateToAccount value from a FileShareServerName, you can re-run one of the above commands and exclude the value you wish to remove.

Alternatively; to remove all values from PrincipalsAllowedToDelegateToAccount from a FileShareServerName, you can run the below command (replacingFileShareServerName with the actual fileshare hostname):

Set-ADComputer FileShareServerName -PrincipalsAllowedToDelegateToAccount $null

Service Login Account Kerberos Delegation

1. Open a Active Directory Module for Windows Powershell Window

2. Ensure that Enterprise Search is running as a service account with the proper spns set.

3. Retrieve the list of computers already delegated to the service login account

   CODE

   get-aduser -identity shinykerbtest -properties PrincipalsAllowedToDelegateToAccount

4. Update the list of computers allowed to delegate to the service logon account

   CODE

   $server1 = Get-AdComputer <enterprise search computer name>
   
   #optional load any existing computers that already had delegation set
   $server2 = Get-AdComputer <prior computer with delegation already set>
   $server3 = Get-AdComputer <prior computer with delegation already set>
   
   # if you have multiple servers, the syntax is below to update the delegation list on the service account to include all the computers
   Set-AdUser <service logon account> --PrincipalsAllowedToDelegateToAccount @($server1, $server2, $server3)
   
   # if you only have the 1 server to add, the syntax can be simplified below.
   Set-AdUser <service logon account> -PrincipalsAllowedToDelegateToAccount $server1

In this scenario, your organization is running Microsoft Entra Domain Services. To connect the Azure File Share to the domain, Microsoft has an article on how to do that: https://learn.microsoft.com/en-us/azure/storage/files/storage-files-identity-auth-domain-services-enable?tabs=azure-portal.

This will always create a service logon account with the same name as the azure storage account. The kerberos delegation script is below.

Service Login Account Kerberos Delegation

1. Open a Active Directory Module for Windows Powershell Window

2. Ensure that Enterprise Search is running as a service account with the proper spns set.

3. Retrieve the list of computers already delegated to the service login account
   This should be on the computer’s Active Directory and Computers. You will need to check the pre-2000 service account name and use that if different.

   CODE

   get-aduser -identity <service logon account> -properties PrincipalsAllowedToDelegateToAccount

4. Update the list of computers allowed to delegate to the service logon account

   POWERSHELL

   $server1 = Get-AdComputer <enterprise search computer name>
   
   #optional load any existing computers that already had delegation set
   $server2 = Get-AdComputer <prior computer with delegation already set>
   $server3 = Get-AdComputer <prior computer with delegation already set>
   
   # if you have multiple servers, the syntax is below to update the delegation list on the service account to include all the computers
   Set-AdUser <service logon account> --PrincipalsAllowedToDelegateToAccount @($server1, $server2, $server3)
   
   # if you only have the 1 server to add, the syntax can be simplified below.
   Set-AdUser <service logon account> -PrincipalsAllowedToDelegateToAccount $server1