Sign-in and SSO#

Sign-in is the gate in front of everything: a user authenticates before any Reportworq shell mounts. Reportworq ships with a Native username and password provider by default, and you can instead activate a single SSO / OIDC provider so users authenticate with corporate identity. Exactly one provider is active at a time.

When to use it. Set the provider once as an install or policy decision. Choose Native for a self-contained account store, or an OIDC provider (Microsoft Entra ID, Google, or Custom OIDC) to let users sign in with their existing corporate identity and inherit roles from identity-provider group membership.

Before you start#

• You need Administrator rights.
• The active provider is set in Settings ▸ Integrations ▸ Authentication. Changing it requires a service restart.
• For an OIDC provider you need its Client Id, Client Secret, and Tenant Id from the identity provider. For Microsoft Entra ID specifically, complete the Azure app registration first. See Microsoft 365 OAuth setup.

How native sign-in works#

The default Native provider shows a username field, a password field, and a Login button. It also handles, on the same surface, these self-service flows:

• First login prompts a newly created account to set an initial password before first use.
• Update Password lets a user change their password voluntarily.
• Password expired forces a change at sign-in.
• Reset password sets a new password from an emailed reset link.
• Forgot Password appears only when the email distributor exists and is enabled. If email is not configured, the action reports "Missing email configuration."

Native lockout and password-complexity rules are configured on the Native provider's inline editor in Settings ▸ Integrations ▸ Authentication.

Licenses are sold as named users. Each account is one person. Sharing a single login between several people violates the terms of service, and it also defeats the audit trail, since every action is recorded against the account that performed it. If several people need access, give each of them an account.

Switch to an OIDC provider (Entra, Google, or Custom)#

1. In Settings ▸ Integrations ▸ Authentication, open the provider you want and enter its fields:
   • Microsoft Entra ID: Client Id, Client Secret, Tenant Id.
   • Google: Client Id, Client Secret, and optionally Tenant Id.
   • Custom OIDC: Client Id, Client Secret, Tenant Id, plus the Authority URI and each claim name (User-ID, Email, Role, Name) and one or more scopes, so it can point at an arbitrary identity provider.
2. Save. Every OIDC client secret is stored encrypted at rest.
3. Mark the provider Active and restart the service.

A restart is required. As noted in Before you start, changing the active provider takes effect only after you restart the service. Until you restart, the previous provider stays active.

Once active, group or role claims from the identity provider resolve to Reportworq entitlements, so you can assign a user's role through identity-provider group membership instead of a local grant.

Switching the active provider strands accounts on the previous provider. Changing the active provider does not simply drop permissions. The existing accounts stay bound to the previous identity provider and become reachable again only if you switch that provider back. Under the new provider, their entitlement and group grants must be re-established. Plan the cutover, because the old accounts are inaccessible while the new provider is active.

Before an Entra cutover, provision your way back in. Supply an initial administrator email that already exists in Entra ID, and confirm it resolves there first. Because the switch strands the old accounts, that pre-provisioned Entra administrator is how you get back in if the cutover locks everyone out. If even that fails, use the Recover from an administrator lockout procedure below.

When a sign-in fails, look in the server log for the cause. If a sign-in cannot complete - a mistyped client secret, an unreachable identity provider, or a declined consent - the user sees a friendly "We couldn't sign you in" page with a Return to sign-in button, not a technical error. This is deliberate: the real cause (including the provider's own error code) is never shown in the browser. To diagnose it, read the server log, where the full failure detail is recorded. A bad Entra client secret is the most common cause, and it is logged there in full.

The Excel add-in login#

The same native view handles the Excel and Office add-in sign-in. When the login state carries an Office cloud host, a successful sign-in posts the token back to the add-in's dialog host rather than navigating the shell, so the task pane connects without a separate browser session. HTTPS is required for the add-in.

Recover from an administrator lockout#

If every enabled Administrator is gone (Reportworq refuses to delete the last one, but disabling it or removing its role is allowed, and Security then shows a No System Administrator banner), or the active provider is misconfigured so no one can sign in, you can recover without a password. Recovery opens the pre-login Administration Settings surface, where you can repair the web-server configuration and re-establish an administrator account.

Recovery is deliberately operator-driven, and it cannot be gated behind a login. The person it exists for cannot authenticate; being locked out is the state it serves. So it is gated instead on proof that you control the server: either you rename a file in the installation directory, or you restart the process with an environment variable set. Neither is something a browser can do.

There are two ways to open it, and both are supported:

Open recovery with a file#

1. Find the file. The installation folder holds a file named lockout-recovery.txt.xxx, which Reportworq creates at startup. Every startup also writes an Information line to the log naming the full path of that file. That line is there for exactly this moment: you are locked out of the screen that would have told you anything, and the installation directory is the one thing you cannot work out from the outside.
2. Rename lockout-recovery.txt.xxx to lockout-recovery.txt. Do this while Reportworq is running; no restart is needed. Only the presence of the file matters and its contents are never read, so if the .xxx file is missing you can create an empty lockout-recovery.txt instead.
3. Refresh the sign-in page. The logon screen now shows an Administration Settings cog. You can reach it from anywhere, not only from the server console.
4. Open it and recover. You can fix the web-server configuration (name, port, SSL) and reach Security to re-establish an administrator account or repair the active provider. Only system-scoped tabs exist in this state, because no workspace provider is loaded. The Authentication tab saves only the providers you changed, and if one of them was removed from Settings ▸ Integrations, Reportworq says so and asks you to add it back there before saving. The recovery screen also hosts Settings ▸ Integrations, including each integration's Availability: an existing integration with no saved setting shows All Workspaces, and a new one starts with no workspace selected, so choose the workspaces it should serve. Changing the port or SSL restarts Reportworq, and the restart closes recovery: rename the file to lockout-recovery.txt again to carry on.
5. Rename the file back to lockout-recovery.txt.xxx (or delete it). The cog disappears and recovery closes.

Opening needs no restart, and recovery turns itself off. The file is checked as the sign-in screen renders, so renaming it opens recovery within a couple of seconds. If you forget to close it, Reportworq renames it back to lockout-recovery.txt.xxx itself after about an hour, and at the next restart. If it switches itself off before you have finished, rename it again.

A restart closes recovery. Do not create the file and then restart the service to pick it up: startup switches the file off. Rename it while the service is running instead. That is the point of this route: on Windows, Reportworq normally runs as a service, and setting a process environment variable means editing the service definition and restarting it, at exactly the moment someone is locked out of their own instance.

The installation directory is the install root - C:\Program Files\Reportworq 6 on a default Windows install - not the versioned Versions\v6.0.0.0 subfolder the application actually runs from. It stays the same when you update, so a path you are given once keeps working across upgrades. Take the exact path from the log line rather than typing it from memory, since a custom or non-Windows install can place the root elsewhere.

Nowhere else works. Only that one folder is checked. A copy of the file at the drive root, in the Repository, or in any other folder does nothing at all, and each of those locations was considered and rejected on security grounds. If you renamed the file and no cog appeared, the likeliest cause is that it is not in the folder the log named, or that it still ends in .xxx (Windows Explorer hides known extensions by default, so check the full name).

Open recovery with an environment variable#

Use this route where the installation directory is read-only or ephemeral, such as a container image.

1. Restart Reportworq with RW_CONFIG_ACCESS=1 set in its environment.
2. Browse to the instance. As with the file route, you can do this from anywhere. The logon screen shows the Administration Settings cog.
3. Open it and recover, exactly as in the file route above.
4. Restart again without the variable. This gate stays open until the process restarts without it.

While recovery is open#

• The pre-login administration shell is reachable by anyone who can reach the instance, not only by someone at the server console. Recovery is a whole-instance switch, not a local one.
• The file route closes itself; the variable does not. Reportworq renames lockout-recovery.txt back to lockout-recovery.txt.xxx after about an hour and at every restart, so a forgotten file cannot leave the instance open. RW_CONFIG_ACCESS=1 never expires: close it by restarting without the variable.
• The instance says so in its log. Reportworq logs a warning when recovery opens, repeats a standing reminder while it stays open, and logs a line when it closes. An instance somebody opened for a five-minute repair and forgot to close is visible in the log rather than silent.

Recover, then close it. This is also why keeping at least one Administrator, and provisioning an Entra way-back-in before a cutover, both matter: either route needs someone with access to the server itself, to rename a file in the installation directory or to restart the service.

Notes and limits#

• Only one provider is active at a time.
• Sign-in itself grants nothing. Role and per-item access are governed after sign-in by workspace security. See Roles and what you can do.
• A user with no workspace access cannot enter a shell. Membership of at least one workspace is required to log in. See Workspaces.
• Native is the only provider with self-service password flows.

Going deeper. To release a license seat immediately after removing a claims-based role, clear the account's "Last Claims." See Accounts, groups, and entitlements.