| Audience: DocuShare administrators |
Configure SAML Single Sign-On in DocuShare 8.1
Applies To
DocuShare 8.1. This article covers SAML authentication modes and configuration behavior for DocuShare Server 8.1. Earlier releases may differ. This article does not describe DocuShare Flex configuration.
Overview
DocuShare supports SAML 2.0 single sign-on (SSO), allowing users to authenticate through an identity provider (IdP), such as Microsoft Entra ID, Okta, or Active Directory Federation Services (AD FS), rather than entering a separate DocuShare password.
Before enabling SAML, decide how users will authenticate, prepare the IdP application, and make sure at least one Site Administrator can sign in through the IdP. In DocuShare 8.1, a successful Verify Connection saves the IdP settings and attribute mappings; select Apply to enable SAML.
Before You Begin
- Confirm that the DocuShare site is reachable at its intended URL. HTTPS is strongly recommended because SAML assertions contain identity information.
- Arrange for an IdP administrator to create or update the SAML application for DocuShare.
- Identify at least one user who will belong to the DocuShare Site Administrators group and will be assigned to the IdP application. Once SAML is enabled, standard administrator login is disabled; if no SAML-authenticated user belongs to the Site Administrators group, administrators can be locked out.
- Decide whether all users will sign in through the IdP or whether selected non-administrator users and service accounts also need DocuShare form login.
- Confirm that user accounts already exist in DocuShare, or decide whether to enable automatic onboarding where available.
Configure SAML
1. Open the SAML Configuration page
a. Sign in to DocuShare as an administrator.
b. Open Administration Menu > Services and Components > SAML Configuration.
c. Review the Service Provider (SP) information shown on the page. Copy these values to the IdP configuration; do not guess or manually construct the URLs. The values depend on the DocuShare URL, host, port, and context root.
2. Configure the DocuShare application in your IdP
In the IdP, create or configure a SAML 2.0 application for DocuShare using the SP values displayed on the DocuShare SAML Configuration page. Configure the IdP to send the identity attributes DocuShare will use, and make the IdP signing certificate and IdP service information available to the DocuShare administrator.
In Microsoft Entra ID, assign the users or groups who will sign in to the enterprise application. For another IdP, follow its procedure for configuring a SAML service provider.
3. Enable SAML and choose an authentication mode
In DocuShare 8.1, select Enable SAML and choose an Authentication Mode:
- SAML Only: Users who need to authenticate are redirected to the IdP automatically.
- Mixed: Users are not redirected automatically; the DocuShare sign-in page offers single sign-on. By default, all users must sign in through the IdP. You can grant DS Form Login Access to specific non-administrator users or groups who also need to sign in through the DocuShare form.
If service accounts need to access the DocuShare API using Basic Authentication, enable Allow Basic Authentication Override for SAML for each applicable account in Account Management. Availability and behavior may depend on your site configuration and authentication mode; confirm them on your DocuShare 8.1 server before relying on the override. DS Form Login Access, available only in Mixed mode, is the separate setting for signing in through the DocuShare form in a browser. Use the override only for accounts that require it. Site, Content, and Account Administrators cannot be added to an override list; they must sign in through SSO.
4. Enter IdP information and map attributes
Enter the IdP information requested on the DocuShare SAML Configuration page, including the IdP Entity ID, Single Sign-On service URL, and signing certificate. If your IdP provides a metadata URL, select Retrieve from Metadata URL to populate available fields, then review the values. Enter a Single Logout URL if your IdP supports single logout and you plan to use it. Map the IdP attributes that provide the user's Email, Username, First Name, and Last Name values to DocuShare. First Name and Last Name are required when automatic onboarding is enabled.
The attribute names and values in DocuShare must match what the IdP actually sends in the SAML assertion. The asserted username must match the user's Username in DocuShare. If these values do not match, authentication can fail or DocuShare may not find the user.
5. Optionally enable automatic onboarding
Where available, Enable Automatic Onboarding of Users allows DocuShare to create an account after the user's first successful SAML sign-in when no matching account exists. The IdP must send the First Name and Last Name attributes mapped in step 4; if either is missing, sign-in fails. User levels available for new accounts depend on your site license. Review the available levels and the default shown on the page, then select a level that matches your organization's access policy. After creation, access is governed by DocuShare collection and document permissions as it is for other users.
Enable automatic onboarding only if your organization intends to provision accounts this way and has confirmed that the default user level shown on the page matches its access policy.
6. Verify and save the configuration
a. Confirm that the IdP application, user or group assignment, certificate, service URLs, and attribute mappings are complete.
b. Click Verify Connection and complete a sign-in test with an assigned IdP test user.
c. Confirm that the test succeeds, then click Apply to enable SAML and save the configuration. A successful Verify Connection saves the IdP settings and attribute mappings, but SAML is not enabled until you click Apply.
d. Test sign-in in a separate browser session with representative users. Confirm that administrators can reach Admin Home and that any approved Mixed-mode users can use the DocuShare form login.
If Administrators Are Locked Out
Before enabling SAML, make sure at least one user in the IdP is assigned to DocuShare and belongs to the Site Administrators group. If a misconfiguration prevents administrators from signing in, run the recovery script from the bin folder in the DocuShare installation directory:
- Windows: disableSAML.bat
- Linux: disableSAML.sh
The script disables SAML and restores DocuShare form login so an administrator can sign in and correct the configuration.
Troubleshooting
- The user is not redirected to the IdP: Confirm SAML is enabled, the DocuShare URL is correct, and the user's account or group is assigned in the IdP application.
- The IdP sign-in succeeds but DocuShare rejects the user: Confirm the IdP Entity ID, Single Sign-On service URL, signing certificate, and attribute mappings (Email and Username, plus First Name and Last Name when automatic onboarding is enabled). Verify that the asserted Username exactly matches the DocuShare Username.
- The configuration cannot be saved as enabled: In DocuShare 8.1, complete a successful Verify Connection test before clicking Apply.
- The user returns from the IdP but cannot reach the DocuShare home page: For DocuShare 8.1, see Use SameSite=Lax for SAML Sign-In.
- The administrator cannot sign in after SAML is enabled: Use the disableSAML.bat or disableSAML.sh recovery script described above.