User Management

Audience: Administrators, Platform Engineers
Time: ~15 min
Prerequisites: Control Core Control Plane deployed and accessible, Super Administrator (ccadmin) credentials

This guide covers creating and managing users, role definitions and permissions, SSO configuration, passkeys, MFA, authentication methods, and session management within the Control Core Control Plane.

Overview

The User Management page (Settings → Users) provides centralized administration for:

• Users — create, edit, deactivate, and audit user accounts
• SSO — configure enterprise identity providers (Entra, Okta, Google Workspace, Auth0, PingID, Generic OIDC, SAML)
• MFA — enforce multi-factor authentication across the organization
• Passkeys — manage WebAuthn/FIDO2 passwordless credentials
• Authentication Methods — control which login methods are available

Accessing User Management

1. Log in to the Control Core Control Plane as a Super Administrator
2. Navigate to Settings → Users
3. Select the appropriate tab for the area you want to configure

Role Definitions

Control Core uses role-based access control aligned with the principle of least privilege. Each user is assigned exactly one role that determines their permissions across the platform.

Role Assignment Best Practices

• Assign the lowest role that allows the user to perform their job function
• Use Super Administrator sparingly — only for platform owners and billing managers
• Policy Administrator is the recommended role for control authors who need to deploy to production
• Developer is appropriate for engineers who author and test controls but should not deploy to production without review
• All role assignments are audited — changes appear in Audit Logs

Strict Role Enforcement

Control Core enforces role permissions strictly by default. A user whose role does not include a required permission receives a clear "permission denied" response (HTTP 403) and the Control Plane UI hides pages they cannot use. The built-in ccadmin Super Administrator always retains full access and can never be locked out.

• The behavior is governed by the Strict role enforcement feature flag (Settings → Feature Flags), which is on in new installations.
• If you are migrating an existing deployment and need a transition window, you can turn the flag off temporarily: actions that would be blocked still run, but each one is recorded so you can review who would have been denied before enabling strict mode.
• Turn it back on once your role assignments are confirmed. Leaving it off is not recommended for production.

Troubleshooting: If a user reports "Access denied" on a page they previously used, confirm their role includes the relevant permission in the table above. Re-assign the appropriate role under Settings → Users; the change is audited and takes effect on their next page load.

Creating and Managing Users

Manual User Creation

When SSO is not configured, the Super Administrator can create users manually:

1. Navigate to Settings → Users → Users tab
2. Click Create User
3. Fill in the required fields: email, display name, role, and department
4. The user receives credentials via the configured method (email or manual distribution)

Troubleshooting: If the Create User button is disabled, SSO may be active. When SSO is enabled, user provisioning flows through your identity provider — only the built-in ccadmin account can be created manually.

User Lifecycle

• Active — user can log in and access the platform per their role
• Inactive — user account exists but login is disabled
• Suspended — temporarily locked (e.g., after failed login attempts or administrative action)
• Pending — user created but has not completed initial authentication

Editing Users

1. Click the edit icon next to a user in the user table
2. Update role, department, or status as needed
3. Click Save

All user modifications generate an audit trail entry.

SSO Configuration

Control Core supports enterprise Single Sign-On via OIDC and SAML 2.0 protocols.

Supported Identity Providers

OIDC Environment Variables

All OIDC providers share a common set of environment variables:

Secure OIDC by default. Control Core uses the Authorization Code flow with PKCE (S256) and a per-login nonce, and it cryptographically verifies every ID token's signature against your provider's published JWKS (jwks_uri in the discovery document) before trusting any claim. Issuer, audience, expiry, and nonce are all validated. No additional configuration is required — any standards-compliant OIDC provider exposes the discovery document and JWKS that Control Core needs.

Troubleshooting: If OIDC login fails with "token verification failed", confirm OIDC_ISSUER_URL points at the issuer whose .well-known/openid-configuration lists a reachable jwks_uri, and that the Control Plane can make outbound HTTPS calls to that JWKS endpoint.

For SAML 2.0, set AUTH_METHOD_SSO_SAML_ENABLED=true and configure both the identity-provider (IdP) and service-provider (SP) sides:

SAML assertion signatures are validated against SAML_CERTIFICATE on every login; assertions that are unsigned, expired, or fail signature checks are rejected. The Control Plane container image bundles the native xmlsec dependency required for signature verification.

Role Mapping

Map identity provider roles/groups to Control Core roles:

1. Navigate to Settings → Users → SSO tab
2. Scroll to Role Mapping
3. For each IdP group/role, select the corresponding Control Core role
4. Click Save role mapping

Users without a matching role mapping default to Viewer.

The role claim is configured via the OIDC_ROLE_CLAIM environment variable. You can also override all mappings via OIDC_ROLE_MAPPING_JSON (JSON object mapping IdP role strings to Control Core role IDs).

Applying SSO Configuration

Environment variables are read on service startup. After updating them:

1. Set the environment variables in your deployment configuration (Helm values, Docker Compose, or .env)
2. Restart the Control Core PAP API service
3. Use Test Connection in the SSO tab to validate the OIDC discovery document
4. Sign out and sign back in from the SSO tab on the login page
5. Monitor user provisioning in the Users tab

Important: While SSO is enabled, only the built-in ccadmin account can create users manually. All other provisioning flows through your identity provider.

Troubleshooting: If Test Connection fails, verify that OIDC_ISSUER_URL resolves to a valid .well-known/openid-configuration endpoint. Check network connectivity between the Control Plane and your IdP. Common causes: firewall rules blocking outbound HTTPS, incorrect tenant ID in the issuer URL, or expired client secret.

Passkeys (WebAuthn)

Passkeys are a modern, phishing-resistant authentication method based on the WebAuthn/FIDO2 standard. They use your device's built-in security features — fingerprint readers, face recognition, or hardware security keys — to authenticate without passwords.

Why Passkeys

• No passwords to remember or manage — eliminates password fatigue and reuse
• Phishing resistant — cryptographic challenge-response bound to the origin; cannot be replayed on a fake site
• Cross-device sync — passkeys stored in iCloud Keychain, Google Password Manager, or Windows Hello sync across your devices
• Faster login — biometric verification is typically faster than typing a password + MFA code

Registering a Passkey

1. Navigate to Settings → Users → Passkeys tab
2. Click Register New Passkey
3. Follow the browser prompt to create a passkey using your device's biometric or security key
4. The passkey appears in your registered passkeys list

Managing Passkeys

• View all registered passkeys with their creation date and last-used timestamp
• Delete passkeys you no longer use by clicking the delete icon

Environment Variables

Browser Support

Passkeys are supported in all modern browsers:

Troubleshooting: If passkey registration fails, verify that PASSKEY_RP_ID matches your domain exactly (no protocol prefix, no port). Ensure PASSKEY_ALLOWED_ORIGINS includes the full origin with protocol. Check that your browser supports WebAuthn and that biometric authentication is enabled on your device.

MFA Configuration

Multi-factor authentication adds a second verification step after password login using a Time-based One-Time Password (TOTP) authenticator app.

Enabling Organization-Wide MFA

1. Navigate to Settings → Users → MFA tab
2. Toggle Require MFA for all users (or set AUTH_REQUIRE_MFA=true in your deployment configuration)
3. When enabled, all users must configure MFA before accessing the platform

How enforcement works at login:

• A user who has enrolled an authenticator is always challenged for a 6-digit TOTP code after a correct password — regardless of the org-wide setting. Login does not complete until a valid code is supplied.
• When MFA is required (AUTH_REQUIRE_MFA=true) and a user has not enrolled, that user is blocked from completing login until they enroll. Provide an enrollment window before turning this on org-wide.
• The built-in ccadmin bootstrap account is exempt from the not-enrolled block so an administrator can never be locked out while rolling MFA out; ccadmin should still enrol an authenticator as a best practice.
• Programmatic logins supply the code via the mfa_code field on the login request; interactive logins are prompted automatically.

Supported Authenticator Apps

• Google Authenticator — Android and iOS
• Microsoft Authenticator — Android, iOS, and Windows

MFA Setup (Per User)

1. Open the MFA setup dialog (triggered on next login when MFA is required, or via user settings)
2. Scan the displayed QR code with your authenticator app
3. Enter the 6-digit verification code from the app
4. MFA is now active for your account

Per-User MFA Status

The MFA tab shows a table of all users with their current MFA enrollment status. Super Administrators can:

• View which users have MFA enabled
• Reset MFA for a user who has lost access to their authenticator

Troubleshooting: If a user cannot complete MFA setup, ensure their authenticator app's clock is synchronized (TOTP codes are time-sensitive, typically with a 30-second window). If a user loses their authenticator device, a Super Administrator can reset their MFA enrollment from the MFA tab.

Authentication Methods

Control Core supports multiple authentication methods that can be enabled or disabled based on your organization's security requirements.

Available Methods

Session Management

Operational guidance for administrators:

1. Use Settings → General → Security → Session Timeout (minutes) to define how much idle time (no qualifying interaction or navigation recorded in that browser tab) is allowed before the warning banner appears for Control Plane operators. Typical platform default is 60 minutes unless your deployment seeded a different baseline. Administrators may choose 5–480 minutes aligned with organizational risk posture.
2. After the countdown on the banner elapses without a choice or after an explicit logout, users must authenticate again—the Control Plane clears local session artifacts.
3. Stay Logged In asks the backend to mint a rotated access token and restarts idle timing; POST /auth/refresh only succeeds inside server-enforced concurrency and uninterrupted-duration caps.
4. Configure CONTROL_CORE_SESSION_MAX_ABSOLUTE_HOURS and CONTROL_CORE_SESSION_MAX_CONCURRENT on the Control Plane API when you need tighter upper bounds on uninterrupted browser tenancy or simultaneous interactive sessions—these safeguards override purely idle-based timelines.

Consult your deployment changelog for Authentication Methods tuning (remember-device windows, SSO-only flows).

Troubleshooting: If “Stay Logged In” redirects to /login, confirm POST /auth/refresh returns HTTP 200 in the developer tools Network tab immediately after pressing the button. Review Control Plane API diagnostics for revocation or concurrency limits (CONTROL_CORE_SESSION_MAX_CONCURRENT).

Token Signing and Service Hardening

Asymmetric token signing (RS256) and JWKS

By default the Control Plane signs session tokens with RS256 (an asymmetric keypair). The private key never leaves the Control Plane API; the public key is published so other services can verify tokens without holding a secret.

• Public verification keys: GET /auth/jwks.json returns the active public key(s) in standard JWKS format. Downstream services and Bouncers can fetch this endpoint to verify Control Plane–issued tokens.
• Key rotation: A Super Administrator can rotate the signing key with POST /auth/keys/rotate. The previous public key remains published until in-flight tokens expire, so rotation is zero-downtime. Rotate on your normal cryptographic cadence (≤ 90 days) or immediately on suspected compromise.
• Compatibility: Set JWT_SIGNING_ALG=HS256 only if you have a specific reason to fall back to symmetric signing; RS256 is recommended for all production deployments.

Troubleshooting: If a downstream verifier reports an unknown key ID (kid), it is caching a stale JWKS. Have it re-fetch GET /auth/jwks.json; after a rotation both the new and previous keys are listed until old tokens expire.

CORS hardening

In production-like deployments the Control Plane API refuses to start if CORS_ORIGINS is left as the wildcard *. Set CORS_ORIGINS to the exact Control Plane frontend origin(s), comma-separated:

CORS_ORIGINS=https://controlplane.example.com

Troubleshooting: If the API container exits immediately at startup with a CORS_ORIGINS='*' is not permitted error, set CORS_ORIGINS to your real frontend origin(s) and redeploy. Wildcard CORS is only tolerated in local/non-production environments.

Troubleshooting

Cannot Log In

Passkey Issues

SSO Issues

Next Steps

• Administrator Guide — full platform administration reference
• Configuration Reference — complete environment variable reference including authentication
• Security Overview — platform security architecture and compliance
• Admin Troubleshooting — broader troubleshooting guide for all admin operations