OIDC_IDENTITY_REJECTED: unable to determine Stable OIDC subject when using Tinyauth

[kuzabi]

Hello,
I am trying to integrate WebSSH with Tinyauth as an OIDC provider, but I cannot complete the login process because WebSSH requires a Stable OIDC subject to link the external identity to an existing local account.

The OIDC discovery endpoint is reachable and TLS verification works correctly. The login flow redirects to Tinyauth, authentication succeeds, and the browser returns to WebSSH. However, WebSSH rejects the identity with:
2026-09-07T19:18:26.367Z [webssh] ⚠️ [19:18:26] OIDC_IDENTITY_REJECTED | ip=192.xxxxx | issuer=https://auth.example.home | reason=unlinked_or_locked
I understand that WebSSH links identities using:
issuer + sub → local WebSSH account
However, I am unable to determine the exact sub claim generated by Tinyauth for the WebSSH OIDC client. I tried to inspect the browser/network traffic and container logs, but the token is not exposed there. The WebSSH log only reports unlinked_or_locked.
WebSSH configuration

environment:
DEPLOYMENT_PROFILE: homelab
CORS_ORIGINS: https://ssh.example.home
TRUSTED_PROXIES: "1"
SESSION_COOKIE_SECURE: "true"
OIDC_ENABLED: "true"
OIDC_ISSUER: https://auth.example.home
OIDC_CLIENT_ID: <clinetid same webssh&tinyauth>
OIDC_CLIENT_SECRET_FILE: /run/secrets/webssh_oidc_client_secret
OIDC_REDIRECT_URI: https://ssh.example.home/oidc/callback

The OIDC client is configured in Tinyauth with:

oidc:
clients:
webssh:
clientId: <clinetid same webssh&tinyauth>
clientSecret:
trustedRedirectUris:
- https://ssh.example.home/oidc/callback
name: WebSSH

The Tinyauth user is:

username: user1
email:
There is an active local WebSSH account named user1.

How can I obtain or display the exact OIDC sub claim received by WebSSH?
Is there a CLI command, admin action, or debug endpoint that can show the external issuer and subject before linking the identity?
Can WebSSH provide more detailed OIDC debug logging, for example:

• whether discovery succeeded;
• whether the authorization code was exchanged successfully;
• the received iss;
• the received sub;
• the selected local account;
• the exact reason why the identity was considered unlinked?
  Is unlinked_or_locked caused by the missing identity mapping only, or could it also indicate a locked/inactive local account?

For security reasons, I do not expect the complete token or client secret to be logged. A redacted diagnostic such as the following would be sufficient:

• OIDC identity received:
• issuer=https://auth.example.home
• subject=
• email=
• linked_account=none
• reason=unlinked

[bifrost0x]

Thanks for the detailed report. Your understanding is correct, and this is not a configuration misunderstanding on your side.

The OIDC_IDENTITY_REJECTED event shown here is reached only after WebSSH has consumed the login state, exchanged the authorization code, obtained the claims, and accepted a non-empty sub with the configured issuer and any subject/domain policy. In other words, discovery and the OIDC callback are working; the failure is at the local identity-mapping step.

WebSSH deliberately does not match an OIDC identity to a local account by username or email. Only the exact (issuer, sub) pair is trusted, because usernames and email addresses can change or be reassigned. The current unlinked_or_locked reason combines three internal cases:

• no exact identity mapping exists;
• the mapped local account is locked; or
• the mapped account is LDAP-managed.

There is no separate inactive-account state. Given your active local account and first-time setup, a missing mapping is the expected cause.

For an immediate Tinyauth workaround, please first confirm the exact Tinyauth version. With Tinyauth 5.1.0 and newer, including 5.2.0, the subject is a UUIDv5 in the URL namespace generated from the resolved Tinyauth username and the exact OIDC clientId:

python3 -c 'import uuid; print(uuid.uuid5(uuid.NAMESPACE_URL, "user1:YOUR_EXACT_CLIENT_ID"))'

Enter the resulting UUID in WebSSH under Admin → Users → user1 → Manage OIDC → Stable OIDC subject. WebSSH supplies the configured issuer automatically.

Tinyauth 5.0.7 used the configured client map key instead of the actual client ID, so for the YAML shown above its input would be user1:webssh. This is why the exact Tinyauth version matters. Please do not post the client secret or any token here.

We also agree that requiring the raw subject without providing a safe way to obtain it is an incomplete enrollment experience in WebSSH. We are starting work on a clean fix now. The intended direction is an authenticated, action-bound Link via OIDC flow that receives and links the validated (issuer, sub) directly, without auto-linking by username/email and without logging tokens or raw subjects. We will also separate the operator-visible rejection reasons while keeping the public authentication error generic to avoid account-state disclosure.

We will update this issue with the pull request and validation results.

[bifrost0x]

Implemented in #209.

The PR adds the safe self-service enrollment path discussed above:

• signed-in local users can link the configured provider from Settings after an action-bound account step-up;
• WebSSH stores only the provider-validated (issuer, sub) pair; username/email auto-linking remains disabled;
• the one-use link intent is bound to the browser session, user, authentication generation, and exact server-side authentication session;
• logout, lockout, authentication invalidation, identity collisions, and provider claim mismatches fail closed;
• operator diagnostics now distinguish unlinked, account_locked, and externally_managed, while the public response remains generic;
• root and APPLICATION_ROOT subfolder deployments are covered.

Compatibility: the database migration is additive and nullable on the short-lived OIDC state table. Existing users, existing OIDC mappings, and existing login and step-up flows are unchanged. Manual admin linking remains available.

Validation on the final commit includes all required GitHub Actions checks, CI pytest (2787 passed, 2 skipped), both browser shards, CodeQL, integration tests, and container image security scans. Local validation additionally covered the complete Python suite (2779 passed, 29 skipped), Node tests (40 passed), focused OIDC route security boundaries (39 passed), the application-root regression suite, and the new linked-identity Settings browser flow.

Until #209 is merged, the Tinyauth UUIDv5/manual-admin workaround from the earlier comment remains the current-release path.

[bifrost0x]

Final implementation update for #209 (current head 484b8d4).

The additional compatibility pass is complete:

• OIDC account and administrator Step-up return URLs are now generated by the server, so both root deployments and APPLICATION_ROOT subfolder deployments return to the correct Settings or Admin page. A browser-supplied continuation is ignored.
• The Settings frontend uses the existing security-confirmation flow, shows the linked OIDC method consistently, and redirects to the provider only after the action-bound confirmation succeeds.
• The OIDC, authentication overview, and account-management documentation now describe self-service linking, the LDAP/GitHub exclusions, operator diagnostics, upgrade behavior, and the administrator recovery fallback.
• The migration remains additive and nullable. A regression test creates a real pre-upgrade in-flight OIDC login state, runs the migration twice, and verifies that the new service can still consume it. Existing users, existing OIDC mappings, login/Step-up flows, and manual administrator link/unlink remain compatible.
• Subject and email-domain policies, locked/expired/external-account states, provider navigation, identity collisions, and application-root behavior are covered explicitly.

No new environment variable, callback URI, or provider registration is required.

Validation on the exact current commit is complete: all required GitHub Actions checks pass, including CI pytest (2796 passed, 2 skipped), Python 3.11, both browser shards, Redis 7/8, SSH and SMB integration, CodeQL, container threading, and AMD64/ARM64 image security. Local validation also passed the full Python suite (2796 passed, 2 skipped), all 40 Node tests, and the complete six-test OIDC/Admin browser suite. The final Codex review found no major issues, and all review threads are resolved.

The pull request is still open and has not been merged or released. Until it is merged and included in a release, the manual administrator-link workaround from the first reply remains the path for current installations.

[kuzabi]

Thanks, your workaround:
python3 -c 'import uuid; print(uuid.uuid5(uuid.NAMESPACE_URL, "user1:YOUR_EXACT_CLIENT_ID"))'
works like a charm, and looks like true magic. :)