This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Administrator Command Line Interface (CLI) Reference

Administrator CLI documentation.

1: Configuring SAML SSO

`admin`

This section shows how to access help and provides examples for admin.

admin --help

Usage: admin [OPTIONS] COMMAND [ARGS]...

  Users, Roles, Permissions, Groups, SAML and Azure AD management commands.

Options:
  --help  Show this message and exit.

Commands:
  create  Create a resource.
  delete  Delete a resource.
  get     Display one resource.
  list    List resources.
  set     Update fields of a resource.
  test    Test various configurations and connections.

`create`

This section lists the create commands.

The following command shows how to access help and provides examples for create.

admin create --help

Usage: admin create [OPTIONS] COMMAND [ARGS]...

  Create a resource.

Options:
  --help  Show this message and exit.

Commands:
  entra-id                Create Entra ID configuration.
  entra-id-import-groups  Import Entra ID groups with optional member...
  entra-id-import-users   Import Entra ID users with role assignments.
  groups                  Create a new group.
  roles                   Create a new role.
  saml-mappers            Create an attribute mapper for a SAML provider.
  saml-providers          Create a new SAML SSO provider.
  users                   Create a new user.

`create entra-id`

The following command shows how to access help and provides examples for create entra-id.

admin create entra-id --help

Usage: admin create entra-id [OPTIONS]

  Create Entra ID configuration.

  Required Entra ID Setup:
  1. Register an application in Entra ID
  2. Grant Microsoft Graph API permissions:
     - User.Read.All (Application)
     - Group.Read.All (Application) - if importing groups
  3. Create a client secret for the application
  4. Note the Tenant ID, Application (Client) ID, and Client Secret

  Examples:
      admin create entra-id --tenant-id "12345678-1234-1234-1234-123456789012" --client-id "87654321-4321-4321-4321-210987654321" --client-secret "your-secret-here"

Options:
  -t, --tenant-id TEXT      Entra ID Tenant ID  [required]
  -c, --client-id TEXT      Entra ID Application (Client) ID  [required]
  -s, --client-secret TEXT  Entra ID Application Client Secret  [required]
  --enabled / --disabled    Enable/disable configuration
  --help                    Show this message and exit.

`create entra-id-import-users`

The following command shows how to access help and provides examples for create entra-id-import-users.

admin create entra-id-import-users --help

Usage: admin create entra-id-import-users [OPTIONS]

  Import Entra ID users with role assignments.

  Import users from Entra ID into the application with role assignments.
  Users must be provided via JSON data.

  JSON Format:
  {
      "users": [
          {
              "userPrincipalName": "john.doe@company.com",
              "email": "john.doe@company.com",
              "firstName": "John",
              "lastName": "Doe",
              "roles": ["admin", "user"],
              "identityProviders": ["AWS-IDP", "AZURE-IDP"]
          }
      ],
      "dryRun": false
  }

  Examples:
      # Direct JSON input with identity providers
      admin create entra-id-import-users --json-data '{"users":[{"userPrincipalName":"john@company.com","email":"john@company.com","firstName":"John","lastName":"Doe","roles":["user"],"identityProviders":["AWS-IDP","AZURE-IDP"]}]}'

      # Dry run with JSON
      admin create entra-id-import-users --json-data '{"users":[...]}' --dry-run

Options:
  --dry-run             Validate import without creating users
  -j, --json-data TEXT  JSON string with users data to import directly
                        [required]
  --help                Show this message and exit.

`create entra-id-import-groups`

The following command shows how to access help and provides examples for create entra-id-import-groups.

admin create entra-id-import-groups --help

Usage: admin create entra-id-import-groups [OPTIONS]

  Import Entra ID groups with optional member import.

  Import groups from Entra ID into the system with role assignments for members.
  Groups must be provided via JSON data.

  JSON Format:
  {
      "groups": [
          {
              "id": "12345678-1234-1234-1234-123456789012",
              "displayName": "Administrators",
              "description": "Administrative users group",
              "importMembers": true,
              "memberRoles": ["admin", "user"],
              "identityProviders": ["AWS-IDP", "AZURE-IDP"]
          }
      ],
      "dryRun": false
  }

  Examples:
      # Direct JSON input with identity providers
      admin create entra-id-import-groups --json-data '{"groups":[{"id":"12345678-1234-1234-1234-123456789012","displayName":"IT Admins","description":"IT department administrators","importMembers":true,"memberRoles":["admin"],"identityProviders":["AWS-IDP","AZURE-IDP"]}]}'

      # Dry run with JSON
      admin create entra-id-import-groups --json-data '{"groups":[...]}' --dry-run

Options:
  --dry-run             Validate import without creating groups
  -j, --json-data TEXT  JSON string with groups data to import directly
                        [required]
  --help                Show this message and exit.

`create groups`

The following command shows how to access help and provides examples for create groups.

admin create groups --help

Usage: admin create groups [OPTIONS]

  Create a new group.

  Examples:
      admin create groups --name developers --description "Development team"
      admin create groups --name admins --members "john,jane" --roles "admin,user_manager"
      admin create groups --name operators --description "System operators" --members "user1,user2" --roles "operator"

Options:
  -n, --name TEXT         Group name  [required]
  -d, --description TEXT  Group description
  -m, --members TEXT      Comma-separated list of usernames to add as members
  -r, --roles TEXT        Comma-separated list of role names to assign to
                          group
  --help                  Show this message and exit.

`create roles`

The following command shows how to access help and provides examples for create roles.

admin create roles --help

Usage: admin create roles [OPTIONS]

  Create a new role.

  Examples:
      admin create roles --name manager --description "Manager role"
      admin create roles --name admin --permissions "security_officer"
      admin create roles --name operator --description "System operator" --permissions "security_officer"

Options:
  -n, --name TEXT         Role name  [required]
  -d, --description TEXT  Role description
  -p, --permissions TEXT  Comma-separated list of permission names
  --help                  Show this message and exit.

`create saml-mappers`

The following command shows how to access help and provides examples for create saml-mappers.

admin create saml-mappers --help

Usage: admin create saml-mappers [OPTIONS] PROVIDER_ALIAS

  Create an attribute mapper for a SAML provider.

  Examples:
      admin create saml-mappers azure-ad --name email-mapper --mapper-type saml-user-attribute-idp-mapper --attribute-name "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" --user-attribute email
      admin create saml-mappers azure-ad --name role-mapper --mapper-type saml-role-idp-mapper --attribute-value admin --role admin

Options:
  -n, --name TEXT                 Name of the attribute mapper  [required]
  --mapper-type [saml-user-attribute-idp-mapper|saml-role-idp-mapper|saml-advanced-group-idp-mapper|saml-username-idp-mapper]
                                  Type of mapper  [required]
  --sync-mode TEXT                Sync mode for the mapper
  --attribute-name TEXT           SAML attribute name to map from
  --user-attribute TEXT           User attribute to map to
  --attribute-value TEXT          SAML attribute value for role mapping
  --role TEXT                     Role to assign
  --group TEXT                    Group to assign users to
  --template TEXT                 Username template
  --attributes TEXT               Key-value pairs for attribute mapping (JSON
                                  format)
  --help                          Show this message and exit.

`create saml-providers`

The following command shows how to access help and provides examples for create saml-providers.

admin create saml-providers --help

Usage: admin create saml-providers [OPTIONS]

  Create a new SAML SSO provider.

  Examples:
      admin create saml-providers --alias azure-ad --display-name "Azure AD" --config-type metadataUrl --service-provider-entity-id "https://your-saml.com/realms/your-realm" --metadata-url "https://..."
      admin create saml-providers --alias okta --display-name "Okta" --config-type metadataFile --service-provider-entity-id "https://your-saml.com/realms/your-realm" --metadata-file /path/to/metadata.xml

Options:
  -a, --alias TEXT                Unique alias for the SAML provider
                                  [required]
  -d, --display-name TEXT         Display name shown in login pages
                                  [required]
  --config-type [metadataUrl|metadataFile]
                                  Configuration type  [required]
  --service-provider-entity-id TEXT
                                  Service Provider Entity ID  [required]
  --metadata-url TEXT             URL to fetch SAML metadata (for metadataUrl
                                  type)
  --metadata-file FILENAME        Path to SAML metadata XML file (for
                                  metadataFile type)
  --signing-certificate TEXT      X.509 certificate for signing (PEM format
                                  without headers)
  --name-id-format TEXT           NameID Policy Format
  --force-authn / --no-force-authn
                                  Force re-authentication
  --validate-signature / --no-validate-signature
                                  Validate SAML response signatures
  --want-assertions-signed / --no-want-assertions-signed
                                  Require signed assertions
  --want-assertions-encrypted / --no-want-assertions-encrypted
                                  Require encrypted assertions
  --signature-algorithm TEXT      Signature algorithm for SAML requests
  --post-binding-response / --no-post-binding-response
                                  Use POST binding for SAML responses
  --post-binding-authn-request / --no-post-binding-authn-request
                                  Use POST binding for SAML authentication
                                  requests
  --post-binding-logout / --no-post-binding-logout
                                  Use POST binding for SAML logout requests
  --want-authn-requests-signed / --no-want-authn-requests-signed
                                  Sign SAML authentication requests
  --attribute-mapping TEXT        Attribute mapping as JSON string or
                                  key=value pairs
  --enabled / --disabled          Enable/disable the provider
  --store-token / --no-store-token
                                  Store tokens returned by the identity
                                  provider
  --help                          Show this message and exit.

Note: The --metadata-file option is not supported. You cannot upload or copy the metadata file. Instead, use the --metadata-url option to configure SAML.

`create users`

The following command shows how to access help and provides examples for create users.

admin create users --help

Usage: admin create users [OPTIONS]

  Create a new user.

  Examples:
      admin create users --username john.doe --email john@example.com --password "StrongPass123!"
      admin create users --username jane --email jane@example.com --password "SecurePass123!" --first-name Jane --last-name Smith --roles "admin,user"
      admin create users --username alpha --email alpha@example.com --password "AlphaPass123!" --identity-provider "AWS-IDP:alpha@example.com:alpha@example.com"
      admin create users --username beta --password "BetaPass123!" --identity-provider "AWS-IDP:beta@example.com:beta@example.com" --identity-provider "AZURE-IDP:beta@azure.com:beta"

Options:
  -u, --username TEXT       Username  [required]
  -e, --email TEXT          Email address
  --first-name TEXT         First name
  --last-name TEXT          Last name
  -p, --password TEXT       Password
  --roles TEXT              Comma-separated list of role names
  --groups TEXT             Comma-separated list of group names
  --identity-provider TEXT  Identity provider in format:
                            PROVIDER_NAME:userId:userName (can be specified
                            multiple times)
  --help                    Show this message and exit.

`delete`

This section lists the delete commands.

The following command shows how to access help and provides examples for delete.

admin delete --help

Usage: admin delete [OPTIONS] COMMAND [ARGS]...

  Delete a resource.

Options:
  --help  Show this message and exit.

Commands:
  entra-id        Delete Entra ID configuration.
  groups          Delete a group.
  roles           Delete a role.
  saml-mappers    Delete an attribute mapper for a SAML provider.
  saml-providers  Delete a SAML SSO provider.
  users           Delete a user by ID.

`delete entra-id`

The following command shows how to access help and provides examples for delete entra-id.

admin delete entra-id --help

Usage: admin delete entra-id [OPTIONS]

  Delete Entra ID configuration.

  Warning: This action cannot be undone and will permanently remove
  all stored Entra ID settings.

  Examples:
      admin delete entra-id

Options:
  --help  Show this message and exit.

`delete groups`

The following command shows how to access help and provides examples for delete groups.

admin delete groups --help

Usage: admin delete groups [OPTIONS] GROUP_ID

  Delete a group.

  Examples:
      admin delete groups group-uuid-here
      admin delete groups group-uuid-here --delete-members

Options:
  -d, --delete-members  Delete all members of the group along with the group
  --help                Show this message and exit.

`delete roles`

The following command shows how to access help and provides examples for delete roles.

admin delete roles --help

Usage: admin delete roles [OPTIONS] ROLE_NAME

  Delete a role.

  Examples:
      admin delete roles admin

Options:
  --help  Show this message and exit.

`delete saml-mappers`

The following command shows how to access help and provides examples for delete saml-mappers.

admin delete saml-mappers --help

Usage: admin delete saml-mappers [OPTIONS] PROVIDER_ALIAS MAPPER_ID

  Delete an attribute mapper for a SAML provider.

  Examples:
      admin delete saml-mappers azure-ad mapper-uuid

Options:
  --help  Show this message and exit.

`delete saml-providers`

The following command shows how to access help and provides examples for delete saml-providers.

admin delete saml-providers --help

Usage: admin delete saml-providers [OPTIONS] ALIAS

  Delete a SAML SSO provider.

  Examples:
      admin delete saml-providers azure-ad

Options:
  --help  Show this message and exit.

`delete users`

The following command shows how to access help and provides examples for delete users.

admin delete users --help

Usage: admin delete users [OPTIONS] USER_ID

  Delete a user by ID.

  Examples:
      admin delete users USER_ID

Options:
  --help  Show this message and exit.

`get`

This section lists the get commands.

The following command shows how to access help and provides examples for get.

admin get --help

Usage: admin get [OPTIONS] COMMAND [ARGS]...

  Display one resource.

Options:
  --help  Show this message and exit.

Commands:
  email            Get current SMTP configuration.
  email-health     Get detailed health status of the email service.
  email-log        Get current log level.
  email-version    Get email version information.
  entra-id         Get current Entra ID configuration.
  groups           Get detailed information about a specific group.
  log-level        Get current log level from the backend.
  password_policy  Get current password policy configuration.
  roles            Get detailed information about a specific role.
  saml-mappers     Get detailed information about a SAML provider...
  saml-providers   Get detailed information about a specific SAML provider.
  users            Get detailed information about a specific user.
  version          Get application version information.

`get email`

The following command shows how to access help and provides examples for get email.

admin get email --help

Usage: admin get email [OPTIONS]

  Get current SMTP configuration.

  Examples:
      admin get email

Options:
  --help  Show this message and exit.

`get email-health`

The following command shows how to access help and provides examples for get email-health.

admin get email-health --help

Usage: admin get email-health [OPTIONS]

  Get detailed health status of the email service.

  Examples:
      admin get email-health

Options:
  --help  Show this message and exit.

`get email-log`

The following command shows how to access help and provides examples for get email-log.

admin get email-log --help

Usage: admin get email-log [OPTIONS]

  Get current log level.

  Examples:
      admin get email-log

Options:
  --help  Show this message and exit.

`get email-version`

The following command shows how to access help and provides examples for get email-version.

admin get email-version --help

Usage: admin get email-version [OPTIONS]

  Get email version information.

  Examples:
      admin get email-version

Options:
  --help  Show this message and exit.

`get entra-id`

The following command shows how to access help and provides examples for get entra-id.

admin get entra-id --help

Usage: admin get entra-id [OPTIONS]

  Get current Entra ID configuration.

  Examples:
      admin get entra-id

Options:
  --help  Show this message and exit.

`get groups`

The following command shows how to access help and provides examples for get groups.

admin get groups --help

Usage: admin get groups [OPTIONS] GROUP_ID

  Get detailed information about a specific group.

  Examples:
      admin get groups group-uuid-here
      admin get groups developers

Options:
  --help  Show this message and exit.

`get password_policy`

The following command shows how to access help and provides examples for get password_policy.

admin get password_policy --help

Usage: admin get password_policy [OPTIONS]

  Get current password policy configuration.

Options:
  --help  Show this message and exit.

`get roles`

The following command shows how to access help and provides examples for get roles.

admin get roles --help

Usage: admin get roles [OPTIONS] ROLE_NAME

  Get detailed information about a specific role.

  Examples:
      admin get roles admin

Options:
  --help  Show this message and exit.

`get saml-mappers`

The following command shows how to access help and provides examples for get saml-mappers.

admin get saml-mappers --help

Usage: admin get saml-mappers [OPTIONS] ALIAS

  Get detailed information about a SAML provider including its mappers.

  Examples:
      admin get saml-mappers azure-ad

Options:
  --help  Show this message and exit.

`get saml-providers`

The following command shows how to access help and provides examples for get saml-providers.

admin get saml-providers --help

Usage: admin get saml-providers [OPTIONS] ALIAS

  Get detailed information about a specific SAML provider.

  Examples:
      admin get saml-providers tttt
      admin get saml-providers azure-ad-saml

Options:
  --help  Show this message and exit.

`get users`

The following command shows how to access help and provides examples for get users.

admin get users --help

Usage: admin get users [OPTIONS] USER_ID

  Get detailed information about a specific user.

  Examples:
      admin get users USER_ID
      admin get users 12345-uuid

Options:
  --help  Show this message and exit.

`get version`

The following command shows how to access help and provides examples for get version.

admin get version --help

Usage: admin get version [OPTIONS]

  Get application version information.

  Examples:
      admin get version

Options:
  --help  Show this message and exit.

`get log-level`

The following command shows how to access help and provides examples for get log-level.

admin get log-level --help

Usage: admin get log-level [OPTIONS]

  Get current log level from the backend.

  Examples:
      admin get log-level

Options:
  --help  Show this message and exit.

`list`

This section lists the list commands.

The following command shows how to access help and provides examples for list.

admin list --help

Usage: admin list [OPTIONS] COMMAND [ARGS]...

  List resources.

Options:
  --help  Show this message and exit.

Commands:
  entra-id-group-members  Search Entra ID group members.
  entra-id-groups         Search Entra ID groups.
  entra-id-users          Search Entra ID users.
  groups                  List all groups with their members and roles.
  permissions             List all available permissions.
  roles                   List all roles.
  saml-mappers            List all attribute mappers for a SAML provider.
  saml-providers          List all SAML SSO providers.
  users                   List all users.

`list entra-id-group-members`

The following command shows how to access help and provides examples for list entra-id-group-members.

admin list entra-id-group-members --help

Usage: admin list entra-id-group-members [OPTIONS]

  Search Entra ID group members.

  Search for members of a specific Entra ID group.

  Search Parameters:
  - Group ID: Required group unique identifier (GUID) - case-sensitive
  - Search Query: Optional filter for members (searches name and email fields)

  Examples:
      admin list entra-id-group-members --group-id "12345678-1234-1234-1234-123456789012"
      admin list entra-id-group-members --group-id "87654321-4321-4321-4321-210987654321" --search "john"
      admin list entra-id-group-members -g "group-guid-here" -s "admin"

Options:
  -g, --group-id TEXT  Group unique identifier (GUID)  [required]
  -s, --search TEXT    Search query to filter group members
  --help               Show this message and exit.

`list entra-id-groups`

The following command shows how to access help and provides examples for list entra-id-groups.

admin list entra-id-groups --help

Usage: admin list entra-id-groups [OPTIONS]

  Search Entra ID groups.

  Search across displayName field.
  If no search query provided, returns all groups.

  Pagination:
  - Use --max to control number of results per page (max: 999)
  - Use --first to skip results (offset)
  - Response shows if more results are available

  Examples:
      # Get first 100 groups (default)
      admin list entra-id-groups

      # Search with default pagination
      admin list entra-id-groups --search "admin"

      # Get first 500 groups
      admin list entra-id-groups --max 500

      # Get maximum groups per page (999)
      admin list entra-id-groups --max 999

      # Get next page of results
      admin list entra-id-groups --max 999 --first 999

      # Search with custom pagination
      admin list entra-id-groups --search "IT" --max 500 --first 0


  To fetch all groups:
      # Loop through pages until no more results
      admin list entra-id-groups --max 999 --first 0
      admin list entra-id-groups --max 999 --first 999
      admin list entra-id-groups --max 999 --first 1998
      # ... continue until "More results available" is not shown

Options:
  -s, --search TEXT    Search query to find groups
  -m, --max INTEGER    Maximum number of groups to return (default: 100, max:
                       999)
  -f, --first INTEGER  Offset for pagination (default: 0)
  --help               Show this message and exit.

`list entra-id-users`

The following command shows how to access help and provides examples for list entra-id-users.

admin list entra-id-users --help

Usage: admin list entra-id-users [OPTIONS]

  Search Entra ID users.

  Search across userPrincipalName, givenName, surname, and mail fields.
  If no search query provided, returns all enabled users.

  Pagination:
  - Use --max to control number of results per page (max: 999)
  - Use --first to skip results (offset)
  - Response shows if more results are available

  Examples:
      # Get first 100 users (default)
      admin list entra-id-users

      # Search with default pagination
      admin list entra-id-users --search "john"

      # Get first 500 users
      admin list entra-id-users --max 500

      # Get maximum users per page (999)
      admin list entra-id-users --max 999

      # Get next page of results
      admin list entra-id-users --max 999 --first 999

      # Search with custom pagination
      admin list entra-id-users --search "smith" --max 500 --first 0


  To fetch all users:
      # Loop through pages until no more results
      admin list entra-id-users --max 999 --first 0
      admin list entra-id-users --max 999 --first 999
      admin list entra-id-users --max 999 --first 1998
      # ... continue until "More results available" is not shown

Options:
  -s, --search TEXT    Search query to find users
  -m, --max INTEGER    Maximum number of users to return (default: 100, max:
                       999)
  -f, --first INTEGER  Offset for pagination (default: 0)
  --help               Show this message and exit.

`list groups`

The following command shows how to access help and provides examples for list groups.

admin list groups --help

Usage: admin list groups [OPTIONS]

  List all groups with their members and roles.

  Examples:
      admin list groups
      admin list groups --max 10
      admin list groups --max 5 --first 10

Options:
  -m, --max INTEGER    Maximum number of groups to return
  -f, --first INTEGER  Offset for pagination
  --help               Show this message and exit.

`list permissions`

The following command shows how to access help and provides examples for list permissions.

admin list permissions --help

Usage: admin list permissions [OPTIONS]

  List all available permissions.

  Examples:
      admin list permissions
      admin list permissions --filter "read*"

Options:
  -f, --filter TEXT  Filter permissions by name pattern
  --help             Show this message and exit.

`list roles`

The following command shows how to access help and provides examples for list roles.

admin list roles --help

Usage: admin list roles [OPTIONS]

  List all roles.

  Examples:
      admin list roles

Options:
  --help  Show this message and exit.

`list saml-mappers`

The following command shows how to access help and provides examples for list saml-mappers.

admin list saml-mappers --help

Usage: admin list saml-mappers [OPTIONS] PROVIDER_ALIAS

  List all attribute mappers for a SAML provider.

  Examples:
      admin list saml-mappers azure-ad

Options:
  --help  Show this message and exit.

`list saml-providers`

The following command shows how to access help and provides examples for list saml-providers.

admin list saml-providers --help

Usage: admin list saml-providers [OPTIONS]

  List all SAML SSO providers.

  Examples:
      admin list saml-providers

Options:
  --help  Show this message and exit.

`list users`

The following command shows how to access help and provides examples for list users.

admin list users --help

Usage: admin list users [OPTIONS]

  List all users.

  Examples:
      admin list users
      admin list users --max 10
      admin list users --max 5 --first 10

Options:
  -m, --max INTEGER    Maximum number of users to return
  -f, --first INTEGER  Offset for pagination
  --help               Show this message and exit.

`set`

This section lists the set commands.

The following command shows how to access help and provides examples for set.

admin set --help

Usage: admin set [OPTIONS] COMMAND [ARGS]...

  Update fields of a resource.

Options:
  --help  Show this message and exit.

Commands:
  email            Update SMTP configuration.
  email-log        Set application log level.
  entra-id         Update existing Entra ID configuration.
  groups           Update an existing group.
  lock_user        Lock a user account.
  log-level        Update the log level (critical, error, warning, info,...
  password_policy  Update password policy configuration.
  roles            Update an existing role.
  saml-providers   Update an existing SAML SSO provider.
  token            Update access token lifespan and SSO idle timeout.
  unlock_user      Unlock a user account and set a new password.
  update_password  Update user password.
  users            Update an existing user.

`set email`

The following command shows how to access help and provides examples for set email.

admin set email --help

Usage: admin set email [OPTIONS]

  Update SMTP configuration.

  Examples:
      admin set email -h "smtp.example.com" -p 587 --use-tls -u "app-user" -w "app-password"

Options:
  -h, --smtp-host TEXT     SMTP server hostname  [required]
  -p, --smtp-port INTEGER  SMTP server port  [required]
  --use-tls / --no-tls     Enable/disable TLS
  -u, --username TEXT      SMTP username
  -w, --password TEXT      SMTP password
  --help                   Show this message and exit.

`set email-log`

The following command shows how to access help and provides examples for set email-log.

admin set email-log --help

Usage: admin set email-log [OPTIONS]

  Set email application log level.

  Examples:
      admin set email-log -l debug
      admin set email-log -l info

Options:
  -l, --level [debug|info|warning|error|critical]
                                  Log level to set  [required]
  --help                          Show this message and exit.

`set entra-id`

The following command shows how to access help and provides examples for set entra-id.

admin set entra-id --help

Usage: admin set entra-id [OPTIONS]

  Update existing Entra ID configuration.

  Only provided fields are updated. Configuration is tested if credentials are changed.

  Examples:
      admin set entra-id --enabled
      admin set entra-id --client-secret "new-secret-here"
      admin set entra-id --tenant-id "new-tenant-id" --client-id "new-client-id"

Options:
  -t, --tenant-id TEXT      Update Entra ID Tenant ID
  -c, --client-id TEXT      Update Entra ID Application (Client) ID
  -s, --client-secret TEXT  Update Entra ID Application Client Secret
  --enabled / --disabled    Enable/disable configuration
  --help                    Show this message and exit.

`set groups`

The following command shows how to access help and provides examples for set groups.

admin set groups --help

Usage: admin set groups [OPTIONS] GROUP_ID

  Update an existing group.

  Examples:
      admin set groups group-uuid --members "john,jane,bob"
      admin set groups group-uuid --roles "admin,user_manager"
      admin set groups group-uuid --members "user1,user2" --roles "operator,viewer"
      admin set groups group-uuid --identity-providers "AWS-IDP,AZURE-IDP"
      admin set groups group-uuid --members "john.doe,senior.dev" --roles "senior_admin,lead_developer" --identity-providers "AWS-IDP,AZURE-IDP"

Options:
  -m, --members TEXT             Comma-separated list of usernames (replaces
                                 existing members)
  -r, --roles TEXT               Comma-separated list of role names (replaces
                                 existing roles)
  -i, --identity-providers TEXT  Comma-separated list of identity provider
                                 names (replaces existing providers)
  --help                         Show this message and exit.

`set lock_user`

The following command shows how to access help and provides examples for set lock_user.

admin set lock_user --help

Usage: admin set lock_user [OPTIONS] USER_ID

  Lock a user account.

  Examples:
      admin set lock_user USER_ID

Options:
  --help  Show this message and exit.

`set log-level`

The following command shows how to access help and provides examples for set log-level.

admin set log-level --help

Usage: admin set log-level [OPTIONS] {critical|error|warning|info|debug}

  Update the log level (critical, error, warning, info, debug).

  Examples:
      admin set log-level info
      admin set log-level debug

Options:
  --help  Show this message and exit.

`set password_policy`

The following command shows how to access help and provides examples for set password_policy.

admin set password_policy --help

Usage: admin set password_policy [OPTIONS]

  Update password policy configuration.

Options:
  --policy TEXT  Password policy configuration as JSON string.

                 Common Keys:
                 - length: Minimum password length
                 - digits: Number of digits required
                 - lowerCase: Number of lowercase characters required
                 - upperCase: Number of uppercase characters required
                 - specialChars: Number of special characters required
                 - notUsername: Password cannot be same as username (0 or 1)
                 - passwordHistory: Number of previous passwords to remember
                 - maxLength: Maximum password length

                 Examples:
                     admin set password_policy --policy '{"length": 8, "digits": 1, "upperCase": 1, "specialChars": 1}'
                     admin set password_policy --policy '{"length": 12, "digits": 2, "lowerCase": 1, "upperCase": 1, "specialChars": 2, "notUsername": 1}'
                     admin set password_policy --policy '{"length": 10, "passwordHistory": 5, "maxLength": 128}'   [required]
  --help         Show this message and exit.

`set roles`

The following command shows how to access help and provides examples for set roles.

admin set roles --help

Usage: admin set roles [OPTIONS] ROLE_NAME

Update an existing role.

Examples:
    admin set roles admin --description "Updated admin role"
    admin set roles manager --permissions "security_officer"
    admin set roles operator --description "System operator" --permissions "security_officer"

Options:
  -d, --description TEXT  New role description
  -p, --permissions TEXT  Comma-separated list of permission names (replaces existing)
  --help                  Show this message and exit.
             Show this message and exit.

`set saml-providers`

The following command shows how to access help and provides examples for set saml-providers.

admin set saml-providers --help

Usage: admin set saml-providers [OPTIONS] ALIAS

  Update an existing SAML SSO provider.

  Only the parameters you explicitly provide will be updated.

  Examples:
      admin set saml-providers azure-ad --display-name "New Azure AD"
      admin set saml-providers Test --enabled
      admin set saml-providers Test --disabled
      admin set saml-providers Test --force-authn
      admin set saml-providers Test --no-validate-signature
      admin set saml-providers Test --metadata-url "https://new-metadata-url.com"
      admin set saml-providers Test --signature-algorithm "RSA_SHA512"

Options:
  -d, --display-name TEXT         Update display name for the provider
  --config-type [metadataUrl|metadataFile]
                                  Update configuration type
  --service-provider-entity-id TEXT
                                  Update Service Provider Entity ID
  --metadata-url TEXT             Update metadata URL
  --metadata-file FILENAME        Update metadata file content
  --signing-certificate TEXT      Update signing certificate
  --name-id-policy-format TEXT    Update NameID Policy Format
  --force-authn                   Enable force authentication
  --no-force-authn                Disable force authentication
  --validate-signature            Enable signature validation
  --no-validate-signature         Disable signature validation
  --want-assertions-signed        Require signed assertions
  --no-want-assertions-signed     Don't require signed assertions
  --want-assertions-encrypted     Require encrypted assertions
  --no-want-assertions-encrypted  Don't require encrypted assertions
  --signature-algorithm TEXT      Update signature algorithm
  --post-binding-response         Enable POST binding for responses
  --no-post-binding-response      Disable POST binding for responses
  --post-binding-authn-request    Enable POST binding for auth requests
  --no-post-binding-authn-request
                                  Disable POST binding for auth requests
  --post-binding-logout           Enable POST binding for logout
  --no-post-binding-logout        Disable POST binding for logout
  --want-authn-requests-signed    Enable authentication request signing
  --no-want-authn-requests-signed
                                  Disable authentication request signing
  --attribute-mapping TEXT        Update attribute mapping (JSON format)
  --enabled                       Enable the provider
  --disabled                      Disable the provider
  --store-token                   Enable token storage
  --no-store-token                Disable token storage
  --help                          Show this message and exit.

Note: The --metadata-file option is not supported. You cannot upload or copy the metadata file. Instead, use the --metadata-url option to configure SAML.

`set unlock_user`

The following command shows how to access help and provides examples for set unlock_user.

admin set unlock_user --help

Usage: admin set unlock_user [OPTIONS] USER_ID

  Unlock a user account and set a new password.

  Examples:
      admin set unlock_user USER_ID --password "NewPassword123!"
      admin set unlock_user USER_ID -p "StrongPass123!"

Options:
  -p, --password TEXT  New password to set after unlocking  [required]
  --help               Show this message and exit.

`set update_password`

The following command shows how to access help and provides examples for set update_password.

admin set update_password --help

Usage: admin set update_password [OPTIONS] USER_ID

  Update user password.

  Examples:
      admin set update_password USER_ID --new-password "NewPassword123!" --old-password "OldPass123!"
      admin set update_password USER_ID -n "NewPass123!" -o "OldPass123!"

Options:
  -n, --new-password TEXT  New password  [required]
  -o, --old-password TEXT  Current password for validation  [required]
  --help                   Show this message and exit.

`set users`

The following command shows how to access help and provides examples for set users.

admin set users --help

Usage: admin set users [OPTIONS] USER_ID

  Update an existing user.

  Examples:
      admin set users USER_ID --email newemail@example.com
      admin set users USER_ID --roles "admin,manager"
      admin set users USER_ID --identity-provider "AWS-IDP:alpha@example.com:alpha@example.com"
      admin set users USER_ID --identity-provider "AWS-IDP:alpha@example.com:alpha@example.com" --identity-provider "AZURE-IDP:beta@azure.com:beta"

Options:
  -e, --email TEXT          New email address
  --first-name TEXT         New first name
  --last-name TEXT          New last name
  --roles TEXT              Comma-separated list of role names (replaces
                            existing)
  --groups TEXT             Comma-separated list of group names (replaces
                            existing)
  --identity-provider TEXT  Identity provider in format:
                            PROVIDER_NAME:userId:userName (can be specified
                            multiple times, replaces existing)
  --help                    Show this message and exit.

`set token`

The following command shows how to access help and provides examples for set token.

admin set token --help

Usage: admin set token [OPTIONS]

  Update access token lifespan and SSO idle timeout.

  Examples:
      admin set token --lifespan 600
      admin set token --lifespan 1200

Options:
  --lifespan INTEGER RANGE  Access token lifespan in seconds (minimum: 60,
                            maximum: 3600)  [60<=x<=3600; required]
  --help                    Show this message and exit.

`test`

This section lists the test commands.

The following command shows how to access help and provides examples for test.

admin test --help

Usage: admin test [OPTIONS] COMMAND [ARGS]...

  Test various configurations and connections.

Options:
  --help  Show this message and exit.

Commands:
  email     Send an email.
  entra-id  Test Entra ID connection.

`test email`

The following command shows how to access help and provides examples for test email.

admin test email --help

Usage: admin test email [OPTIONS]

  Send an email.

  Examples:
      admin test email -f "sender@example.com" -t "recipient@example.com" -s "Test" -b "This is a test"
      admin test email -f "sender@example.com" -t "recipient@example.com" -c "cc@example.com" --bcc-emails "bcc@example.com" -s "Test" -b "Message"

Options:
  -f, --from-email TEXT  Sender email address  [required]
  -t, --to-emails TEXT   Recipient email address. For multiple recipients,
                         provide a comma-separated list  [required]
  -s, --subject TEXT     Email subject  [required]
  -b, --body TEXT        Email body content  [required]
  -c, --cc-emails TEXT   CC email address. For multiple recipients, provide a
                         comma-separated list
  --bcc-emails TEXT      BCC email address. For multiple recipients, provide a
                         comma-separated list
  --help                 Show this message and exit.

`test entra-id`

The following command shows how to access help and provides examples for test entra-id.

admin test entra-id --help

Usage: admin test entra-id [OPTIONS]

  Test Entra ID connection.

  Test Options:
  1. Test stored configuration: --use-stored
  2. Test provided credentials: --tenant-id, --client-id, --client-secret

  Examples:
      admin test entra-id --use-stored
      admin test entra-id --tenant-id "tenant-id" --client-id "client-id" --client-secret "secret"

Options:
  --use-stored              Test stored configuration
  -t, --tenant-id TEXT      Entra ID Tenant ID (for direct test)
  -c, --client-id TEXT      Entra ID Application (Client) ID (for direct test)
  -s, --client-secret TEXT  Entra ID Application Client Secret (for direct
                            test)
  --help                    Show this message and exit.

1 - Configuring SAML SSO

Steps to configure SAML SSO using the CLI

SAML SSO enables users to authenticate using enterprise‑managed credentials instead of maintaining separate application passwords.

This section describes how to configure SAML Single Sign‑On (SSO) using an external Identity Provider (IdP) in cloud environments such as Entra ID, AWS, and Google Cloud Platform (GCP).

Setting up SAML SSO using the CLI

This section describes how to configure SAML SSO using the PPC CLI.

Prerequisites

Before you begin, ensure the following prerequisites are met:

Access to an IdP.
Administrative privileges to configure SAML settings in the IdP.
Copy the Metadata URL.
Users and groups already created in the IdP.
Administrative access to the PPC CLI.

The same setup flow applies across Entra ID, AWS, and GCP, with differences limited to the IdP administration interface.

Setting up SAML SSO on Entra ID IdP - An Example

To configure SAML SSO on PPC using Entra ID IdP, perform the following steps:

Create a SAML provider using the metadata URL from the IdP using the following command.

admin create saml-providers \
--alias <saml-provider-alias> \
--display-name "<saml-provider-display-name>" \
--config-type metadataUrl \
--service-provider-entity-id "https://<service-provider-entity-id>" \
--metadata-url "https://<idp-metadata-url>" \

Uploading a metadata file is not supported. --metadata-url must be used.

The key parameters are listed below.

--alias: Unique identifier for the SAML provider.
--display-name: Name shown on the login page.
--config-type: Must be metadataUrl.
--service-provider-entity-id: Entity ID expected by the IdP.
--metadata-url: URL from which SAML metadata is fetched.
After successful execution, the following message displays.
```
SAML provider '<saml-provider-alias>' created successfully!
```

Verify if the SAML provider is created successfully using the following command.
```
admin list saml-providers
```
A list of configured SAML providers appears.
After creating the SAML provider, retrieve the SAML provider details to obtain the Redirect URI using the following command.
```
admin get saml-providers <saml-provider-alias>
```
Note the Redirect URI from the displayed information.
Update the SAML configuration in Entra ID Idp.
To update the SAML configuration in the Idp, perform the following steps:
1. Log in to Entra ID IdP.
2. Navigate to Enterprise applications, and select the application.
3. In the Basic SAML Configuration, update the Redirect URI noted in the previous step.
In the PPC CLI, create the Entra ID configuration using the following command.
```
admin create entra-id --tenant-id "<tenant-id>" --client-id "<client-id>" --client-secret "your-secret-here"
```
After successful execution, the following message displays.
```
Entra ID configuration '<tenant-id>' created successfully!
```
This confirms trust is established between the IdP and the appliance.

Import the user from Entra ID IdP using the following command.

admin create entra-id-import-users --json data {
  "users": [
      {
          "userPrincipalName": "john.doe@company.com",
          "email": "john.doe@company.com",
          "firstName": "John",
          "lastName": "Doe",
          "roles": ["security_administrator"],
          "identityProviders": ["Entra ID-IDP"],
          "password": "Password@123"
      }
  ],
}'

After successful execution, the following message displays.

Successfully imported 1 user(s)

Verify if the user is imported using the following command.
```
admin list users
```
A list of all available users display. The imported user appears in the list. Note the USER_ID.
To get detailed information about a user, run the following command.
```
admin get users USER_ID
```
The user details display. The attributes display user type as external, stating that the user is imported from an external IdP.
Open the Web browser and enter the FQDN of the PPC. The Login page displays.
Click Sign in with SAML SSO.
The screen is redirected to the IdP portal for authentication. If the user is not logged in, the login dialog appears. Provide the user credentials for login.
After logging in successfully, the screen automatically redirects to the PPC Dashboard.

SAML SSO is now configured. Users can authenticate using enterprise‑managed credentials and are granted access based on the roles assigned in the PPC.

Creating users for AWS and GCP

This section describes environments where users are created locally using the Admin CLI, rather than being imported from an external IdP. This procedure is applicable to AWS and GCP deployments where SAML SSO is enabled but users are created using the CLI.

Creating local users for AWS and GCP using the CLI

In AWS and GCP environments, administrators can create users directly using the Admin CLI. These users authenticate through the configured SAML provider, while credentials, roles, and access control are managed locally.

To create the users for AWS and GCP using the CLI, perform the following steps:

Configure the SAML provider using the CLI.
Create a local user, set a password, assign one or more roles to define access permissions, using the following command.
```
admin create users \
--username john.doe \
--email john.doe@example.com \
--first-name John \
--last-name Doe \
--password StrongPassword123! \
--roles admin
```
Here,
- The --password parameter sets the initial login password.
- The --roles parameter assigns one or more roles that control user permissions.
The user authenticates via the SAML IdP and is authorized based on locally assigned roles.

To update the roles, run the following command:

admin set users USER_ID --roles admin,operator

To update an existing user password, run the following command:

admin set update_password USER_ID \
--old-password OldPassword123! \
--new-password NewPassword123!

To unlock an account, run the following command:

admin set unlock_user USER_ID --password NewPassword123!

Note: In this process, users are not imported from AWS IAM or GCP IAM. Identity authentication is handled through the SAML provider, while user records, passwords, and role assignments are managed locally through the CLI.

Understanding SAML Mappers

SAML mappers define how attributes received from the SAML Identity Provider (IdP) are mapped to local user attributes, roles, or groups during authentication.

SAML mappers are configured per SAML provider and allow administrators to control how identity data is interpreted and applied within the system.

Why SAML Mappers Are Required

SAML assertions typically contain user attributes such as email, username, group membership, or role indicators. SAML mappers translate these attributes into:

Local usernames
User attributes
Role assignments
Group memberships

Without SAML mappers, users may authenticate successfully but will not be assigned the correct access permissions.

Note: SAML mappers are evaluated during user authentication. Ensure that the IdP sends the required attributes and that mapper definitions align with the IdP’s SAML assertion format.