Authentication
primedocs does not run a user directory with passwords of its own. Every sign-in goes through the bundled Identity Server (IdS), which is connected to the corporate directory (Entra ID or Active Directory). This page describes who signs in by which method and what the sign-in hands over to primedocs. The corresponding configuration is covered in the Installation section.
Authentication only establishes who signs in. Which data that person holds in primedocs (user fields, profile, organizational unit) is created afterwards by provisioning.
Two kinds of sign-in
| Kind | Who | Method |
|---|---|---|
| People | Users in primedocs Web, Desktop and the Office add-ins | OpenID Connect against the IdS, which forwards the sign-in to the directory |
| Systems | Third-party systems calling Connect, the Web API or the Admin API | OAuth 2.0 against the IdS, usually through client_credentials. The clients are registered in primedocs.config. See API Authentication |
| External administrators | Operations and support access for managing a datasource | A dedicated Entra ID app (<dataSourceAdminAppAuth>), alongside the sign-in of the regular users. These accounts are deliberately not created as users in the datasource. See Entra ID Apps |
In every case the IdS issues the access token, and the primedocs services have it validated by the IdS.
Authentication methods for people
For the sign-in of regular users, a primedocs instance runs in one of the two methods. What decides it is whether an <office365Auth> node is configured in primedocs.config:
| Method | Directory | Use | Configuration |
|---|---|---|---|
| Entra ID | Microsoft Entra ID (formerly Azure Active Directory) | Cloud and hybrid operation. A prerequisite for the Office and Teams add-ins | <office365Auth> in primedocs.config plus an Entra ID app |
| Windows authentication | Active Directory | Pure on-premises operation without Microsoft 365 | No <office365Auth>. Kerberos/Negotiate either directly or through the Windows host of the IdS. Prerequisites: Active Directory requirements |
What the sign-in supplies and what it does not
From the sign-in itself, primedocs takes the identity only:
| Item | Meaning |
|---|---|
| PrimarySid | The unique key of the person. With Active Directory this is the objectSid (format S-1-5-…), with Entra ID the objectId (a GUID). primedocs uses it to match the user record, see Users, Profiles and Organizations |
| Account name | The sign-in name from the token (UPN or preferred_username) |
The display name and the group memberships are not in the token. primedocs reads them from the directory itself after the sign-in (a separate access using the server's permissions, not part of the sign-in). From the group SIDs, primedocs then derives the permissions.
Where the groups come from
The chosen authentication method determines the source primedocs reads the display name and group memberships from. This is the point where authentication and data retrieval genuinely do connect:
| Authentication method | Source for display name and groups |
|---|---|
| Windows authentication | Active Directory via LDAP |
| Entra ID | Microsoft Graph |
| Entra ID with SCIM | The data supplied through SCIM (useful when no application permission may be granted for Microsoft Graph) |
Which directory property serves as the display name is configurable per source. SCIM can only be combined with Entra ID, not with Windows authentication.
From sign-in to user
After the sign-in, primedocs checks whether a user already exists in the datasource for that PrimarySid. If not, the user and a default profile are created automatically. The sequence is described in Provisioning. The details are in Onboarding & Offboarding.
Sign-in in primedocs Web and the web add-ins
primedocs Web signs in directly at the IdS using the Authorization Code with PKCE flow (OAuth 2.0 and OpenID Connect) and receives tokens in return. primedocs Web sends every call to the server with the access token as a bearer token. There is no cookie session between the browser and primedocs Web. The Office and Teams add-ins receive the same tokens, either through the sign-in page or silently through Nested App Authentication.
| Token | Validity |
|---|---|
| Access token | 8 hours. primedocs Web renews it in the background before it expires. |
| Refresh token | Replaced by a new one on every renewal (rotation). Valid for at most 30 days from the original sign-in, regardless of how actively primedocs is used. |
- Maximum sign-in duration: a new sign-in is required no later than 30 days after the sign-in.
- One session per sign-in: every sign-in, for example in the browser or in an Office add-in, forms a separate session at the IdS.
- Signing out: revokes all tokens of this session at the IdS, including refresh tokens that have already been replaced and tokens from a renewal running at the same time. Within the same browser, signing out also signs out the other primedocs Web tabs. Sessions of the same person on other devices remain active. The sign-in at the IdS and at Entra ID also remains active. So that primedocs does not sign the user in again automatically right away, the next sign-in shortly after signing out requires interaction (see SSO).
- Temporary disruptions: if the IdS cannot be reached during a renewal, the sign-in is kept and primedocs Web retries the renewal later. After the device has been in sleep mode, primedocs Web renews an expired access token before the next call. A new sign-in is only required once the IdS rejects the refresh token, for example after the 30 days have elapsed or after signing out.
On renewal, the IdS does not check again whether the account is still active in the directory (Entra ID or Active Directory). Disabling an account in the directory therefore does not end an existing sign-in in primedocs Web immediately. It remains usable for up to 30 days after the sign-in.
Automatic sign-in (SSO)
If a valid Entra ID session already exists on the workstation, primedocs signs users in without a login dialog. This applies to Desktop, Web and the Office and Teams add-ins. How it works, its prerequisites and the required app registration are described in Single Sign-On (SSO).
Further reading
- primedocs.config: configuration of authentication and of the API clients
- Single Sign-On (SSO): automatic sign-in across all clients
- API Authentication: obtaining tokens for third-party systems
- Provisioning: how user and organization data is created after sign-in
- Roles: how group memberships become permissions