Skip to content

docs: oauth2 sso enforcement #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
secana merged 2 commits into from
Sep 23, 2026
Merged

docs: oauth2 sso enforcement #68

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a563de
docs: document OAuth2 SSO enforcement and RP-initiated logout
secana Sep 23, 2026
56e6364
docs: note the post-logout redirect prefix and the ID token cookie limit
secana Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions src/views/DocumentationV6View.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -892,6 +892,12 @@ const mobileNavOpen = ref(false);
description="Group name that grants read-only access (e.g., 'kellnr-readonly')." />
<ConfigCard title="Button Text" toml="[oauth2] button_text" env-var="KELLNR_OAUTH2__BUTTON_TEXT"
default-value="Login with SSO" description="Text displayed on the OAuth2 login button in the web UI." />
<ConfigCard title="Enforced" toml="[oauth2] enforced" env-var="KELLNR_OAUTH2__ENFORCED"
default-value="false"
description="Make SSO the only way to log in. Disables password login, password changes and resets, and local user creation. Requires enabled." />
<ConfigCard title="Auto Redirect" toml="[oauth2] auto_redirect"
env-var="KELLNR_OAUTH2__AUTO_REDIRECT" default-value="false"
description="Skip the login page and send users straight to the identity provider. Requires enforced." />
</ConfigGrid>

<MinorHeader id="config-toolchain-values">Toolchain Server</MinorHeader>
Expand Down Expand Up @@ -954,6 +960,8 @@ const mobileNavOpen = ref(false);
<li>Automatic user provisioning on first login</li>
<li>Group-based admin and read-only role assignment</li>
<li>Customizable login button text</li>
<li>Optional SSO-only mode that disables password login entirely</li>
<li>RP-initiated logout, ending the session at the identity provider as well</li>
</ul>
</TextBlock>

Expand Down Expand Up @@ -1041,6 +1049,88 @@ const mobileNavOpen = ref(false);
read_only_group_value = "kellnr-readonly"
</CodeBlock>

<TextBlock>
<b>SSO-Only Login</b><br />
By default, the SSO button sits next to the username and password form, so both login methods stay
available. Set <i>enforced</i> to make SSO the only way in:
</TextBlock>

<CodeBlock lang="toml">
[oauth2]
enabled = true
enforced = true
</CodeBlock>

<TextBlock>
With enforcement on, Kellnr rejects every path that relies on a local password:
<ul>
<li>The login endpoint refuses username and password credentials</li>
<li>Changing your own password and resetting another user's password are refused</li>
<li>Creating a local user is refused, since users come from the identity provider</li>
<li>HTTP Basic authentication against the registry API is refused</li>
</ul>
The web UI hides the matching forms and buttons, so the password form, the Change Password tab, the
Add User form and the password reset action disappear.<br />
<br />
Cargo API tokens are unaffected. They are independent of how a user logs in, so
<code>cargo publish</code> and <code>cargo add</code> keep working exactly as before.
</TextBlock>

<WarnBlock>
Configure <i>admin_group_claim</i> and <i>admin_group_value</i> before enabling <i>enforced</i> on a
fresh instance. The local admin account can no longer log in, and without a group mapping no user
provisioned through SSO is ever promoted, which leaves the instance without an administrator. Kellnr
logs a warning at startup when it detects this combination.
</WarnBlock>

<TextBlock>
Kellnr also refuses to start when <i>enforced</i> is set but the OIDC handler cannot be initialized,
for example because the provider is unreachable or the issuer URL is malformed. Starting anyway would
serve a registry that nobody can log into, so the process exits with status code 1 and logs the reason
instead.
</TextBlock>

<TextBlock>
<b>Skipping the Login Page</b><br />
Once SSO is the only login method, the login page holds a single button. Set <i>auto_redirect</i> to
send users straight to the identity provider instead:
</TextBlock>

<CodeBlock lang="toml">
[oauth2]
enabled = true
enforced = true
auto_redirect = true
</CodeBlock>

<TextBlock>
<i>auto_redirect</i> requires <i>enforced</i>, and <i>enforced</i> requires <i>enabled</i>. Kellnr
rejects a configuration that sets one without the other, rather than silently disabling all login.
</TextBlock>

<TextBlock>
<b>Logout</b><br />
When your provider advertises an <i>end_session_endpoint</i> in its discovery document (RP-Initiated
Logout 1.0), logging out of Kellnr also ends the session at the provider. Kellnr redirects the browser
to that endpoint with the ID token as <i>id_token_hint</i>, and the provider redirects back to Kellnr
afterwards. Add your Kellnr URL to the provider's list of allowed post-logout redirect URIs, otherwise
the provider refuses the redirect:
<ul>
<li><i>https://your-kellnr-host/</i></li>
<li><i>https://your-kellnr-host/your-prefix/</i> when <i>origin.path</i> is set</li>
</ul>
Providers without an <i>end_session_endpoint</i> only have the local Kellnr session cleared, so the
provider may sign the user straight back in on the next login attempt.
</TextBlock>

<TextBlock>
Kellnr keeps the ID token in a cookie to pass it back as <i>id_token_hint</i>. Browsers cap a single
cookie at roughly 4 KB, so a very large ID token, typically one carrying many group memberships, is
dropped and the provider session is no longer ended on logout. The local Kellnr session is still
cleared, so the only visible symptom is that the provider signs the user straight back in. If you hit
this, trim the claims your provider puts in the ID token.
</TextBlock>

<WarnBlock>
The client secret should be kept confidential. It is recommended to set it via the
<i>KELLNR_OAUTH2__CLIENT_SECRET</i> environment variable rather than storing it in the config file.
Expand Down Expand Up @@ -1474,6 +1564,16 @@ const mobileNavOpen = ref(false);
<td>Enable OAuth2/OIDC authentication</td>
<td>false</td>
</tr>
<tr>
<td><code>--oauth2-enforced</code></td>
<td>Make SSO the only way to log in</td>
<td>false</td>
</tr>
<tr>
<td><code>--oauth2-auto-redirect</code></td>
<td>Skip the login page and redirect to the identity provider</td>
<td>false</td>
</tr>
</tbody>
</TableBlock>

Expand Down
Loading