Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Make OIDC setup order and access checks usable

pulse-triage[bot]0e021c5cb850
diff --git a/docs/OIDC.md b/docs/OIDC.md
index e671f5fe98..898eadda34 100644
--- a/docs/OIDC.md
+++ b/docs/OIDC.md
@@ -4,16 +4,43 @@ Enable Single Sign-On (SSO) with providers like Authentik, Keycloak, Okta, and M
## πŸš€ Quick Start
-1. **Configure Provider**: Create an OIDC application in your IdP.
- - **Redirect URI**: `https://<your-pulse-domain>/api/oidc/<provider-id>/callback`
- - **Scopes**: `openid`, `profile`, `email`
-2. **Enable in Pulse**: Go to **Settings β†’ Security β†’ Single Sign-On**.
-3. **Enter Details**:
- - **Issuer URL**: The base URL of your IdP (e.g., `https://auth.example.com/application/o/pulse/`).
- - **Client ID & Secret**: From your IdP.
-4. **Save**: The login page will now show your configured SSO provider button(s).
-
-> **Tip**: To hide the username/password form and only show the SSO button, set `PULSE_AUTH_HIDE_LOCAL_LOGIN=true` in your environment. You can still access the local login by appending `?show_local=true` to the URL (e.g., `https://your-pulse-instance/?show_local=true`).
+Keep a working, independent administrator login and its browser session while
+setting up SSO. Saving a provider or seeing its login button is not proof of
+successful sign-in or administrator access.
+
+1. **Prepare the IdP application.** Obtain its issuer URL, client ID and client
+ secret through your IdP's normal registration flow. Enter the secret only in
+ Pulse's HTTPS settings form or private deployment configuration, never in a
+ command, URL or report. Start with `openid profile email`; follow the
+ [provider examples](#-provider-examples) for group claims and any additional
+ supported scope, rather than adding `groups` universally.
+2. **Configure access before saving.** In **Settings β†’ Security β†’ Single
+ Sign-On**, add an OIDC provider and enter those details. Select **Show access
+ restrictions & role mapping** and set the intended login restrictions and
+ **Group Role Mappings**, including a trusted group mapped to `admin` if
+ administrators will use SSO. Check the [access rules](#access-control) and
+ [role mappings](#group-to-role-mapping) first; blank login restrictions do
+ not limit sign-ins to administrators. New UI providers are enabled on save.
+3. **Save, then register the actual callback.** Copy **Callback / Redirect
+ URL** from the saved provider card into the IdP's redirect allowlist. Pulse
+ generates the provider ID when it is saved; do not register a guessed ID or
+ the literal `<provider-id>` placeholder. Use the exact public HTTPS URL,
+ not a backend address or wildcard. If the displayed URL is wrong, correct
+ the [HTTPS/proxy configuration](REVERSE_PROXY.md#before-configuring-the-proxy)
+ before signing in, without disabling certificate or origin checks.
+4. **Verify without replacing the working login.** In a separate browser
+ session, sign in as an intended administrator and check access to Security
+ settings. Where you already have suitable users, also check an intended
+ non-admin's read-only access and refusal for an excluded user. Do not change
+ settings to test privileges. A successful provider **Test** checks discovery,
+ not the callback, user claims or resulting permissions. Keep the independent
+ administrator path until these checks pass; do not clear restrictions to
+ make a failed login work. Use [safe diagnosis](#safe-diagnosis).
+
+Only after verifying SSO, optionally hide the local username/password form with
+`PULSE_AUTH_HIDE_LOCAL_LOGIN=true` through your normal deployment configuration.
+Appending `?show_local=true` to your Pulse URL shows that form again; it does
+not create or restore local credentials, bypass the proxy or revoke SSO sessions.
## βš™οΈ Configuration
@@ -30,7 +57,7 @@ Enable Single Sign-On (SSO) with providers like Authentik, Keycloak, Okta, and M
### Access Control
Restrict access to specific users or groups:
-- **Allowed Groups**: Only users in these groups can login. Requires the `groups` scope/claim.
+- **Allowed Groups**: Only users with a matching group in the configured claim can login. Configure the IdP to include that claim; a `groups` scope is not universally supported.
- **Allowed Domains**: Restrict to specific email domains (e.g., `example.com`).
- **Allowed Emails**: Allow specific email addresses.
@@ -81,7 +108,11 @@ If a user has groups `["oidc-admins", "developers"]` and you have mappings:
The user will be assigned both `admin` and `operator` roles.
-> **Note**: Ensure your IdP includes the `groups` scope and that the groups claim is properly configured. Some providers use `groups`, others use `roles` or custom claims.
+> **Note**: Pulse reads the configured groups claim, not a scope name. Some
+> providers use `groups`, others use `roles` or custom claims. Request an extra
+> scope only when that IdP supports and requires it to emit the claim. Microsoft
+> Entra ID has no `groups` scope; use its token configuration below. The scope
+> alone neither supplies group membership nor grants a Pulse role.
### Sessions and `offline_access`
@@ -142,40 +173,48 @@ service as a substitute for verified revocation.
### Authentik
- **Type**: OAuth2/OpenID (Confidential)
-- **Redirect URI**: `https://pulse.example.com/api/oidc/<provider-id>/callback`
+- **Redirect URI**: the exact **Callback / Redirect URL** copied from the saved Pulse provider card.
- **Signing Key**: Must use **RS256** (create a certificate/key pair if needed).
- **Issuer URL**: `https://auth.example.com/application/o/pulse/`
### Keycloak
- **Client ID**: `pulse`
- **Access Type**: Confidential
-- **Valid Redirect URIs**: `https://pulse.example.com/api/oidc/<provider-id>/callback`
+- **Valid Redirect URIs**: the exact **Callback / Redirect URL** copied from the saved Pulse provider card, without a wildcard.
- **Issuer URL**: `https://keycloak.example.com/realms/myrealm`
### Microsoft Entra ID (formerly Azure AD)
-Create the provider in Pulse first (**Settings β†’ Security β†’ Single Sign-On β†’ Add OIDC**) so it gets its ID β€” Pulse generates a UUID per provider and shows the resulting callback URL. You need that URL for the Entra redirect URI below.
+Prepare the Entra app registration and client credentials first, then save the
+Pulse provider with its access restrictions as in [Quick Start](#-quick-start).
+Finally register the callback copied from that saved provider card. Do not use
+dummy client details or a guessed provider ID to break the setup order.
**In the Entra admin center:**
1. **App registrations β†’ New registration**: give it a name (e.g. `Pulse SSO`) and choose *Accounts in this organizational directory only (Single tenant)*.
-2. **Authentication β†’ Add a platform β†’ Web**: set the redirect URI to `https://pulse.example.com/api/oidc/<provider-id>/callback` and tick **ID tokens**.
-3. **Certificates & secrets β†’ New client secret**: copy the secret **Value** (not the Secret ID) β€” it is only shown once.
-4. **Token configuration β†’ Add groups claim**: select **Groups assigned to the application**, expand **ID**, and choose **Group ID**.
-5. **Enterprise applications β†’ (your app) β†’ Properties**: set **Assignment required?** to `Yes`, so only assigned users and groups can sign in.
-6. **Enterprise applications β†’ (your app) β†’ Users and groups**: assign the security group (e.g. `Pulse-Admins`) and copy its **Object ID** β€” a GUID like `a1b2c3d4-e5f6-7890-abcd-123456789abc`.
+2. **Certificates & secrets β†’ New client secret**: copy the secret **Value** (not the Secret ID) β€” it is only shown once. Keep it private for Pulse's HTTPS form.
+3. **Token configuration β†’ Add groups claim**: select **Groups assigned to the application**, expand **ID**, and choose **Group ID**.
+4. **Enterprise applications β†’ (your app) β†’ Properties**: set **Assignment required?** to `Yes`, so only assigned users and groups can sign in.
+5. **Enterprise applications β†’ (your app) β†’ Users and groups**: assign the security group (e.g. `Pulse-Admins`) and copy its **Object ID** β€” a GUID like `a1b2c3d4-e5f6-7890-abcd-123456789abc`.
**In Pulse:**
- **Issuer URL**: `https://login.microsoftonline.com/<tenant-id>/v2.0`
- **Client ID**: the app registration's *Application (client) ID*.
-- **Client Secret**: the secret value from step 3.
-- **Redirect URI**: `https://pulse.example.com/api/oidc/<provider-id>/callback`, matching the app registration exactly. The bare `/api/oidc/callback` is a v5 compatibility path. It is mapped to the legacy (v5-migrated or env-configured) provider; if that provider is not enabled, Pulse instead serves the provider whose login started from it (recovered from the pending login state). Don't use it as the redirect URI for a new provider.
+- **Client Secret**: the secret value from step 2.
+- **Redirect URL**: normally leave the override empty; save to obtain the actual callback from the provider card. The bare `/api/oidc/callback` is a v5 compatibility path. It is mapped to the legacy (v5-migrated or env-configured) provider; if that provider is not enabled, Pulse instead serves the provider whose login started from it (recovered from the pending login state). Don't use it as the redirect URI for a new provider.
- **Scopes**: exactly `openid profile email`. Do **not** add `groups`. Entra has no `groups` scope and fails the whole authorization request with `AADSTS650053`; group membership arrives in the ID token from the Token configuration step, not from a scope.
- **Groups Claim**: `groups`
- **Allowed Groups**: the group's Object ID (GUID), not its display name.
- **Group Role Mappings**: `<guid>=admin`. Keying on the Object ID means the mapping survives a group rename in Entra.
+**Complete the redirect registration before signing in:** In Entra,
+**Authentication β†’ Add a platform β†’ Web**, paste the exact **Callback / Redirect
+URL** from the saved Pulse card and tick **ID tokens**. It must match exactly;
+do not use a wildcard, guessed ID or compatibility callback. Then follow the
+separate-session login and permission checks in Quick Start.
+
> **Warning β€” group overage**: if a user belongs to more groups than Entra will fit in a token, Entra omits the `groups` claim entirely and sends a `_claim_names` / `_claim_sources` overage marker pointing at Microsoft Graph instead. Pulse does not follow that marker, so it sees the user as having no groups β€” and because a configured group-role mapping is authoritative, that login **clears** the user's role assignments instead of leaving them alone. Selecting **Groups assigned to the application** rather than **Security groups** in Token configuration keeps the claim small and avoids the overage. If the token still carries every security group after that, check the app registration **Manifest**: `groupMembershipClaims` must be exactly `"ApplicationGroup"`. A value like `"SecurityGroup, ApplicationGroup"` (left over from an earlier Token configuration choice) keeps emitting all security groups no matter what **Assignment required** is set to, so edit the manifest to drop `SecurityGroup`.
> **Note**: Plain SSO login, **Allowed Groups** gating, and group mapping to built-in roles work on every plan. Creating custom roles and manually managing user assignments require Pro RBAC.
diff --git a/frontend-modern/public/docs/OIDC.md b/frontend-modern/public/docs/OIDC.md
index e671f5fe98..898eadda34 100644
--- a/frontend-modern/public/docs/OIDC.md
+++ b/frontend-modern/public/docs/OIDC.md
@@ -4,16 +4,43 @@ Enable Single Sign-On (SSO) with providers like Authentik, Keycloak, Okta, and M
## πŸš€ Quick Start
-1. **Configure Provider**: Create an OIDC application in your IdP.
- - **Redirect URI**: `https://<your-pulse-domain>/api/oidc/<provider-id>/callback`
- - **Scopes**: `openid`, `profile`, `email`
-2. **Enable in Pulse**: Go to **Settings β†’ Security β†’ Single Sign-On**.
-3. **Enter Details**:
- - **Issuer URL**: The base URL of your IdP (e.g., `https://auth.example.com/application/o/pulse/`).
- - **Client ID & Secret**: From your IdP.
-4. **Save**: The login page will now show your configured SSO provider button(s).
-
-> **Tip**: To hide the username/password form and only show the SSO button, set `PULSE_AUTH_HIDE_LOCAL_LOGIN=true` in your environment. You can still access the local login by appending `?show_local=true` to the URL (e.g., `https://your-pulse-instance/?show_local=true`).
+Keep a working, independent administrator login and its browser session while
+setting up SSO. Saving a provider or seeing its login button is not proof of
+successful sign-in or administrator access.
+
+1. **Prepare the IdP application.** Obtain its issuer URL, client ID and client
+ secret through your IdP's normal registration flow. Enter the secret only in
+ Pulse's HTTPS settings form or private deployment configuration, never in a
+ command, URL or report. Start with `openid profile email`; follow the
+ [provider examples](#-provider-examples) for group claims and any additional
+ supported scope, rather than adding `groups` universally.
+2. **Configure access before saving.** In **Settings β†’ Security β†’ Single
+ Sign-On**, add an OIDC provider and enter those details. Select **Show access
+ restrictions & role mapping** and set the intended login restrictions and
+ **Group Role Mappings**, including a trusted group mapped to `admin` if
+ administrators will use SSO. Check the [access rules](#access-control) and
+ [role mappings](#group-to-role-mapping) first; blank login restrictions do
+ not limit sign-ins to administrators. New UI providers are enabled on save.
+3. **Save, then register the actual callback.** Copy **Callback / Redirect
+ URL** from the saved provider card into the IdP's redirect allowlist. Pulse
+ generates the provider ID when it is saved; do not register a guessed ID or
+ the literal `<provider-id>` placeholder. Use the exact public HTTPS URL,
+ not a backend address or wildcard. If the displayed URL is wrong, correct
+ the [HTTPS/proxy configuration](REVERSE_PROXY.md#before-configuring-the-proxy)
+ before signing in, without disabling certificate or origin checks.
+4. **Verify without replacing the working login.** In a separate browser
+ session, sign in as an intended administrator and check access to Security
+ settings. Where you already have suitable users, also check an intended
+ non-admin's read-only access and refusal for an excluded user. Do not change
+ settings to test privileges. A successful provider **Test** checks discovery,
+ not the callback, user claims or resulting permissions. Keep the independent
+ administrator path until these checks pass; do not clear restrictions to
+ make a failed login work. Use [safe diagnosis](#safe-diagnosis).
+
+Only after verifying SSO, optionally hide the local username/password form with
+`PULSE_AUTH_HIDE_LOCAL_LOGIN=true` through your normal deployment configuration.
+Appending `?show_local=true` to your Pulse URL shows that form again; it does
+not create or restore local credentials, bypass the proxy or revoke SSO sessions.
## βš™οΈ Configuration
@@ -30,7 +57,7 @@ Enable Single Sign-On (SSO) with providers like Authentik, Keycloak, Okta, and M
### Access Control
Restrict access to specific users or groups:
-- **Allowed Groups**: Only users in these groups can login. Requires the `groups` scope/claim.
+- **Allowed Groups**: Only users with a matching group in the configured claim can login. Configure the IdP to include that claim; a `groups` scope is not universally supported.
- **Allowed Domains**: Restrict to specific email domains (e.g., `example.com`).
- **Allowed Emails**: Allow specific email addresses.
@@ -81,7 +108,11 @@ If a user has groups `["oidc-admins", "developers"]` and you have mappings:
The user will be assigned both `admin` and `operator` roles.
-> **Note**: Ensure your IdP includes the `groups` scope and that the groups claim is properly configured. Some providers use `groups`, others use `roles` or custom claims.
+> **Note**: Pulse reads the configured groups claim, not a scope name. Some
+> providers use `groups`, others use `roles` or custom claims. Request an extra
+> scope only when that IdP supports and requires it to emit the claim. Microsoft
+> Entra ID has no `groups` scope; use its token configuration below. The scope
+> alone neither supplies group membership nor grants a Pulse role.
### Sessions and `offline_access`
@@ -142,40 +173,48 @@ service as a substitute for verified revocation.
### Authentik
- **Type**: OAuth2/OpenID (Confidential)
-- **Redirect URI**: `https://pulse.example.com/api/oidc/<provider-id>/callback`
+- **Redirect URI**: the exact **Callback / Redirect URL** copied from the saved Pulse provider card.
- **Signing Key**: Must use **RS256** (create a certificate/key pair if needed).
- **Issuer URL**: `https://auth.example.com/application/o/pulse/`
### Keycloak
- **Client ID**: `pulse`
- **Access Type**: Confidential
-- **Valid Redirect URIs**: `https://pulse.example.com/api/oidc/<provider-id>/callback`
+- **Valid Redirect URIs**: the exact **Callback / Redirect URL** copied from the saved Pulse provider card, without a wildcard.
- **Issuer URL**: `https://keycloak.example.com/realms/myrealm`
### Microsoft Entra ID (formerly Azure AD)
-Create the provider in Pulse first (**Settings β†’ Security β†’ Single Sign-On β†’ Add OIDC**) so it gets its ID β€” Pulse generates a UUID per provider and shows the resulting callback URL. You need that URL for the Entra redirect URI below.
+Prepare the Entra app registration and client credentials first, then save the
+Pulse provider with its access restrictions as in [Quick Start](#-quick-start).
+Finally register the callback copied from that saved provider card. Do not use
+dummy client details or a guessed provider ID to break the setup order.
**In the Entra admin center:**
1. **App registrations β†’ New registration**: give it a name (e.g. `Pulse SSO`) and choose *Accounts in this organizational directory only (Single tenant)*.
-2. **Authentication β†’ Add a platform β†’ Web**: set the redirect URI to `https://pulse.example.com/api/oidc/<provider-id>/callback` and tick **ID tokens**.
-3. **Certificates & secrets β†’ New client secret**: copy the secret **Value** (not the Secret ID) β€” it is only shown once.
-4. **Token configuration β†’ Add groups claim**: select **Groups assigned to the application**, expand **ID**, and choose **Group ID**.
-5. **Enterprise applications β†’ (your app) β†’ Properties**: set **Assignment required?** to `Yes`, so only assigned users and groups can sign in.
-6. **Enterprise applications β†’ (your app) β†’ Users and groups**: assign the security group (e.g. `Pulse-Admins`) and copy its **Object ID** β€” a GUID like `a1b2c3d4-e5f6-7890-abcd-123456789abc`.
+2. **Certificates & secrets β†’ New client secret**: copy the secret **Value** (not the Secret ID) β€” it is only shown once. Keep it private for Pulse's HTTPS form.
+3. **Token configuration β†’ Add groups claim**: select **Groups assigned to the application**, expand **ID**, and choose **Group ID**.
+4. **Enterprise applications β†’ (your app) β†’ Properties**: set **Assignment required?** to `Yes`, so only assigned users and groups can sign in.
+5. **Enterprise applications β†’ (your app) β†’ Users and groups**: assign the security group (e.g. `Pulse-Admins`) and copy its **Object ID** β€” a GUID like `a1b2c3d4-e5f6-7890-abcd-123456789abc`.
**In Pulse:**
- **Issuer URL**: `https://login.microsoftonline.com/<tenant-id>/v2.0`
- **Client ID**: the app registration's *Application (client) ID*.
-- **Client Secret**: the secret value from step 3.
-- **Redirect URI**: `https://pulse.example.com/api/oidc/<provider-id>/callback`, matching the app registration exactly. The bare `/api/oidc/callback` is a v5 compatibility path. It is mapped to the legacy (v5-migrated or env-configured) provider; if that provider is not enabled, Pulse instead serves the provider whose login started from it (recovered from the pending login state). Don't use it as the redirect URI for a new provider.
+- **Client Secret**: the secret value from step 2.
+- **Redirect URL**: normally leave the override empty; save to obtain the actual callback from the provider card. The bare `/api/oidc/callback` is a v5 compatibility path. It is mapped to the legacy (v5-migrated or env-configured) provider; if that provider is not enabled, Pulse instead serves the provider whose login started from it (recovered from the pending login state). Don't use it as the redirect URI for a new provider.
- **Scopes**: exactly `openid profile email`. Do **not** add `groups`. Entra has no `groups` scope and fails the whole authorization request with `AADSTS650053`; group membership arrives in the ID token from the Token configuration step, not from a scope.
- **Groups Claim**: `groups`
- **Allowed Groups**: the group's Object ID (GUID), not its display name.
- **Group Role Mappings**: `<guid>=admin`. Keying on the Object ID means the mapping survives a group rename in Entra.
+**Complete the redirect registration before signing in:** In Entra,
+**Authentication β†’ Add a platform β†’ Web**, paste the exact **Callback / Redirect
+URL** from the saved Pulse card and tick **ID tokens**. It must match exactly;
+do not use a wildcard, guessed ID or compatibility callback. Then follow the
+separate-session login and permission checks in Quick Start.
+
> **Warning β€” group overage**: if a user belongs to more groups than Entra will fit in a token, Entra omits the `groups` claim entirely and sends a `_claim_names` / `_claim_sources` overage marker pointing at Microsoft Graph instead. Pulse does not follow that marker, so it sees the user as having no groups β€” and because a configured group-role mapping is authoritative, that login **clears** the user's role assignments instead of leaving them alone. Selecting **Groups assigned to the application** rather than **Security groups** in Token configuration keeps the claim small and avoids the overage. If the token still carries every security group after that, check the app registration **Manifest**: `groupMembershipClaims` must be exactly `"ApplicationGroup"`. A value like `"SecurityGroup, ApplicationGroup"` (left over from an earlier Token configuration choice) keeps emitting all security groups no matter what **Assignment required** is set to, so edit the manifest to drop `SecurityGroup`.
> **Note**: Plain SSO login, **Allowed Groups** gating, and group mapping to built-in roles work on every plan. Creating custom roles and manually managing user assignments require Pro RBAC.
diff --git a/frontend-modern/src/features/docs/__tests__/oidcSetupDocs.test.ts b/frontend-modern/src/features/docs/__tests__/oidcSetupDocs.test.ts
new file mode 100644
index 0000000000..223a5ad1ad
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/oidcSetupDocs.test.ts
@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createGuideFixture } from './guideFixture';
+
+const read = (name: string) => readFileSync(resolve(process.cwd(), '../docs', `${name}.md`), 'utf8');
+const article = createGuideFixture(read);
+const text = (node: Element) => node.textContent!.replace(/\s+/g, ' ').trim();
+
+describe('OIDC setup without losing access', () => {
+ it('renders the real setup sequence before optional local-login hiding', () => {
+ const guide = article('OIDC');
+ const setup = guide.querySelector('[id="-quick-start"]')!;
+ expect(text(setup.nextElementSibling!)).toContain('independent administrator login');
+ const list = setup.nextElementSibling!.nextElementSibling!;
+ expect(list.tagName).toBe('OL');
+ expect([...list.children].map((step) => text(step.querySelector('strong')!))).toEqual([
+ 'Prepare the IdP application.',
+ 'Configure access before saving.',
+ 'Save, then register the actual callback.',
+ 'Verify without replacing the working login.',
+ ]);
+ expect(text(list.children[1])).toContain('Show access restrictions & role mapping');
+ expect(text(list.children[1])).toContain('New UI providers are enabled on save');
+ expect(text(list.children[2])).toContain('literal <provider-id> placeholder');
+ expect(text(list.children[3])).toContain('not the callback, user claims');
+ expect(text(list.nextElementSibling!)).toContain('does not create or restore local credentials');
+ });
+
+ it('keeps the common claim advice consistent with the Entra recipe', () => {
+ const guide = article('OIDC');
+ expect(text(guide)).not.toContain('Requires the groups scope/claim');
+ expect(text(guide)).not.toContain('Ensure your IdP includes the groups scope');
+ expect(text(guide)).toContain('a groups scope is not universally supported');
+ expect(text(guide)).toContain('Pulse reads the configured groups claim, not a scope name');
+ const entra = guide.querySelector('#microsoft-entra-id-formerly-azure-ad')!;
+ expect(text(entra.nextElementSibling!)).toContain('client credentials first');
+ expect(text(guide)).toContain('Complete the redirect registration before signing in');
+ expect(text(guide)).toContain('Do not add groups');
+ expect(readFileSync(resolve(process.cwd(), 'public/docs/OIDC.md'), 'utf8')).toBe(read('OIDC'));
+ });
+
+ it('links all setup decisions to real focused documentation headings', () => {
+ const guide = article('OIDC');
+ for (const [name, fragment] of [
+ ['OIDC', '-provider-examples'],
+ ['OIDC', 'access-control'],
+ ['OIDC', 'group-to-role-mapping'],
+ ['OIDC', 'safe-diagnosis'],
+ ['OIDC', '-quick-start'],
+ ['REVERSE_PROXY', 'before-configuring-the-proxy'],
+ ]) {
+ expect(guide.querySelector(`a[href="/docs/${name}#${fragment}"]`)).not.toBeNull();
+ expect(article(name).querySelector(`[id="${fragment}"]`)).not.toBeNull();
+ }
+ });
+});
diff --git a/scripts/tests/test_oidc_session_docs.py b/scripts/tests/test_oidc_session_docs.py
index 14243ce64a..892eecfc10 100644
--- a/scripts/tests/test_oidc_session_docs.py
+++ b/scripts/tests/test_oidc_session_docs.py
@@ -18,7 +18,63 @@ def guide_section(start, end):
return " ".join(text.split(start, 1)[1].split(end, 1)[0].split())
+def assert_callback_setup(case, guide):
+ setup = " ".join(guide.split("## πŸš€ Quick Start", 1)[1].split("## βš™οΈ Configuration", 1)[0].split())
+ markers = ("Keep a working, independent administrator login", "Prepare the IdP application",
+ "Configure access before saving", "Save, then register the actual callback",
+ "Verify without replacing the working login", "Only after verifying SSO")
+ positions = []
+ for marker in markers:
+ case.assertIn(marker, setup)
+ positions.append(setup.index(marker))
+ case.assertEqual(positions, sorted(positions))
+ for marker in ("Show access restrictions & role mapping", "New UI providers are enabled on save",
+ "do not register a guessed ID", "not the callback, user claims",
+ "does not create or restore local credentials"):
+ case.assertIn(marker, setup)
+
+
+def assert_group_claim_advice(case, guide):
+ case.assertNotIn("Requires the `groups` scope/claim", guide)
+ case.assertNotIn("Ensure your IdP includes the `groups` scope", guide)
+ for marker in ("a `groups` scope is not universally supported", "not a scope name",
+ "Entra ID has no `groups` scope", "alone neither supplies group membership"):
+ case.assertIn(marker, " ".join(guide.split()))
+
+
class OIDCSessionDocsTest(unittest.TestCase):
+ def test_setup_orders_callback_and_access_before_cutover(self):
+ assert_callback_setup(self, GUIDE.read_text())
+
+ def test_generic_group_advice_does_not_break_entra(self):
+ assert_group_claim_advice(self, GUIDE.read_text())
+
+ def test_provider_examples_copy_the_saved_callback(self):
+ text = guide_section("## πŸ“š Provider Examples", "## πŸ”§ Troubleshooting")
+ self.assertNotIn("Create the provider in Pulse first", text)
+ self.assertNotIn("<provider-id>", text)
+ self.assertIn("Prepare the Entra app registration and client credentials first", text)
+ self.assertIn("Complete the redirect registration before signing in", text)
+ self.assertIn("secret value from step 2", text)
+ self.assertIn("Do **not** add `groups`", text)
+ self.assertIn("compatibility path", text)
+
+ def test_setup_matches_existing_form_and_discovery_test(self):
+ panel = (ROOT / "frontend-modern/src/components/Settings/SSOProvidersPanel.tsx").read_text()
+ self.assertIn("URL is generated when the provider is saved", panel)
+ self.assertIn("access restrictions & role mapping", panel)
+ self.assertIn('label="Group Role Mappings"', panel)
+ model = (ROOT / "frontend-modern/src/components/Settings/ssoProvidersModel.ts").read_text()
+ defaults = model.split("export const createEmptyProviderForm", 1)[1].split("});", 1)[0]
+ self.assertIn("id: ''", defaults)
+ self.assertIn("enabled: true", defaults)
+ self.assertIn("oidcScopes: 'openid profile email'", defaults)
+ handlers = (ROOT / "internal/api/identity_sso_handlers.go").read_text()
+ create = handlers.split("func (r *Router) handleCreateSSOProvider", 1)[1].split(
+ "func (r *Router) handleUpdateSSOProvider", 1)[0]
+ self.assertIn("provider.ID = uuid.NewString()", create)
+ self.assertIn('Message: "OIDC discovery successful"', handlers)
+
def test_cookie_server_and_idp_lifetimes_are_distinct(self):
text = guide_section("### Sessions and `offline_access`", "#### Changing or removing access")
for expected in (