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

In Shinydocs Pro 26.1+ we introduced an official Azure Files connector. This guide has been updated to reflect the new configuration.

What you are setting up

In this guide, you will be setting up an Azure Files source in Shinydocs Pro for analysis and setting up the connection for permission checking of Search results for your source.

Once complete:

• Your Azure Files source will be analyzed by Shinydocs Pro

• Files are immediately searchable via Search, enforcing Azure Files permissions on all search results.

Requirements

• Shinydocs Pro is installed and running.

• Internet access to reach Microsoft Online

  • If the server cannot have direct internet access, ensure firewall rules are setup to allow HTTPS traffic on port 443

• Azure/Entra permission to:

  • Create application registrations

  • Grant admin consent

  • Permission to see and modify your storage account

• A certificate used to authenticate (Azure requires the .cer and Shinydocs Pro requires the .pfx)

Create the self signed certificate for Azure

If you already have a process internally for creating these certificates, please follow your organizations best practices. If not, you can use the script below.

#Requires -RunAsAdministrator
<#
.SYNOPSIS
Creates a Self Signed Certificate for use in server to server authentication
.DESCRIPTION
.EXAMPLE
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key.
.EXAMPLE
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Password (ConvertTo-SecureString -String "MyPassword" -AsPlainText -Force)
This will create a new self signed certificate with the common name "CN=MyCert". The password as specified in the Password parameter will be used to protect the private key
.EXAMPLE
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Force
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key. If there is already a certificate with the common name you specified, it will be removed first.
#>
Param(

[Parameter(Mandatory=$true)]
   [string]$CommonName,

[Parameter(Mandatory=$true)]
   [DateTime]$StartDate,

[Parameter(Mandatory=$true)]
   [DateTime]$EndDate,

[Parameter(Mandatory=$false, HelpMessage="Will overwrite existing certificates")]
   [Switch]$Force,

[Parameter(Mandatory=$false)]
   [SecureString]$Password
)

# DO NOT MODIFY BELOW

function CreateSelfSignedCertificate(){

#Remove and existing certificates with the same common name from personal and root stores
    #Need to be very wary of this as could break something
    if($CommonName.ToLower().StartsWith("cn="))
    {
        # Remove CN from common name
        $CommonName = $CommonName.Substring(3)
    }
    $certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
    if($certs -ne $null -and $certs.Length -gt 0)
    {
        if($Force)
        {

foreach($c in $certs)
            {
                remove-item $c.PSPath
            }
        } else {
            Write-Host -ForegroundColor Red "One or more certificates with the same common name (CN=$CommonName) are already located in the local certificate store. Use -Force to remove them";
            return $false
        }
    }

$name = new-object -com "X509Enrollment.CX500DistinguishedName.1"
    $name.Encode("CN=$CommonName", 0)

$key = new-object -com "X509Enrollment.CX509PrivateKey.1"
    $key.ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
    $key.KeySpec = 1
    $key.Length = 2048
    $key.SecurityDescriptor = "D:PAI(A;;0xd01f01ff;;;SY)(A;;0xd01f01ff;;;BA)(A;;0x80120089;;;NS)"
    $key.MachineContext = 1
    $key.ExportPolicy = 1 # This is required to allow the private key to be exported
    $key.Create()

$serverauthoid = new-object -com "X509Enrollment.CObjectId.1"
    $serverauthoid.InitializeFromValue("1.3.6.1.5.5.7.3.1") # Server Authentication
    $ekuoids = new-object -com "X509Enrollment.CObjectIds.1"
    $ekuoids.add($serverauthoid)
    $ekuext = new-object -com "X509Enrollment.CX509ExtensionEnhancedKeyUsage.1"
    $ekuext.InitializeEncode($ekuoids)

$cert = new-object -com "X509Enrollment.CX509CertificateRequestCertificate.1"
    $cert.InitializeFromPrivateKey(2, $key, "")
    $cert.Subject = $name
    $cert.Issuer = $cert.Subject
    $cert.NotBefore = $StartDate
    $cert.NotAfter = $EndDate
    $cert.X509Extensions.Add($ekuext)
    $cert.Encode()

$enrollment = new-object -com "X509Enrollment.CX509Enrollment.1"
    $enrollment.InitializeFromRequest($cert)
    $certdata = $enrollment.CreateRequest(0)
    $enrollment.InstallResponse(2, $certdata, 0, "")
    return $true
}

function ExportPFXFile()
{
    if($CommonName.ToLower().StartsWith("cn="))
    {
        # Remove CN from common name
        $CommonName = $CommonName.Substring(3)
    }
    if($Password -eq $null)
    {
        $Password = Read-Host -Prompt "Enter Password to protect private key" -AsSecureString
    }
    $cert = Get-ChildItem -Path Cert:\LocalMachine\my | where-object{$_.Subject -eq "CN=$CommonName"}

Export-PfxCertificate -Cert $cert -Password $Password -FilePath "$($CommonName).pfx"
    Export-Certificate -Cert $cert -Type CERT -FilePath "$CommonName.cer"
}

function RemoveCertsFromStore()
{
    # Once the certificates have been been exported we can safely remove them from the store
    if($CommonName.ToLower().StartsWith("cn="))
    {
        # Remove CN from common name
        $CommonName = $CommonName.Substring(3)
    }
    $certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
    foreach($c in $certs)
    {
        remove-item $c.PSPath
    }
}

if(CreateSelfSignedCertificate)
{
    ExportPFXFile
    RemoveCertsFromStore
}

Step 1 - Register Shinydocs Software with Azure

The first step of the process is to register your Shinydocs software with Azure, so that it can access Azure Files data.

You only need to register one application for Shinydocs software. Permissions to supported repositories can be configured the one registration.

1. Open Microsoft Azure.

2. In the upper left corner dropdown menu, navigate to Azure Active Directory.

   

3. From the sidebar menu, select App registrations

   

4. Select + New registration

   

5. Enter a name for the application. In this case, we used “Shinydocs Pro” as the application name.

6. Select who, within your organization, can use or access the application. In most cases, the first option (Single tenant) will be selected (see below).

7. The optional Redirect URl is not needed in this case.

8. Select Register to continue.

   

Upload Authentication Certificate to Azure

These steps require a .cer file.

1. From the sidebar menu, select Certificates & secrets

2. Select Certificates

3. Select Upload certificate

   

4. Select the folder icon to browse for your certificate (.cer). Optionally, add a description to let other administrators know what this certificate is used for.

   

5. Select Add

6. Verify that the certificate was uploaded successfully by confirming the certificate is shown Certificates

   

7. Still in Certificates & secrets, click the Client secrets tab.

8. Click + New client secret

   1. In the Add a client secret panel, add a description of your choice

   2. Set it to expire in 12 months or longer.
      This is a good time to schedule a reminder for the expiry, as Shinydocs Pro will also need the new secret key when this one expires.

   3. Click Add.

   4. Copy the secret key to a safe location, as you will not be able to retrieve it later.

9. In the left-hand menu, open Overview

10. Note/save the following information for configuring Shinydocs Pro in later steps.

• Application (client) ID: ___________________________________________________
• Directory (tenant) ID: ___________________________________________________
• Secret key: ___________________________________________________

Authentication

Still in the Azure portal Shinydocs application registration, now you will set up the redirect URIs for authentication.

1. Navigate to the Authentication tab in the application registration

   

2. Web > Redirect URIs

   1. This set up will be for the server running Shinydocs Pro Search using it’s hostname. You can update these settings later when/if you set up your fully qualified domain name in your DNS.

   2. Click Add URI, and add the following

      1. https://<shinydocs pro server host name>/azuread/success

         1. e.g. https://shinyvm/azuread/success

      2. https://<shinydocs pro server host name>/api/v1/oidc/signin-callback

         1. e.g.https://shinyvm/api/v1/oidc/signin-callback

      3. https://localhost/azuread/success

      4. https://localhost/api/v1/oidc/signin-callback

Step 2 - Assign the Roles to the Service Principal

When an application registration is performed in Azure, a Service Principal is automatically created for it. In this step, you will be assigning the appropriate roles for it to access Azure Files.

1. In the Azure portal, navigate to the Storage account section in your tenant

   

2. Select Access Control (IAM) from the sidebar.

   

3. Click Add, then select Add role assignment.

4. Search for and select one or both depending on what you want Shinydocs Pro to be able to do:
   

   

   1. Storage File Data Privileged Contributor
      You want to analyze your content and action it (i.e. disposal)

   2. Storage File Data Privileged Reader
      You only want to analyze data and not action it (i.e. disposal)

5. Under Members, select User, group, or service principal.

6. Search for and select your Shinydocs App Registration by name.

7. Click Review + assign.

Step 3 - Azure API Permissions Configuration (for Search functionality)

Now that the Shinydocs Application has been registered with Azure, it’s time to apply permissions to access content within SharePoint Online.

1. From the sidebar menu, select API permissions

   

2. Select + Add a permission

   

3. Select Microsoft Graph:

   

4. Then, select Delegated permissions

   

5. Add the following delegated permissions

   1. User.Read
      Type: Delegated

   2. offline_acccess
      Type: Delegated

   3. openid
      Type: Delegated

   4. profile
      Type: Delegated

   5. Sites.Read.All
      Type: Delegated

6. Click Add permissions

7. Next, select Grant admin consent for [Tenant Name].

   

8. Select Yes to grant consent for the requested permissions for all accounts in [Directory Name].

   

9. At the top of the page, there will be a notification that admin consent for the requested permissions was successfully granted.

Step 4 - Add your Azure Files source in Shinydocs Pro Control Center

These steps can be followed once Shinydocs Pro has been installed.
You will need the .pfx file from your certificate.

Moving the .pfx after setting the Certificate file location will cause any related tasks to fail.

If the .pfx file is moved, you will need to update the Certificate file location to the new path.

In Shinydocs Control Center (either in quick-start or + Add source):

1. Select Azure Files as your new or existing source and click Next

   

2. Fill out the form with the details from your app regirstation

   

   1. Service Uri: Replace storageAccountName with the name of your Azure Storage Account. (e.g. azslfiletest)

   2. Share Name: The name of the Azure file share you want to analyze

   3. Application ID: enter the Application (client) ID previously noted

   4. Tenant ID: enter the Directory (tenant) ID previously noted

   5. Certificate file location: enter the path of the .pfx file

      1. Do not use double quotes around the path

   6. Certificate password: enter the password for the .pfx file. If your .pfx file does not have a password, leave this field blank

   7. Search Authentication Type: select Protected - OAuth2

      

      1. Client ID: Enter the Client ID from your application registration

      2. Client Secret (key): Enter the secret from your application registration

      3. Login/Authorize Endpoint: replace “common” with your Tenant ID

         1. e.g. https://login.microsoftonline.com/42abc123-a76a-4j03-bf1e-4e51c696d65d/oauth2/v2.0/authorize

      4. Token Endpoint: replace “common” with your Tenant ID

         1. e.g. https://login.microsoftonline.com/42abc123-a76a-4j03-bf1e-4e51c696d65d/oauth2/v2.0/token

      5. Redirect URL: For the Redirect URL, https://localhost:9701 works for initial testing when you're accessing Search directly on the server. Once Search is deployed and being accessed by end users through a proper hostname or load balancer, this needs to be updated to match the actual URL users will hit, for example:

         https://search.contoso.com:9701

         or whatever the production hostname and port end up being. The format is always just the domain and port, since /oauth/authorized gets appended automatically.
         

         Important: the Redirect URL here and the Redirect URI configured on the App Registration in Azure Entra ID must match exactly. If you update one, you need to update the other, or the OAuth flow will fail with a redirect mismatch error.
         

3. Click Next. A validation check is performed to make sure the information entered is correct. If an error occurs, the error should indicate the issue at hand.

4. You can now choose the scope of the analysis:

   

   1. Enter the folder path exactly as it appears in your file share, relative to the share root. Use a forward slash ( / ) to separate nested folders.

      Examples:

Note: Paths are case-sensitive. Reports and reports are treated as different folders. If the path is not found, you will see a validation error before the crawl begins.

Crawling multiple folders

Click + Add to add another folder entry. Each path is crawled independently as its own root, so you can mix folders from different locations in the share:

Finance/Invoices
HR/Contracts
Shared/Templates

Only the contents of the specified folders (and their subfolders) will be indexed.

Tips

• Do not include a leading slash (use Reports, not /Reports).

• If two folders share the same name in different locations, use the full path to specify the correct one (e.g., SubFolder1/ABC vs SubFolder2/ABC).

• Use + Add multiple to paste a list of paths at once.

More options

In Shinydocs Pro 26.1+, administrators can now by default select which analysis tools will run on the source.

• Extracting digital and image content reads file contents, including images, for analysis.

  • Digital fingerprint (Hash): creates a unique identifier for each file to detect exact duplicates.

  • Text Extraction: extracts readable text from documents for searching and analysis (includes OCR).

• Tag duplicate: marks files as duplicates based on their digital fingerprint across all Shinydocs Pro sources.

• Identifying people, places and organizations: detects mentions of people, locations, and organizations within document content.

• Identifying content with personal information: scans for personally identifiable information like names, addresses, and social insurance/security numbers (PII).

• Identifying non-valuable content: flags redundant, obsolete, or trivial (ROT) content to identify cleanup candidates.

• AI Analysis Tool (license dependent, requires setup before use): employs AI for deeper content classification beyond rules.

• Schedule: controls how often analysis tasks run. "Daily" runs them once per day.

Click Start Analysis when you are ready to begin.

Congratulations! You should now be crawling your organization’s Azure Files content.