Configure Shinydocs Pro Control Center for OpenText Content Server (OTCS)

OAuth 2

Prepare

This setup uses OTDS as your broker to your OIDC provider, meaning Shinydocs Search will authenticate against OTDS via OIDC and OAUTH 2.

If you do not have this setup configured in your organization already, please KB0797287 from OpenText for more information. This will need to be completed before proceeding. Please contact OpenText support for more information/assistance.

OTDS Configuration

This section documents how to setup OTDS to be an OAuth client for Integrated search, so users can connect and search against Content Server.

1. Login to the OTDS Admin portal.

2. In the side bar click on OAuth Clients to add a new OAuth client.

   

3. Click the Add Button to add a new OAuth Client

4. General Section - fill in the following fields

   • Client Id - This is an arbitrary name, however it should be unique and descriptive.

   • Display Name - This is an arbitrary name, however it also should be unique and descriptive

   • Confidential should be checked.

   • Authentication Method should be Client Secret

     

5. User Partition - fill in the following fields

   • Global or User Partition. - If all your users are from the provided OAuth source, you can select Global. However, if you have a mix of authentication sources, all different, you may want to restrict it to the user partition from the source you wish to use. If so, specify the partition name in the User Partition. In the screenshot below, the partition setup for users from Entra Id is called entraid.

     

6. Advanced - fill in the following fields

   • Grant Refresh Token - checked

   • Permissible Scopes - openid

   • Default Scopes - openid

     

7. Redirect Urls - these are permitted redirect urls that OTDS will redirect to once the user is authorized.

   • This should be the hostname of the integrated search with the path /oauth/authorized on the end of the url: e.g. https://search.example.cloud:9701/oauth/authorized where search.example.cloud:9701 is the host that is running control center and integrated search.

8. Custom Attributes - nothing to fill in there

   

9. Click Save

   • Upon save, a popup will appear showing you the Generated Client Secret. Copy this value, and put it in a safe place. You will need this later to setup integrated search.

OTDS (via Kerberos)

Configure Shinydocs Search Service Account:

1. Account Requirements:

   • The "Shinydocs Control Center" process must run as a domain user account or a group-managed service account (GMSA). For more details on GMSA, refer to the Microsoft documentation.

     • Right-click Shinydocs Control Center in Windows Services > Properties.

     • Click the Log on tab and assign the service account to the service

     • Click OK

2. Grant Permissions to the Service Account:

   • Add the account to the local Administrators group on the server where Shinydocs Pro is installed.

     • Alternatively, configure the following specific permissions:

       • Read access to the server.

         • Add the account to the local "Users" group.

       • Full Control on the Shinydocs Search folder (default path: C:\Program Files\Shinydocs Professional\ControlCenter).

       • Read access to the Shinydocs Search service certificate (default certificate: localhost.localdomain).

Grant Certificate Permissions

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

2. Navigate to Certificates - Local Computer > Personal > Certificates.

3. Locate and select localhost.localdomain.

4. From the menu bar, choose Action > All Tasks > Manage Private Keys.

5. Click Add and select the service account.

6. Under "Allow", checkmark Read, then click Apply.

Active Directory User Setup

Configure Delegation

1. Open Active Directory Users and Computers.

2. Locate the Shinydocs Service Account.

3. Right-click the account and select Properties.

4. Go to the Delegation tab and:

   • Choose Trust this user for delegation to specified services only.

   • Select Use Kerberos only.

Add SPNs for Delegation

1. Click Add to open the delegation window.

2. Select Users or Computers and search for the target service account.

3. Add the required SPNs associated with the service.

4. Click Apply to save changes.

Setting Service Principal Names (SPNs)

SPN Configuration Steps

1. Open a command prompt or PowerShell with administrative rights.

2. Determine the hostnames of the Shinydocs Search servers:

   • For single-instance setups, use the machine hostname (e.g., search.example.local).

   • For load-balanced clusters, include all machine hostnames and the load balancer's DNS name (e.g., search01.example.local, search02.example.local, search.example.local).

3. Run the following commands to add SPNs:

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

   Repeat for each hostname.

Authorization to OTDS (SPNs)

Set SPNs for OTDS Hosts

Run either of the following commands for each OTDS-related hostname:

1. OTDS Hostname:

   setspn -S HTTP/<otdsHostName> <domain\service_account>
   

2. OTDS Fully Qualified Domain Name (FQDN):

   setspn -S HTTP/<otdsHostName.fqdn.com> <domain\service_account>
   

3. OTDS Load Balancer:

   setspn -S HTTP/<otdsloadbalancer> <domain\service_account>
   setspn -S HTTP/<otdsloadbalancer.fqdn.com> <domain\service_account>
   

Troubleshooting

• Kerberos logging can be enabled by editing the following registry key:
  HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters

Registry Value: LogLevel

Value Type: REG_DWORD

Value Data: 0x1

• Further details at: https://docs.microsoft.com/en-us/troubleshoot/windows-server/identity/enable-kerberos-event-logging

• The logging events will show in the System event log, in the Windows event viewer.

• Ensure the SPNs have been replicated through the domain.

• Ensure that the OTDS server is running as the content server user account created above, and negotiate authentication is enabled within OTDS.

• Review the OTDS logs, otds.log, directory_access.log for any errors during authentication.