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.

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 Administrator is removed, 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 write a file into 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. Take the path from the log. Every startup writes an Information line naming the full path of the file to create, whether or not the file exists. 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. Create a file named lockout-recovery.txt at that path. Only the presence of the file matters. Its contents are never read, so an empty file is enough.
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.
5. Delete lockout-recovery.txt. The cog disappears and recovery closes.

Neither opening nor closing needs a restart. The file is checked as the sign-in screen renders, so creating it opens recovery and deleting it closes recovery within a couple of seconds. That is the point of this route: on Windows, Reportworq normally runs as a service, so setting a process environment variable means editing the service definition and restarting the service twice, once to open recovery and once to close it again, at exactly the moment someone is locked out of their own instance.

The installation directory is the folder holding the running binaries, and on Windows that is not the install root. The Bootstrap Service starts the application from a versioned subfolder, so the path is of the form C:\Program Files\Reportworq 6\Versions\v6.0.0.0, not C:\Program Files\Reportworq 6, and it changes when you update. Take it from the log line rather than typing it from memory.

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 created the file and no cog appeared, the likeliest cause is that it is not in the folder the log named.

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.
• Nothing closes it for you. The file is never deleted automatically and the variable never expires, because a recovery that timed itself out would strand the administrator it exists for. Closing it is a deliberate step: delete the file, or restart 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 write a file into 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.