CISO Assistant User Mgmt

User Management Page: Groups and RBAC Mapping Reference This guide details how to configure the internal user management workflow, handle user profiles, and map functional User Groups to baseline Roles across your defined Domains.

1. Architecture Overview: IAM & RBAC Matrix
   
   CISO Assistant separates account identities from specific execution scopes. Users do not hold permissions globally; instead, their capabilities are scoped to the Domain they occupy through specialized user groups.

Core Built-in Roles

• Manager (Privileged): Full write, delete, and assignment creation capabilities for the designated domain.

• Auditor: Read-only tracking across framework requirements and compliance campaigns.

• Contributor (Actor/Respondent): Scoped access allowing assessment updates and evidence upload for specifically assigned tasks.

1. Group-to-Role Mapping Strategy
   
   To maintain strict compliance with the Access Control Policy (Least Privilege and Need-to-Know), organizational units are structured using a three-tier configuration:

[Identity Provider Group]  ──>  [CISO Assistant User Group]  ──>  [Scoped Domain Role]

(e.g., Entra ID DevOps)           (e.g., AWS-Prod-Managers)           (Manager over AWS-Prod)

Authorization Mapping Framework

Functional Group Name

Target Platform Role

Access Scope

Policy / Verification

Global-Admins

Instance Superuser

Instance-wide controls & system configurations.

MFA Required; credentials vaulted.

Domain-Managers

Manager

Scoped to a specific Domain (e.g., Corporate IT).

Can assign tasks to Contributors.

Assurance-Auditors

Auditor

Read-only view for continuous assessment monitoring.

Compliance verification via X-rays.

Squad-Contributors

Contributor

Read/Write access confined to assigned remediation tasks.

Updates locked upon item submission.

1. Setting Up User Groups and Mapping
   
   Follow this step-by-step procedure to establish account permissions within the platform:

Step 1: Group Creation & Scope Assignment

1. Navigate to System > User Groups within the main navigation panel.

2. Click Create User Group to launch the form layout.

3. Configure fields precisely following the platform's metadata constraint order:

   • Name: Enter a clear, functional name (e.g., Finance-Domain-Managers).

   • Description: Document the intended audience and operational intent.

   • Domain / Perimeter: Pin the group to its specific organizational boundary to prevent permission bleed.

Step 2: External Single Sign-On (SSO) Mapping

If utilizing Single Sign-On integration (Microsoft Entra ID or Google Cloud Identity) via OIDC or SAML:

1. Register the application within your corporate Identity Provider (IdP).

2. Configure your IdP to include group claims in the token payload.

3. In CISO Assistant, link the external Group Object ID to the corresponding local User Group. Users will automatically sync to their mapped roles upon first login.

Step 3: Lifecycle and Account Termination

• Quarterly Access Reviews: Per policy, access configurations must be reviewed quarterly. Use the user count telemetry (ciso_assistant_nb_users) exposed by the Prometheus Metrics Server (python manage.py metrics_server) to audit baseline shifts.

• Account Termination: Access must be immediately revoked or decoupled from the Active Domain upon employee offboarding or role adjustment.

1. Data Quality Assurance via X-Rays
   
   Before finalizing permissions, run the X-rays tool to identify critical identity gaps:

Ownership Gap Warning: Flags any active perimeters, assets, or compliance assessments that lack an assigned Owner or Manager. Always verify every domain has a distinct point of operational accountability mapped to a valid user account.

User Group Access Review Checklist & Guide

This checklist provides a structured framework for conducting your first Quarterly Access Review within CISO Assistant, ensuring adherence to your organization's Access Control Policy. It outlines the exact step-by-step verification process to map identities to operational roles safely across your domains.1

Part 1: Automated Pre-Flight Metrics & Telemetry

Before launching the manual validation workflow, collect baseline user distribution statistics via your backend environment.

• Expose Performance Data: Start the standalone HTTP metrics server to cleanly separate monitoring from your active interface by running:1

• python manage.py metrics_server --port 8001

• 
  

• Collect Identity Baseline: Access http://localhost:8001/metrics and document the instance value for ciso_assistant_nb_users. This establishes an unalterable count of total registered profiles in the system.1

• Verify Infrastructure Health: Ensure that ciso_assistant_nb_domains and ciso_assistant_nb_perimeters explicitly match your production topology map.1

Part 2: The Core Review Workflow

1. Identity Lifetime & Offboarding Validation

• Revocation Check: Cross-reference active user list items against HR employment rosters. Ensure that any employee or contractor whose assignment has terminated has had their unique identifier immediately disabled or deleted.1

• Role Adjustment Sync: Audit accounts of internal transfers. Verify that rights were modified during role shifts to eliminate lingering permissions from past assignments.1

• Inactivity Pruning: Identify and disable any dormant account that has exceeded 90 days of continuous inactivity.1

2. Least-Privilege & Role Mapping Integrity

• Unique Identifier Rule: Verify that no shared or generic accounts are being used to access system perimeters. Every user must utilize an isolated, named identity profile.1

• MFA Enforcement Review: Ensure that multi-factor authentication (MFA) is actively required for all accounts mapped to the Manager role, as well as any remote users.1

• Privileged Access Auditing: Confirm that all actions executed by accounts within the Global-Admins or Domain-Managers groups are cleanly captured by your log forwarders. Ensure that credentials for these privileged roles are held securely within your corporate password vault.1

Part 3: Access Certification Sign-Off Matrix

Use this operational table to log the quarterly status of your domain groups:

Evaluated User Group

Target Domain Role

Authorization Verification Rule

Review Status (Pass/Fail)

Action Required

Global-Admins

Instance Superuser

MFA active; vault storage verified; named personnel assignment.1

Domain-Managers

Manager1

Write and task delegation capabilities strictly confined to specific perimeter folders.1

Assurance-Auditors

Auditor1

Read-only configuration active across selected compliance frameworks.1

Squad-Contributors

Contributor1

Access restricted entirely to assigned remediation tasks.1

Part 4: Post-Review Quality Assurance via X-Rays

Conclude the review cycle by running a system integrity scan to identify structural gaps:

• Resolve Ownership Gaps: Filter for warnings flagged by the X-Rays Engine indicating active perimeters, assets, or compliance campaigns that lack a designated Owner or Manager. Every core object must be explicitly linked back to an active, audited user account.1

To automate the mapping of your Identity Provider (IdP) user attributes and directory groups directly to CISO Assistant's Role-Based Access Control (RBAC) model, follow this technical implementation guide for both SAML 2.0 and OpenID Connect (OIDC) environments.12

Group Claims with IDP

Step 1: Configure Group Claims in Your Identity Provider

Before CISO Assistant can parse group memberships, your Identity Provider must be explicitly configured to release them as a standard claim string attribute in the authentication token.1

For Microsoft Entra ID (Azure AD)

1. Navigate to the App Registrations panel and select your registered CISO Assistant GRC application.3

2. Under Token configuration, click Add groups claim.

3. Select the group types you want to include (e.g., Security groups or All groups).

4. Expand the Source Attribute dropdown for each token type (ID, Access, SAML) and enforce Group ID (this passes the immutable Object ID URN) or NetBIOS domain\Group name depending on your mapping preference.

For Google Workspace (Cloud Identity)

1. From the custom CISO Assistant GRC SAML application settings in admin.google.com, advance to the Attribute Mapping screen.14

2. Click Add Mapping to establish a new custom field entry.

3. Google Application Attribute: Select Employee Details > Groups.

4. App Attribute (Claim Name): Input exactly memberOf or groups. This defines the exact text key CISO Assistant looks for in the assertion payload.4

Step 2: Establish Single Sign-On Mapping Environment

Your container stack utilizes the environmental layout configuration file to intercept these group claims and parse permissions automatically at the application layer.4

1. Establish an active remote terminal terminal connection to your host VPS via PuTTY.34

2. Navigate into your primary application deployment folder:

3. cd /opt/ciso-assistant

4. 
   

5. Open your live runtime secrets configuration file:

6. sudo nano .env

7. 
   

8. Depending on your active authentication mechanism, verify that your claim keys match your Identity Provider's token output strings:12

   • For SAML 2.0 Deployments:14

SAML_ENABLED=True

SAML_PROVIDER_NAME=GoogleSAML

SAML_SP_ENTITY_ID=https://grc-emfris.emfris.co.uk/

SAML_IDP_CERT_PATH=/app/certs/google_saml.crt

# Map the incoming SAML attribute block key

8. • SAML_GROUP_ATTRIBUTE_NAME=memberOf

   • 
     

   • For OIDC / OpenID Connect Deployments:24

OIDC_ENABLED=True

OIDC_PROVIDER_NAME=Google

OIDC_CLIENT_ID=your_google_client_id.apps.googleusercontent.com

OIDC_CLIENT_SECRET=your_google_client_secret

# Specify the scopes required to fetch group metrics

8. • OIDC_SCOPE=openid profile email groups

   • 
     

9. Save the parameters and exit the editor (Ctrl + O, Enter, Ctrl + X).4

Step 3: Link External Group IDs to CISO Assistant Roles

Once tokens are flowing into the application space, you link the external directory entities to the system permissions using the platform's user group synchronization module.

1. Access your web environment with your master system administrator account via the local login backdoor path.34

2. Navigate to System > User Groups using the primary sidebar navigation panel.

3. Locate the corresponding scoped user group matching your target operational bounds (e.g., Finance-Domain-Managers).

4. Click Edit to adjust the metadata fields:

   • External Group ID / Mapping Key: Input the exact string value provided by your identity provider token.

     • For Entra ID: Paste the alphanumeric string representing the Azure Object ID (e.g., 12345678-abcd-1234-efgh-1234567890ab).

     • For Google Cloud Identity: Input the exact text string name of the Google group (e.g., grc-managers@emfris.co.uk).

5. Save the group object configuration.

Step 4: Verification & Runtime Synchronization

The user synchronization engine evaluates permissions dynamically upon user interaction.2

┌────────────────────────┐      Allows Access       ┌────────────────────────┐

│   User Authenticates   │─────────────────────────►│ CISO Assistant Parses  │

│  via IdP Identity SSO  │                          │  Dynamic Group Claims  │

└────────────────────────┘                          └───────────┬────────────┘

                                                                │

                                                                ▼

┌────────────────────────┐   Restricts View to      ┌────────────────────────┐

│  Permissions Revoked   │◄─────────────────────────┤ Matches Mapped ID to   │

│   on Token Expiration  │   Active Domain Scope    │ Scoped User Group Role │

└────────────────────────┘                          └────────────────────────┘

1. Instruct an internal staff user to visit your production domain endpoint at https://grc-emfris.emfris.co.uk.3

2. Have them execute an authentication challenge by clicking Login with SAML or Login with OIDC.23

3. The platform instantly inspects the token attributes, maps their identity to the corresponding group key, and provisions their scoped environment automatically.2

4. To monitor structural access issues, navigate to the X-Rays dashboard to ensure no newly synchronized profiles create an Ownership Gap or handle unmapped assets.

Troubleshooting

Troubleshooting Dynamic Directory Group Mapping Single Sign-On token validation errors and missing group claims occur when the token configuration inside your Identity Provider (IdP) diverges from the runtime .env string mappings defined on your host server. Follow this structural matrix to diagnose and fix synchronization failures.

1. Verification of the Token Payload Structure

Before altering local configurations, verify that the Identity Provider is genuinely passing directory groups in the secure token string.

# Extract your active JWT token string from the network browser console and execute a clean local text parse

# Replace token.txt with your raw copied base64 token payload block

cat token.txt | cut -d'.' -f2 | base64 --decode 2>/dev/null | jq

What to look for in the JSON output:

• For Entra ID (OIDC): Verify an array named "groups" exists containing the exact alphanumeric Object IDs of your directory groups (e.g., ["12345678-abcd-1234-efgh-1234567890ab"]).

• For Google/Generic SAML: Verify a block matching your specified XML attribute key exists, structured as:

"[link removed]": [

  "grc-managers@emfris.co.uk"

• ]

• 
  

2. Synchronization Logs & Common Failure Codes

Access your live container logs to identify the exact rejection mechanism thrown by the authentication module during user interaction:

# Stream the real-time backend API log output to trap authentication exceptions

sudo docker compose logs -f backend

Diagnostic Error Profiles

[AUTH_ERROR] SAML Response lacks attribute specified in SAML_GROUP_ATTRIBUTE_NAME

• Root Cause: The key name in your host .env file does not match the actual string attribute key sent by your IdP.

• Remediation: Check your /opt/ciso-assistant/.env file. If Google Workspace passes the claim as memberOf, ensure SAML_GROUP_ATTRIBUTE_NAME=memberOf is set perfectly.

[AUTH_ERROR] User authenticated but holds no group memberships matching mapped External Group IDs

• Root Cause: The user successfully logged in via single sign-on, but their IdP directory groups do not match any External Group ID strings saved in System > User Groups.

• Remediation: Open the User Groups page in the web interface, edit your group (e.g., Finance-Domain-Managers), and verify the External Group ID exactly matches the token value (use the raw Azure Object ID string, not the friendly group name, if utilizing Entra ID).

3. Identity Provider Certificate Mismatches

If your Single Sign-On process fails completely with a cryptographic validation error before mapping groups, your public key token may be invalid or corrupt.

[CRYPTO_ERROR] SAML Signature verification failed / Signature validation handler caught Exception

1. Open your local certificate repository file:

2. sudo nano /opt/ciso-assistant/certs/google_saml.crt

3. 
   

4. Ensure the file begins exactly with -----BEGIN CERTIFICATE----- on its own line and ends with -----END CERTIFICATE----- on its own line.

5. If your Identity Provider rotated its keys, download the fresh .pem or .crt metadata file from your IdP dashboard and paste the updated block cleanly into the cert path.

4. Post-Correction Stack Reset

Whenever adjustments are made to your host .env file or cryptographic certificates, you must perform a clean container recycle to force the configuration layers to reload into system memory:

# Move to your deployment root directory

cd /opt/ciso-assistant

# Down the containers and recreate the stack with fresh environment maps

sudo docker compose down

sudo docker compose up -d --force-recreate

Once the stack finishes booting, log into the dashboard with your Master Backdoor administrator account. Check the X-Rays interface to confirm that your newly synchronized user profiles are cleanly integrated without causing any Ownership Gaps over your active perimeters and assets.