Configure Shinydocs Pro Control Center for Microsoft Sources (OneDrive, Teams, SharePoint Online, Exchange Online)

Overview

Shinydocs Pro reads OneDrive, Teams, SharePoint Online and Exchange Online through a Microsoft Entra ID app registration that you create in your tenant. This guide covers Shinydocs Pro 26.5 and later; the last section lists what differs in 26.4 and earlier.

The app registration uses two credentials:

• Certificate: Shinydocs Pro uses it to read your content. Every source needs it.

• Client secret: only used when a source's Search authentication type is Protected - OAuth2. Each person then signs in to Microsoft from Search, and sees only results they have access to.

One app registration can serve all four sources. The permissions table lists what each source needs; if you connect several sources, add each permission once.

Requirements

• Network: HTTPS (port 443) from the Shinydocs Pro server to:

  • login.microsoftonline.com

  • graph.microsoft.com

  • <tenant>.sharepoint.com (SharePoint Online sources)

  • *.sharepoint.com, including <tenant>-my.sharepoint.com, where Microsoft serves file downloads [Confirm C4]

• Browsers: users who sign in from Search need to reach login.microsoftonline.com.

• Entra roles: a role that can create app registrations (for example Application Administrator). Granting admin consent for Microsoft Graph application permissions needs Privileged Role Administrator or Global Administrator (Microsoft: grant admin consent).

• Certificate: a .cer file (public key) for Entra and a .pfx file (with the private key) for Shinydocs Pro. Your IT or network team may issue one; otherwise create one as described in the next section.

• Control Center address (Protected - OAuth2 only): the exact address users type to reach Control Center, for example https://shinydocs.contoso.com, or https://shinyvm:9701 if they include a port. You enter it in Entra and in each source, and it must match in both places.

Create a certificate

If your organization already issues certificates, follow its process; Microsoft recommends a certificate from a trusted certificate authority for production use. Otherwise, create a self-signed certificate with PowerShell, as Microsoft describes in Create a self-signed public certificate to authenticate your application.

1. Open PowerShell on any Windows computer.

2. Run the following, changing the name and validity to suit your policy:

$certName = "ShinydocsPro"
$cert = New-SelfSignedCertificate -Subject "CN=$certName" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -NotAfter (Get-Date).AddYears(2)
Export-Certificate -Cert $cert -FilePath ".\$certName.cer"
$pfxPassword = Read-Host -Prompt "Enter a password to protect the .pfx file" -AsSecureString
Export-PfxCertificate -Cert $cert -FilePath ".\$certName.pfx" -Password $pfxPassword

3. The current folder now holds ShinydocsPro.cer (upload it to Entra) and ShinydocsPro.pfx (upload it to Shinydocs Pro).

4. Optional: remove the certificate from this computer's store once both files are saved: Remove-Item "Cert:\CurrentUser\My\$($cert.Thumbprint)".

Anyone with the .pfx file and its password can use the app's permissions. Keep both in your organization's password manager or secret store, and note the expiry date so you can renew in time (see Renew the certificate and client secret).

Register the app in Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center.

2. Go to Entra ID > App registrations > New registration.

   
   

3. Enter a name, for example Shinydocs Pro.

4. Under Supported account types, select Single tenant only.

5. Leave the redirect URI empty; you add redirect URIs later, under Authentication.

6. Select Register.

   

7. On the Overview page, note the Application (client) ID and the Directory (tenant) ID. You need both in Control Center.

   

Upload the certificate

1. Open Certificates & secrets > Certificates > Upload certificate.

   

2. Select your .cer file (Entra also accepts .pem and .crt), add a description if you like, and select Add.

   

3. Check that the certificate is listed, and note its expiry date.

   

Create a client secret (Protected - OAuth2 only)

Skip this if no source will use Protected - OAuth2 for Search.

1. Open Certificates & secrets > Client secrets > New client secret.

2. Add a description and choose an expiry. Microsoft recommends less than 12 months, and the maximum is 24 months (Microsoft: add credentials).

3. Select Add.

4. Copy the Value column right away, not the Secret ID. Entra never shows the value again.

5. Store the value in your organization's password manager, not in a document or email.

6. Set a reminder before the expiry date. When the secret expires, Search sign-in for these sources stops working until you add a new secret to each source.

Add redirect URIs

Redirect URIs are needed only if a source uses Protected - OAuth2 for Search, or if Control Center sign-in uses this app registration. Entra sends a user back only to an address registered here, and the match must be exact: scheme, host name, port and path. A mismatch shows error AADSTS50011.

Choose one Control Center address and use it in three places: here, in each source's Redirect URL field, and in users' browsers.

• Port: include it if users type one (Control Center's default is 9701). Leave it out only if your DNS or proxy serves Control Center without a port.

• Host name: https://shinyvm:9701 and https://shinyvm.contoso.com:9701 are different addresses. Register the one users actually type; the sign-in is tied to their Control Center session, so it can't complete on a different host name.

1. In the app registration, open Authentication.

   

2. Add a redirect URI and choose the Web platform, not Single-page application.

3. Add the URIs from the table that apply to you, replacing <address> with your Control Center address, with no trailing slash.

4. Save. Changes can take a few minutes to apply.

5. Leave ID tokens and Access tokens (implicit grant) unchecked; Shinydocs Pro doesn't use them.

For example, if users reach Control Center at https://shinydocs.contoso.com, register https://shinydocs.contoso.com/oauth/authorized, and enter https://shinydocs.contoso.com as each source's Redirect URL.

Add API permissions

Add the permissions for each source you connect. Sources share some permissions; if you connect several, add each permission once.

1. In the app registration, open API permissions > Add a permission.

   
   

2. Choose the API from the table: Microsoft Graph or SharePoint.

   
   

3. Choose Application permissions or Delegated permissions, select the permissions, and select Add permissions.

   
   

4. Repeat for each row, then grant admin consent (below).

SharePoint Online's Sites.Read.All application permission goes under the SharePoint API, not Microsoft Graph. To limit Shinydocs Pro to specific sites instead, see the next section.

This guide covers analysis. To delete content with Dispose, also give the app permission to delete content in that source.

Grant admin consent

1. On the API permissions page, select Grant admin consent for your tenant, then Yes.

   
   

2. Check that every permission shows Granted for your tenant in the Status column.

This step is required. Application permissions always need admin consent. Microsoft's default user consent setting also stops users from consenting to Files.Read.All, Sites.Read.All or Mail.Read themselves, so without admin consent users see "Need admin approval" when they sign in from Search (Microsoft: app consent policies). If you add permissions later, grant consent again.

Optional: limit SharePoint Online to specific sites

Sites.Selected gives Shinydocs Pro access only to the sites you choose, instead of every site. Shinydocs recommends Sites.Read.All and AllSites.Read for simplicity and complete coverage; use Sites.Selected if your organization doesn't allow that level of access.

1. In the app registration, open API permissions and add these instead of the SharePoint Online permissions above:

2. Grant admin consent.

3. Give the app access to each site, with Read, or Write if you use Dispose. Use PnP PowerShell (below) or the Microsoft Graph API (Microsoft: create permission on a site).

4. When you add the source, enter each of these sites in the Site field. Leaving Site empty, to analyze all sites, needs Sites.Read.All.

Grant site access with PnP PowerShell

PnP PowerShell needs PowerShell 7.4 or later. It also needs an app registration of your own to sign you in, because the shared PnP app was retired in September 2024. That app needs the Microsoft Graph delegated permission Sites.FullControl.All to change site permissions.

1. If you don't have a PnP app registration yet, install PnP PowerShell and create one:

Install-Module PnP.PowerShell -Scope CurrentUser
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP PowerShell" -Tenant contoso.onmicrosoft.com -GraphDelegatePermissions "Sites.FullControl.All"

2. Note the client ID it returns. If you create the PnP app by hand instead, add the Mobile and desktop applications platform with the redirect URI http://localhost.

3. Sign in as a SharePoint Administrator or Global Administrator, and grant the Shinydocs Pro app access to each site:

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId "<PnP app client ID>" -Interactive
Grant-PnPEntraIDAppSitePermission -AppId "<Shinydocs Pro app client ID>" -DisplayName "Shinydocs Pro" -Permissions Read -Site "https://contoso.sharepoint.com/sites/<site name>"

4. If no error is shown, the grant worked. Repeat the second command for each site.

Older PnP versions call the cmdlet Grant-PnPAzureADAppSitePermission; that name still works (PnP: Grant-PnPEntraIDAppSitePermission).

Optional: limit Exchange Online to specific mailboxes

The application permission Mail.Read lets the app read every mailbox in your tenant. To limit it to certain mailboxes, use Exchange Online's RBAC for Applications, which replaces application access policies (Microsoft: RBAC for Applications in Exchange Online).

1. In Exchange Online PowerShell, as an Exchange Administrator, follow Microsoft's steps to register the app's service principal and assign it the Application Mail.Read role scoped to your mailboxes. Use Application Mail.ReadWrite if you use Dispose.

2. Check the assignment with Test-ServicePrincipalAuthorization.

3. Remove Mail.Read (application) from the app registration in Entra. Entra and Exchange grants add together, so leaving it in place keeps access to every mailbox.

4. Enter each in-scope mailbox in the source's Email address field, rather than leaving it empty.

Changes can take 30 minutes to 2 hours to apply.

Add the source in Control Center

Have these ready: the Application (client) ID, the Directory (tenant) ID, the .pfx file and its password, and, for Protected - OAuth2, the client secret value and your Control Center address. The steps are the same for all four sources, except where noted.

Connection

1. On the Sources page, select Add source. On first run, the quick-start wizard shows the same form.

   

2. Select Microsoft SharePoint Online, Microsoft Exchange Online, Microsoft Teams or Microsoft OneDrive, then Next.

3. Fill in the connection:

   • Connection name: a name you'll recognize later.

   • Tenant URL (SharePoint Online only): the root address, for example https://contoso.sharepoint.com. A site address is rejected here; you add sites in a later step.

   • Application ID: the Application (client) ID.

   • Tenant ID: the Directory (tenant) ID.

   • Certificate file: upload the .pfx file.

   • Certificate password: leave it empty if the .pfx has no password.

   • Search authentication type: how this source appears in Search. Hidden - Exclude from Search (the default) leaves it out. Public - No authentication required shows its results to everyone who uses Search. Protected - OAuth2 has each person sign in to Microsoft from Search and shows only what they can access. Protected - OIDC uses the person's Control Center sign-in instead of a separate one. It needs Control Center sign-in set up with OIDC, as described in Access and Authentication in Shinydocs Pro, and that app registration needs this source's delegated permissions with admin consent [Confirm C11].

   

4. For Protected - OAuth2, also fill in:

   • Client ID: the Application (client) ID again.

   • Client secret: the secret's value.

   • Login/Authorize endpoint: replace common with your Directory (tenant) ID, for example https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/authorize. A single-tenant app left on common fails with error AADSTS50194.

   • Token endpoint: the same change: https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/token.

   • Redirect URL: your Control Center address with no path, for example https://shinydocs.contoso.com or https://shinyvm:9701. Shinydocs Pro adds /oauth/authorized, and the result must match the redirect URI registered in Entra. The default, https://localhost:9701, only works in a browser on the server itself.

   

5. Select Next. Shinydocs Pro checks the certificate, Application ID and Tenant ID; for SharePoint Online it also checks the Tenant URL, and for OneDrive it lists users. It does not check the redirect URI, the client secret or admin consent; those show up only when someone signs in from Search, so test that after setup.

What to analyze

6. Optionally, enter what to analyze; leave the field empty to analyze everything the app can read. Each entry becomes its own source, and Add multiple takes one entry per line.

   

7. Exchange Online only: three options, all off by default.

   • Index inline images: indexes images embedded in message bodies, such as signature logos and pasted screenshots, as documents of their own. Other attachments are indexed either way.

   • Index extended message properties: adds each message's conversation topic, sensitivity and size on the server. It adds a request for every page of messages, so analysis takes longer.

   • Use immutable message IDs: keeps a message's ID when it moves between folders, so filing an email updates the existing document instead of creating a second one. Choose it before the first analysis; it can't be changed afterwards.

8. Under More options, choose a Schedule: Daily runs now and then every day at 8:00 PM server time; None runs once, now.

   

9. Select Start analysis.

Test Search sign-in

If a source uses Protected - OAuth2, test it as a regular user before rolling out:

1. Open Control Center at the address you registered, and go to Search.

2. Sign in to Microsoft for the source when prompted.

3. Search for something that user can access in the source, and check that it appears.

The sign-in lasts for the person's Control Center session. They sign in again after signing out of Control Center, or after the Shinydocs Pro service restarts.

The Control Center log records failed sign-ins: "Could not authenticate user" means the token exchange failed, usually the secret or token endpoint; "Could not authorize user" means Microsoft returned an error to Control Center, usually consent.

Renew the certificate and client secret

Renew both before they expire. Entra allows more than one certificate and secret at a time, so you can switch without downtime.

Certificate

1. Create or obtain a new certificate.

2. In Entra, upload the new .cer under Certificates & secrets, and keep the old certificate for now.

3. In Control Center, open Edit connection for each Microsoft connection, and upload the new .pfx and its password.

4. Once every connection uses the new certificate, delete the old one in Entra.

Client secret

1. In Entra, create a new client secret and copy its value.

2. In Control Center, open Edit connection for each source that uses Protected - OAuth2, and replace the Client secret.

3. Delete the old secret in Entra.

Differences in 26.4 and earlier

• Certificate: the field is Certificate file location, a path to the .pfx file on the computer where the Shinydocs Pro agent runs. Don't put quotes around the path. If the file moves, update the path, or analysis fails.

• More options (26.1 to 26.4): also lists the analysis tools to run on the source, each with a switch, above Schedule. 26.0 has no More options.

• Exchange Online: the three options (inline images, extended message properties, immutable message IDs) were added in 26.5.