Skip to main content

DocuShare Flex: Configuring Microsoft Entra ID SAML Single Sign-On

Updated

DocuShare Flex: Configuring Microsoft Entra ID SAML Single Sign-On

Overview

DocuShare Flex supports Microsoft Entra ID (formerly Azure AD) as a SAML 2.0 identity provider.

This allows users to authenticate to DocuShare Flex using their organization credentials instead of a separate DocuShare password.

This article provides the recommended configuration procedure and the key checks to complete before enabling SAML in production.

Prerequisites

  • DocuShare Flex is installed and available over HTTPS.
  • You have administrative access to both the DocuShare Flex site (Coordinator Role) and the Microsoft Entra ID tenant.
  • The users or groups who will use SAML are assigned to the Entra application.
  • The DocuShare Flex hostname and context path are known and validated.

Important Guidance

Use the values shown on the live DocuShare SAML Configuration page as the source of truth for the Service Provider configuration.

The Service Provider values should match the actual DocuShare host, port, and context root for the tenant.

Do not manually guess the URLs when a valid tenant-specific value is available in the product UI.

Typical Service Provider Values

  • Entity ID: https://{host}:{port}/docushare
  • Assertion Consumer Service URL: https://{host}:{port}/docushare/dsweb/ApplySAMLLogin
  • Sign-on URL: https://{host}:{port}/docushare/dsweb/HomePage
  • Logout URL: https://{host}:{port}/docushare/dsweb/ApplySAMLLogout

Procedure

1. Register the application in Microsoft Entra ID

  • Sign in to the Microsoft Entra admin center.
  • Open Enterprise applications.
  • Select New application > Create your own application.
  • Enter a name for the application, such as DocuShare Flex SSO.
  • Select the non-gallery option and click Create.
  • After the app is created, open it and select Single sign-on.
  • Select SAML.

2. Configure the Basic SAML settings

  • Enter the Identifier (Entity ID) for the DocuShare Service Provider.
  • Enter the Reply URL (Assertion Consumer Service URL).
  • Enter the Sign on URL.
  • Save the configuration.

3. Configure the claims

Recommended claim mappings include:

  • Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Username: the claim that matches the DocuShare username for the user
  • First name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • Last name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

 

The claim names must match the values actually returned in the SAML assertion. If the username mapping is incorrect, the user will fail authentication.

4. Download the certificate

  • In the Microsoft Entra application, open the SAML configuration page.
  • Download the certificate in Base64 format.
  • Copy the certificate content without the BEGIN CERTIFICATE and END CERTIFICATE lines.
  • Paste the Base64 content into the IdP certificate field in DocuShare Flex.

5. Assign users or groups

Before SAML login works, assign the appropriate users or security groups to the enterprise application in Entra ID.

This can be done individually or by group-based access control depending on the organization policy.

6. Configure SAML in DocuShare Flex

  • Sign in to DocuShare Flex as an administrator.
  • Navigate to Administration > Services > SAML Configuration.
  • Enable SAML.
  • Enter the IdP Entity ID, IdP Single Sign-On Service URL, and IdP certificate values collected from Entra ID.
  • Configure the Email Mapping and Username Mapping fields.
  • If automatic onboarding is being used, configure the first name, last name, and default user level mapping.
  • Click Test Connection.
  • Sign in using an assigned Entra ID test account when prompted.
  • If the test is successful, click Apply to save the configuration.

DocuShare Flex requires the SAML configuration to be verified with a live test before it can be saved in the enabled state.

7. Verify successful login

  • Open a new browser session or private browsing window.
  • Navigate to the DocuShare Flex home page.
  • Confirm the user is redirected to the Entra ID sign-in page.
  • Sign in with an assigned Entra ID account.
  • Confirm the user is redirected back to DocuShare Flex and is successfully authenticated.

Automatic Onboarding

Automatic onboarding is optional and allows a user who does not yet exist in DocuShare Flex to be created on first successful SAML sign-in.

This option requires mappings for email, username, first name, and last name.

Only enable this option if your organization is comfortable with on-demand user provisioning.

Troubleshooting

Users are redirected to Entra ID but cannot sign in

  • SAML is enabled in DocuShare Flex.
  • The IdP certificate matches the current Entra certificate.
  • The IdP Entity ID and Single Sign-On URL are correct.
  • The user is assigned to the Entra enterprise application.
  • The username and email claim values match the content of the SAML assertion.

Login fails with an attribute-mapping error

  • Confirm the exact names of the attributes in the SAML assertion.
  • Update the DocuShare mapping to match the actual attribute names.
  • Verify that the username and email claim values are present in the assertion.

SAML will not save in enabled mode

  • Repeat the Test Connection step.
  • Verify the login completes successfully before applying the changes.
  • Ensure the user being tested is assigned to the Entra enterprise application.

Best Practices

  • Use the values on the live DocuShare SAML Configuration page as the source of truth.
  • Validate all URLs against the actual Flex host and context root.
  • Keep the certificate current and refresh it whenever the Entra application certificate changes.
  • Test with a real user account assigned to the enterprise application before moving to production.

Validation

This article was reviewed against the SAML configuration logic and product source available in the DocuShare workspace.

The verified implementation confirms that the Service Provider values are derived from the current DocuShare URL and context root, that a live verification is required before enabling SAML, and that claim mappings must match the actual values returned by the identity provider.

The original PDF reviewed during this task was directionally useful, but it included example URLs that are not fully consistent with the validated DocuShare Flex implementation.