Admin Commands
Administrative commands provide system-wide management capabilities for GrantFlow administrators. These commands let you manage identity connectors, monitor agents, track background jobs, and configure roles. All admin commands require the administrator role in your GrantFlow tenant.
Connector Management
Identity connectors link GrantFlow to external identity providers and systems like Azure Entra ID, Active Directory, and cloud platforms. These commands help administrators monitor connector health and trigger synchronization.
grantflow admin connectors list
Display all identity connectors configured in your tenant, showing their type, status, and configuration.
Usage
grantflow admin connectors list [--output table|json|yaml]
Parameters
--output- Output format (default: table)
Example
$ grantflow admin connectors list
ID TYPE NAME ENABLED
conn-entra-1 entra_id Azure Entra ID true
conn-ad-1 active_directory On-Premises AD true
conn-azure-2 azure_apps Azure Applications false
Connector Types
GrantFlow supports several connector types, each integrating with different identity sources:
The entra_id connector synchronizes users, groups, and role assignments from Azure Entra ID (formerly Azure AD). This is the primary connector for cloud-first organizations.
The active_directory connector integrates with on-premises Active Directory domains through the GrantFlow agent. This enables just-in-time access to AD groups and enables account management for Windows systems.
The azure_apps connector manages Azure service principals and application permissions, allowing you to control access to Azure resources through GrantFlow.
Connector Status
The enabled column indicates whether the connector is active. Disabled connectors don't synchronize data or provision access. You might disable a connector temporarily during maintenance or permanently when decommissioning an identity source.
grantflow admin connectors sync
Trigger manual synchronization for a specific connector. This forces an immediate sync rather than waiting for the scheduled sync interval.
Usage
grantflow admin connectors sync <connector-id>
Parameters
<connector-id>(required) - The ID of the connector to synchronize
Example
$ grantflow admin connectors sync conn-entra-1
✓ Connector sync initiated successfully
Synchronization Process
When you trigger a sync, GrantFlow creates a background job that connects to the identity source, retrieves current data, and updates the local database. For large organizations, this process may take several minutes to complete.
The sync operation is asynchronous. The command returns immediately after queueing the job. Use grantflow admin jobs list to monitor the sync's progress and check for errors.
When to Sync Manually
You typically trigger manual sync when you've made changes in the source system and need them reflected in GrantFlow immediately. Common scenarios include:
Adding new users or groups that need immediate access to GrantFlow, modifying group memberships that affect role eligibility, or troubleshooting sync issues by forcing a fresh synchronization.
By default, connectors sync automatically on a schedule configured by your administrators. Manual sync is useful for exceptional cases but shouldn't be necessary for routine operations.
If manual syncs fail consistently, check the connector configuration in the web interface and verify network connectivity to the identity source.
Agent Management
On-premises agents connect GrantFlow to your internal Active Directory domains and enable privileged access management for on-premises resources. These commands help you monitor agent health and connectivity.
grantflow admin agents list
Display all registered agents in your tenant, showing their status, associated connectors, and version information.
Usage
grantflow admin agents list [--output table|json|yaml]
Parameters
--output- Output format (default: table)
Example
$ grantflow admin agents list
ID NAME STATUS CONNECTOR_ID VERSION
agent-dc-01 DC1 Agent online conn-ad-1 0.5.2
agent-dc-02 DC2 Agent offline conn-ad-1 0.5.2
agent-azure-1 Azure Agent online conn-azure-2 0.4.1
Agent Status
The status column shows the current connectivity state of each agent:
An online agent maintains an active connection to the GrantFlow control plane and can execute provisioning jobs. The agent checks in regularly with heartbeat messages.
An offline agent hasn't communicated with the control plane within the expected heartbeat interval. This might indicate network issues, agent service problems, or planned maintenance. Check the agent logs on the host system for details.
An error status means the agent is connected but reported operational issues, such as inability to reach its configured Active Directory domain controller or certificate validation failures.
Agent Versions
The version column shows the agent software version. GrantFlow agents update automatically in most deployments, but some environments require manual updates. If you see version disparities between agents, consider whether you need to update lagging agents to maintain consistency.
Agent version requirements may change with new GrantFlow platform releases. Check the release notes when upgrading the central platform to confirm agent compatibility.
Job Management
Background jobs handle asynchronous operations like directory synchronization, role provisioning, and account management. These commands help administrators monitor job execution and troubleshoot failures.
grantflow admin jobs list
View and filter background jobs to monitor system operations and identify failures requiring attention.
Usage
grantflow admin jobs list [--limit <count>] [--status <status>] [--output table|json|yaml]
Parameters
--limit- Maximum jobs to return (default: 50)--status- Filter by status (pending, running, completed, failed)--output- Output format (default: table)
Example
$ grantflow admin jobs list --status running --limit 50
ID TYPE STATUS CREATED_AT STARTED_AT COMPLETED_AT
job-001 Connector.Sync running 2024-10-24T11:30:00Z 2024-10-24T11:31:00Z -
job-002 Role.Provision running 2024-10-24T11:28:00Z 2024-10-24T11:29:00Z -
Job Types
GrantFlow uses background jobs for various operations:
Connector.Sync jobs synchronize data from identity providers. These run on schedule and can be triggered manually via the connectors sync command.
Role.Provision and Role.Revoke jobs handle just-in-time access provisioning, adding users to groups, assigning Azure roles, or enabling accounts based on activation requests.
Account.Enable and Account.Disable jobs manage privileged account lifecycle, enabling accounts during checkout and disabling them when the checkout expires.
Job Status
Jobs progress through several states during their lifecycle:
A pending job sits in the queue waiting for execution. The job dispatcher assigns pending jobs to appropriate workers or agents based on the job type and tenant.
A running job is currently executing. For most operations, jobs complete within seconds, but complex tasks like full directory synchronization may run for several minutes.
A completed job finished successfully. The completed_at timestamp indicates when execution finished.
A failed job encountered an error and couldn't complete. Check the job details in the web interface to see error messages and stack traces.
Monitoring Failed Jobs
Failed jobs often indicate configuration problems, network connectivity issues, or permission gaps. Common failure scenarios include:
- Connector sync failures due to incorrect credentials or network connectivity
- Provisioning failures when target systems are unavailable
- Permission errors when service accounts lack required privileges
When you see failed jobs, investigate using the web interface's job detail view, which shows complete error messages and helps identify the root cause.
# Check for recent failures
grantflow admin jobs list --status failed --limit 100
Role Management
Administrative role commands provide system-wide visibility into all roles and enable role creation. Regular users can only see roles they're eligible for, but administrators see the complete role catalog.
grantflow admin roles list
Display all roles defined in the tenant, regardless of user eligibility. This gives administrators a comprehensive view of the role catalog.
Usage
grantflow admin roles list [--output table|json|yaml]
Parameters
--output- Output format (default: table)
Example
$ grantflow admin roles list
ID NAME DESCRIPTION MAX_DURATION APPROVERPOLICYID
role-prod-dba Production DBA Prod database admin 480 policy-123
role-azure-contributor Azure Contributor Azure subscription 240 policy-456
role-ad-admin AD Admin Active Directory admin 120 policy-789
Differences from User View
Unlike the standard grantflow roles list command, the admin version shows all roles including:
- Roles with no eligible users currently assigned
- Disabled or archived roles not visible to standard users
- Roles still being configured before assignment
This comprehensive view helps administrators manage the role catalog and troubleshoot assignment issues.
grantflow admin roles create
Create a new privileged role definition. This establishes the role in GrantFlow, after which you can assign it to users and configure approval policies.
Usage
grantflow admin roles create --name <role-name> --connector <connector-id> [--description <description>] [--type <role-type>] [--max-duration <minutes>]
Parameters
--name(required) - Role display name--connector(required) - Connector ID that manages this role--description- Role description (optional)--type- Role type: entraid, activedirectory (default: entraid)--max-duration- Maximum activation duration in minutes (default: 480)
Example
$ grantflow admin roles create \
--name "Production DBA" \
--description "Production database administrator" \
--type entraid \
--connector conn-entra-1 \
--max-duration 480
✓ Role created successfully (ID: role-prod-dba-2024)
Role Types
The role type determines how GrantFlow provisions access when users activate the role:
Entra ID roles integrate with Azure Entra ID, assigning users to Entra ID roles, administrative units, or application roles. These work through the Microsoft Graph API and don't require on-premises agents.
Active Directory roles manage group membership in on-premises AD domains. They require an active GrantFlow agent connected to the domain. When activated, the agent adds the user to the configured AD group.
Maximum Duration
The max duration parameter sets the upper limit for activation requests. Users can request any duration up to this value, but cannot exceed it. Choose durations appropriate to the role's purpose:
- Emergency response roles: 4-8 hours
- Routine administrative tasks: 2-4 hours
- Elevated reading or auditing: 1-2 hours
Shorter durations align better with least-privilege principles and reduce risk exposure.
Next Steps After Creation
After creating a role, you'll typically:
- Configure approver policies through the web interface
- Assign eligible users who can request activation
- Test the activation and provisioning workflow
- Document the role's purpose and usage in your runbooks
The web interface provides more comprehensive role configuration options including custom attributes, connector-specific settings, and policy associations.
Permission Requirements
All admin commands require administrator privileges in your GrantFlow tenant. If you see authorization errors when running these commands, verify that your user account has the administrator role assigned.
Standard users attempting to run admin commands will receive a clear error message indicating insufficient permissions.
Related Topics
- Connector Management - Web interface for connector configuration
- Active Directory Agents - Agent deployment and management
- Connector Jobs - Monitoring and troubleshooting jobs
- Role Management - Creating and managing roles
- Audit Commands - Monitor administrative actions in the audit log