Skip to content
English
  • There are no suggestions because the search field is empty.

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
  • 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:

PowerShell

$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
  1. The current folder now holds ShinydocsPro.cer (upload it to Entra) and ShinydocsPro.pfx (upload it to Shinydocs Pro).
  2. 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.
Redirect URI Needed for
<address>/oauth/authorized Search sign-in for sources set to Protected - OAuth2
<address>/api/v1/oidc/signin-callback Control Center sign-in with OIDC, if it uses this app registration (see Access and Authentication in Shinydocs Pro)
<address>/api/v1/oidc/signout-callback Control Center sign-out, with the sign-in above
https://localhost:9701/oauth/authorized and the two localhost versions of the URIs above Optional: signing in from a browser on the Shinydocs Pro server itself

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).
Source API Type Permissions
SharePoint Online Microsoft Graph Delegated User.Read, offline_access, openid, profile, Files.Read.All
SharePoint Online SharePoint Delegated AllSites.Read
SharePoint Online SharePoint Application Sites.Read.All
Exchange Online Microsoft Graph Application User.Read.All, Mail.Read
Exchange Online Microsoft Graph Delegated Directory.AccessAsUser.All, email, EWS.AccessAsUser.All, Files.Read.All, Group.Read.All, Mail.Read, Mail.Read.Shared, offline_access, openid, profile, User.Read
Teams Microsoft Graph Application Channel.ReadBasic.All, ChannelMember.Read.All, ChannelMessage.Read.All, ChannelSettings.Read.All, Chat.Read.All, Chat.ReadBasic.All, ChatMessage.Read.All, Files.Read.All, Team.ReadBasic.All, User.Read.All
Teams Microsoft Graph Delegated offline_access, openid, profile, User.Read, Files.Read.All, Sites.Read.All, Directory.Read.All, Channel.ReadBasic.All, ChannelMember.Read.All, Chat.Read, Group.Read.All, Team.ReadBasic.All, TeamSettings.Read.All
OneDrive Microsoft Graph Application Files.Read.All, Directory.Read.All
OneDrive Microsoft Graph Delegated offline_access, openid, profile, User.Read, Files.Read.All, Directory.Read.All

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:
API Type Permissions
Microsoft Graph Delegated User.Read, offline_access, openid, profile, Sites.Selected, Files.Read.All
SharePoint Application Sites.Selected, User.Read.All
  1. Grant admin consent.
  2. 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).
  3. 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:

PowerShell

Install-Module PnP.PowerShell -Scope CurrentUser Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP PowerShell" -Tenant contoso.onmicrosoft.com -GraphDelegatePermissions "Sites.FullControl.All"
  1. 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.
  2. Sign in as a SharePoint Administrator or Global Administrator, and grant the Shinydocs Pro app access to each site:

PowerShell

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>"
  1. 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.
  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
  1. 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.
Source Field What to enter
SharePoint Online Site A site address, for example https://contoso.sharepoint.com/sites/Finance. Subsites are included automatically, so don't add a site and its subsite separately. Empty analyzes all sites and needs Sites.Read.All.
Exchange Online Email address A mailbox's user principal name (UPN), for example alex@contoso.com. Empty analyzes every user with an email address.
Teams User Ids or Teams Ids A user's UPN or object ID, or a team's ID or exact name. Type it exactly as it appears in Entra; matching is case-sensitive.
OneDrive User Id The user's UPN. Email aliases and object IDs aren't accepted.
  1. 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.
  2. Under More options, choose a Schedule: Daily runs now and then every day at 8:00 PM server time; None runs once, now.
  3. 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.

Error or symptom Cause Fix
AADSTS50011: redirect URI doesn't match The source's Redirect URL plus /oauth/authorized isn't registered exactly in Entra, often because of a missing port or a different host name Register the exact URI, or correct the Redirect URL
AADSTS50194 common is still in the endpoints of a single-tenant app Replace common with the Directory (tenant) ID in both endpoints
AADSTS65001, or "Need admin approval" Admin consent hasn't been granted for a delegated permission Grant admin consent on the API permissions page
AADSTS7000215 The client secret is wrong, often the Secret ID copied instead of the value Enter the secret's value
AADSTS7000222 The client secret has expired Create a new secret and update each source
AADSTS700016 The app isn't found in that tenant Check the Client ID and the tenant ID in both endpoints
Sign-in completes, but the source stays signed out or shows no results Control Center was opened at a different address from the Redirect URL, or a delegated permission is missing Use the registered address, and check the delegated permissions and consent

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 the certificate and the client secret before they expire. You can see the expiry dates under Certificates & secrets in the app registration. A client secret lasts 24 months at most. Control Center doesn’t warn you before a credential expires, so note each expiry date when you create the credential and plan to renew it a few weeks ahead.

Microsoft Entra ID lets an app have more than one certificate and client secret at a time, so you can add the new one, switch Control Center over, and then remove the old one without interrupting crawls or Search.

Certificate
  1. Create a new certificate, as described in Create a certificate.
  2. In the Microsoft Entra admin center, open the app registration, select Certificates & secrets > Certificates > Upload certificate, and add the new .cer. Keep the old certificate for now.

In Control Center

  1. Go to Sources, find the group for the connection, and select Edit. You can also go to Settings > Connections, choose the connector, and select Edit connection.
  2. Switch on Replace the stored credentials, choose the new .pfx in Certificate file, and enter its password in Certificate password (optional).
  3. Select Save changes. Control Center checks the new credential through an agent before saving, so an agent must be running. If the check fails, nothing is saved and the dialog shows the error.

Repeat this for each Microsoft connection, for example if SharePoint Online and Exchange Online use separate connections. The change applies to every source that shares the connection. Crawls that start after you save use the new credential, and nothing needs to change on the agents. To check the connection again later, select Run tests in Settings > Connections.

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

If the certificate has already expired, crawls of these sources fail until you replace it. Testing or saving a connection with the expired certificate shows: The provided certificate has expired in the Azure app registration. Register a new certificate and try again.

Client secret (Protected - OAuth2 only)
  1. In Entra, select Certificates & secrets > Client secrets > New client secret, choose an expiry, and copy the Value. Entra shows it only once.
  2. In Control Center, go to Sources, find the group for the connection, and select Edit. You can also go to Settings > Connections, choose the connector, and select Edit connection.
  3. In Client secret, delete the asterisks (**********) and enter the new value. If you leave the asterisks, Control Center keeps the old value. It’s under Search Authentication Type.
  4. Save changes, then repeat for each connection that uses Protected - OAuth2.
  5. Control Center doesn’t check this secret when you save, so sign in to Search to make sure it works. Then 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 Shinydocs Pro server. 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.