OIDC SSO & API Tokens

CollectorCtrl supports centralized enterprise identity management and programmatic access control. This section explains how to configure OpenID Connect (OIDC) SSO and issue secure API Tokens for programmatic automation.

OIDC Identity & Group Mapping

Enterprise users log in via Single Sign-On (SSO). Their identity claims are dynamically mapped to secure system roles (admin, editor, viewer).

Identity Provider

Mapping Engine

1. OIDC SSO Configuration

Centralize user management by integrating your Identity Provider (IdP) such as Azure AD (Entra ID), Okta, Auth0, or Keycloak.

OIDC Configuration Panel

Core Settings Parameters

Configure the following parameters in the SSO Configuration view:

Issuer URL: The base endpoint of your provider (e.g. https://login.microsoftonline.com/{tenant}/v2.0). The server queries this URL to auto-discover configuration endpoints (resolving .well-known/openid-configuration).
Client ID & Client Secret: The credentials generated during app registration in your IdP portal.
Redirect Callback URL: The endpoint where users are returned after successful authentication: https://your-collectorctrl-server:4321/api/auth/callback
Default Role: The default access role (typically Viewer) assigned to authenticated users who do not match any explicit group mappings.

2. Directory Group-to-Role Mapping

To automate permission updates, CollectorCtrl maps identity claims (typically the groups array in the ID token) to system roles.

Map AD Groups to System Roles:
- Admin Groups: Users matching groups like AD-DomainAdmins or SecOps-Leads receive system-wide Admin access.
- Editor Groups: Users in groups like DevOps-Engineers or SRE-Team receive Editor permissions.
- Viewer Groups: Fallback groups (e.g. Dev-All) receive Viewer access.
Highest-Privilege Resolution: If a user belongs to multiple groups matching different mappings, CollectorCtrl automatically resolves permissions and grants the highest matching role.

3. Emergency "Break-Glass" Access

If your external Identity Provider goes offline, you can bypass OIDC using emergency local access:

Local Bootstrap Admin: CollectorCtrl maintains a local, isolated admin account (admin) in the database.
Access Isolation: SSO users are blocked from setting local passwords, preventing credential bypasses. Local password hashing is enforced using Bcrypt.
Recovery Mechanism: In the event of an IdP outage, administrators log in via the local console portal bypass link: https://your-server:4321/login?local=true.

4. API Token Management & Security

For automation, CI/CD pipelines, and registering new Supervisor agents, you can generate persistent API keys.

API Tokens Management

Token Generation & Prefixes

Dynamic Generation: Navigate to SSO & Tokens > API Tokens and click Generate Token.
One-Time Visibility: The secret is displayed once. CollectorCtrl hashes the token value using SHA-256 before saving it, ensuring leaked database backups do not expose active API tokens.
Scope Definition: Tokens are assigned standard RBAC roles (e.g. SupervisorRegistration, CI-Operator).

Secret Scanning Compatibility

To protect your infrastructure from accidental token exposure, CollectorCtrl API tokens use a recognizable structure:

Prefix Format: Every token begins with the prefix cct_ (CollectorCtrl Token).
Automated Scanners: This prefix format is compatible with secret scanning tools like Gitleaks and GitHub Secret Scanning. If a developer accidentally commits a token to a repository, scanning rules identify the signature prefix and flag the leak, allowing security teams to revoke the token before it is abused.