DocuWare supports the OpenID Connect (OIDC) standard for single sign-on (SSO). Read these guidelines for connecting DocuWare to an OIDC identity provider.
Most professional identity providers support OIDC. But as it is an open standard, the configuration will differ depending on the identity provider.
You will probably need to set up an application within your identity provider to connect it to DocuWare. For more information, contact your identity provider.
Connect to an identity provider with OPEN ID
Go to DocuWare Configurations > General > Security > Single Sign on.
The following screenshot shows the SSO configuration dialog. Find explanations underneath.
.png)
Configure single sign-on connection
Specify the connection between the identity provider and DocuWare in the section of the dialog Configure single sign-on connection.
DocuWare and the external identity provider communicate via URLs: DocuWare addresses the identity provider via the Issuer URL and receives information back via the Callback URL.
You will get the Client ID and the Client Secret Key from your identity provider.
Attributes mapping
To enable DocuWare users to authenticate through an external identity provider, each user must be uniquely identifiable in both systems. Consequently, DocuWare and the identity provider must share a common set of user attributes.
Terms for “attribute” may vary
The term “attributes” is not defined in the OIDC standard; your identity provider may instead refer to them as “claims,” “properties,” or something similar. Attribute names can also vary—for example, DocuWare’s “username” might appear as “userID” at the identity provider. Because of these differences, be sure to configure and test the mapping carefully.
Enable the option Automatically link existing users at login to ensure that attribute mapping works correctly. Disable it only if you are using DocuWare User Synchronization 2 in a non-standard setup.
Scopes
OIDC is built on OAuth 2.0. Select the OAuth 2.0 scopes that will supply the attributes DocuWare needs. In most cases the default scopes, openid and profile, are sufficient.
If you enable Additional claims provided by the UserInfo endpoint, DocuWare will also retrieve any attributes returned by that endpoint.
Using the UserInfo endpoint slows down the login process, so activate it only if the required attributes are not available through the profile or email scopes.
DocuWare uses the email address as the primary key for matching users with the identity provider. Ensure that every user has an email address in both systems. In your identity provider, an attribute (e.g., “email”) already holds this value.
Enter the exact name of that attribute here so DocuWare can retrieve the address and link the external user to the corresponding DocuWare user.
Username
Select the attribute that DocuWare should use as the username. This value must uniquely identify the user in the external directory and must exactly match the existing DocuWare username.
External ID
If your identity provider supplies a unique ID for every user, select the attribute that contains this value. A dedicated external ID speeds up the mapping process and increases security.
If no separate ID exists, choose any other attribute that is unique for each user—such as the e-mail address, username, or userID.
External Provider ID
Specify an identifier that is unique to the identity-provider instance itself. This is required only when you operate multiple instances of the same provider.
Test
Click the button Test to verify the SSO connection. Always run this test after you save any changes.
Enforce single sign-on
This setting controls whether users can still sign in with their DocuWare credentials or must authenticate exclusively through the external identity provider (IdP).
Disabled: Users may choose either method—DocuWare username/password or the external Identity Provider.
Enabled: All users must authenticate via the external identity provider. DocuWare credentials are blocked unless the user or role is added to the exclusion list. Administrators can use this list to let specific accounts bypass SSO.
Note: Test the SSO setup thoroughly before enforcing it. If the connection fails, every user—including organization administrators—could be locked out.
How-to guide for a safe rollout of Enforce Single Sign-On
When you as an administrator configure Signle sign-on (SSO) in DocuWare you have two options to roll the feature out to the users:
Optional SSO – Users may sign in with their DocuWare username/password or via SSO.
Enforced SSO – Activate Enforce single sign-on authentication for all users. Users must authenticate through the external identity provider (IdP) unless they belong to an exclusion list.
Follow the three steps below to activate enforced SSO:
Step 1 – Enable SSO and test it
1. In DocuWare Configurations > Security, set up your identity provider. But leave “Enforce SSO” unchecked for now.
2. Ask several internal users to log in via SSO to confirm the setup.
3. If you import users with DocuWare User Sync or User Provisioning, verify those accounts can also log in via SSO.
4. Ensure every organization administrator can authenticate via SSO. Keep at least one admin in mind for the exclusion list (see Step 2).
Step 2 – Identify accounts to exclude
Typical accounts for exclusions are
• External users (e.g., partners or customers) not managed by the IdP
• Service accounts used by external applications
• Accounts running internal DocuWare jobs (not required from DocuWare 7.13 onward)
• Any other accounts that must stay password-based (e.g., no internet access)
How to find them:
1. Go to DocuWare Configurations > User Management and click Export users as CSV.
2. Open the file in Excel and look for e-mail domains outside your company; these are likely external users.
3. Review integrations and workflows to locate service accounts.
Step 3 – Roll out enforced SSO
1. Enable Enforce single sign-on authentication for all users.
2. Add all users or roles to the exclusion list so nobody is locked out.
3. Over the next days or weeks, remove exclusions in stages, confirming each group can log in via SSO.
4. When finished, leave only the accounts identified in Step 2 on the exclusion list.
5. Keep at least one administrator account excluded as a safety net.
Always test the SSO connection after any change. If the IdP becomes unavailable and no exclusions exist, all users—including admins—could be locked out.