fix(auth): let an Auth0 RBAC admin role reach the token

[schronck]

Summary

With DECPM_ADMIN_ROLE set on an Auth0 node, no user could pass require_admin, so POST /network-config, /kick and post-bootstrap PUT /party-config were unreachable. Auth0 returns a permission in scope only when the client requested it, and the SPA requested nothing beyond the default openid profile email.

Two carriers, so an operator can pick per tenant:

• permissions — read the array Auth0 emits under access_token_authz. Auth0 does not filter it by requested scope, so an RBAC-assigned role arrives with no post-login Action. This is the path that needs no Auth0 Action at all.
• DECPM_AUTH0_SCOPE — extra scopes plumbed cli.rs → Auth0Config → /auth-config → authorizationParams.scope, for tenants that grant the role as a resource-server scope.

DECPM_JWT_ROLE_CLAIM (#378) already covers the namespaced-custom-claim path. The three are complementary; the docs now present all three and lead with the one that needs no Action.

Related issues

Closes #383

Type of change

• Bug fix
• New feature
• Refactor
• Documentation
• Build / CI / chore

Checklist

• cargo fmt -- --check passes
• cargo clippy --all-targets --all-features -- -D warnings is clean
• cargo test passes
• Added/updated tests where appropriate
• Updated documentation where appropriate
• Commits follow the <type>(<scope>): <subject> convention

Notes for reviewers

Two decisions worth a look.

permissions is read from the flattened claim map, not a typed field. A typed Option<Vec<String>> would fail the whole decode::<Claims> on any provider that emits a different shape under that name, turning a cosmetic mismatch into a total lockout of a healthy node. malformed_permissions_claim_still_verifies pins that.

The frontend re-states openid profile email when a scope is set. auth0-spa-js 2.19.2 builds options as Object.assign({}, defaultOptions.authorizationParams, options.authorizationParams), a shallow merge, so a supplied scope replaces the default outright — its own typings say so. A plain passthrough would have silently stripped the email claim Principal reads.

cargo test is unchecked because I did not run the suite locally; clippy --all-targets compiles the new tests, and CI will execute them. Five added: permissions grants the role, malformed permissions still verifies, permissions/scope dedupe, and /auth-config surfacing vs omitting the scope.

The reporter on #383 offered to test whichever shape we picked, so worth a devnet image for them.

[Copilot]

Pull request overview

This PR fixes Auth0-admin authorization failures by adding support for Auth0 RBAC permissions[] as a role carrier in JWT validation, and by optionally plumbing a deploy-time Auth0 scope (DECPM_AUTH0_SCOPE) from CLI/config → backend /auth-config → frontend Auth0 SDK initialization. It also updates the deployment guide to document the three supported Auth0 “admin role” carriers.

Changes:

• Extend JWT role extraction to read Auth0 RBAC permissions (in addition to existing roles, realm_access.roles, and scope carriers), with tests.
• Add DECPM_AUTH0_SCOPE through config + /auth-config, and update the SPA to append it while preserving Auth0’s default openid profile email.
• Update deployment documentation to explain the three carrier options and troubleshooting guidance.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/DEPLOYMENT_GUIDE.md	Documents Auth0 admin-role carrier options (permissions, scope, custom claim) and adds DECPM_AUTH0_SCOPE.
crates/decman/src/server/handlers/auth.rs	Extends /auth-config response with auth0_scope and adds handler tests.
crates/decman/src/main.rs	Wires CLI/env DECPM_AUTH0_SCOPE into Auth0Config and warns when scope is set without Auth0 config.
crates/decman/src/config.rs	Adds scope: Option<String> to Auth0Config with documentation and updates config tests.
crates/decman/src/cli.rs	Introduces hidden CLI/env option DECPM_AUTH0_SCOPE.
crates/decman/src/auth/validators/jwt.rs	Reads Auth0 permissions[] into role collection and adds targeted JWT validator tests.
crates/decman/frontend/src/main.tsx	If auth0_scope is present, requests openid profile email plus the configured scopes (avoiding auth0-spa-js default override).
crates/common/src/types.rs	Adds auth0_scope to AuthConfigResponse (omitted when None).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

crates/decman/src/auth/validators/jwt.rs:268

• Restrict this carrier to the configured Auth0 API. find_trusted currently records only client_id/discovery data and JWT validation disables audience checking, so this block promotes permissions for every trusted issuer. The new test even uses a Keycloak validator. Consequently, a Keycloak token—or an Auth0 token for another API in the same tenant and SPA—with a matching permission can satisfy DECPM_ADMIN_ROLE. Preserve the matched provider and expected Auth0 audience, enforce that audience, and only merge permissions for that Auth0 match.

        if let Some(value) = claims.additional.get("permissions")
            && let Ok(permissions) = serde_json::from_value::<Vec<String>>(value.clone())
        {
            flat_roles.extend(permissions);