Manage Authentication Profiles

Use the ZEDEDA CLI (ZCLI) to manage authentication profiles from the command line. This article covers zcli auth-profile commands, with syntax and examples for each operation. An authentication profile determines how users of your enterprise sign in: either with ZEDEDA-native (local) credentials under a password policy that you define, or through an external OIDC-compliant Identity Provider. In the Edge Infrastructure Services console this object is the External Authentication Profile; ZCLI calls it an authorization profile, which is why the command family is auth-profile. This page is the command reference. For the end-to-end single sign-on setup procedure, including realms, child-enterprise inheritance, role mapping, and troubleshooting, see Enable Single Sign-On.

Before You Start

ZCLI is installed and authenticated against your enterprise. See Get Started.
You have the SysManager or SysAdmin role in your enterprise. See Manage Roles. [TBD: verify whether SysRoot is required; the source article lists SysRoot privileges as the prerequisite.]
For GUI-based authentication management, see Enable Single Sign-On and Manage Users.

Profile Types

ZCLI supports two profile types. You set the type with --type when you create the profile, and you cannot change it afterwards. To switch types, create a new profile.

Type	Description
`local`	Users sign in with ZEDEDA-native credentials. The profile defines the password policy (length, character classes, age, history, and expiry notification) that applies to every local user in the enterprise. See Password Policy Parameters.
`oauth`	Users sign in through an external OIDC-compliant Identity Provider, such as Google, Azure AD, or Okta. The profile holds the client ID, client secret, and OpenID Connect endpoint issued by the provider.

An enterprise can hold several authentication profiles, but only one profile can be active at a time. Use --active to put a profile into service and --test-only to validate its credentials without putting it into service. Password policy applies at the enterprise level. You cannot set different password expiry conditions for individual users. If different groups of users need different conditions, place them in separate enterprises.

Password Policy Parameters

A local profile requires all ten password parameters. You can pass them inline as flags or supply them in a JSON file with --password-config. ZCLI validates the values before it sends the request and rejects the command if any value is missing or out of range.

Flag	JSON key	Allowed range	Description
`--min-len`	`min_length`	8 to 64	Password minimum length.
`--max-len`	`max_length`	8 to 64, not less than the minimum length	Password maximum length.
`--min-num-chars`	`min_numeric_chars`	1 to 10	Minimum numeric characters.
`--min-sym-chars`	`min_symbol_chars`	1 to 10	Minimum symbol characters.
`--min-upper-chars`	`min_uppercase_chars`	1 to 10	Minimum uppercase characters.
`--min-lower-chars`	`min_lowercase_chars`	1 to 10	Minimum lowercase characters.
`--max-pwd-age`	`max_password_age`	86400 to 94608000 (1 day to 3 years, in seconds)	Maximum password age.
`--min-pwd-age`	`min_password_age`	86400 to the maximum password age (in seconds)	Minimum password age.
`--num-prev-pwd-check`	`num_prev_password_check`	3 to 24	Number of previous passwords that a new password is checked against.
`--pwd-expiry-notification-period`	`password_expiry_notification_period_in_seconds`	0 to 1728000	Period before expiry during which users are notified. [TBD: verify the unit. The ZCLI help text describes this value in days, but ZCLI stores it in the API field `passwordExpiryNotificationPeriodInSeconds` and accepts values up to 1728000.]

The following is an example passwordconfig.json file for --password-config:

{
  "min_length": 10,
  "max_length": 64,
  "min_numeric_chars": 2,
  "min_symbol_chars": 2,
  "min_uppercase_chars": 2,
  "min_lowercase_chars": 2,
  "max_password_age": 94608000,
  "min_password_age": 86400,
  "num_prev_password_check": 3,
  "password_expiry_notification_period_in_seconds": 604800
}

Manage Authentication Profiles

Create an authentication profile

Create a profile of type local or oauth. A local profile takes the password policy, either inline or from a config file. An oauth profile takes the client ID, client secret, and OpenID Connect endpoint from your Identity Provider.

zcli auth-profile create <name> [--test-only] [--active] --type=[oauth | local] [--jwt-algorithm=[RS256|RS384|RS512]] (--client-id=<client-id> --client-secret=<client-secret> --endpoint=<endpoint> | (--password-config=<config-path> | --min-len=<min-len> --max-len=<max-len> --min-num-chars=<min-num-chars> --min-sym-chars=<min-sym-chars> --min-upper-chars=<min-upper-chars> --min-lower-chars=<min-lower-chars> --max-pwd-age=<max-pwd-age> --min-pwd-age=<min-pwd-age> --num-prev-pwd-check=<num-prev-pwd-check> --pwd-expiry-notification-period=<pwd-expiry-notification-period>)) [--default-role=<role-name> | --disable-auto-user] [--role-scope=<scope>]

Flag	Description
`--type=[oauth \| local]`	Type of the profile. Required, and fixed after creation.
`--active`	Mark the profile as active. Only one profile can be active per enterprise.
`--test-only`	Validate the credentials only, without putting the profile into service.
`--client-id=<client-id>`	OAuth client ID issued by the Identity Provider.
`--client-secret=<client-secret>`	OAuth client secret issued by the Identity Provider.
`--endpoint=<endpoint>`	OpenID Connect endpoint of the Identity Provider.
`--jwt-algorithm=[RS256\|RS384\|RS512]`	Algorithm used to verify the JWT signature of the ID token. Set it on create; `zcli auth-profile update` currently ignores this flag.
`--default-role=<role-name>`	Role attached to OAuth users who are created automatically on first login. The role must already exist. List roles with `zcli role show`.
`--disable-auto-user`	Do not create a user automatically on first login if the user does not exist. Use this instead of `--default-role`.
`--role-scope=<scope>`	Name of the ID-token claim that carries role names for OAuth users.
`--password-config=<config-path>`	Path to a JSON file with the password parameters for a `local` profile. See Password Policy Parameters.

When you create a local profile, ZCLI always disables automatic user creation and does not attach a default role, because local users are created explicitly by an administrator. An update can turn automatic user creation back on. See Update an authentication profile. Example of an OAuth profile that is activated immediately:

zcli auth-profile create MY_AUTH_PROFILE --type=oauth --active --client-id=MY_CLIENT_ID --client-secret=MY_CLIENT_SECRET --endpoint="https://accounts.google.com" --default-role=SysAdmin

Example of a local profile with the password policy passed inline:

zcli auth-profile create MY_AUTH_PROFILE --type=local --min-len=10 --max-len=64 --min-num-chars=2 --min-sym-chars=2 --min-upper-chars=2 --min-lower-chars=2 --max-pwd-age=94608000 --min-pwd-age=86400 --num-prev-pwd-check=3 --pwd-expiry-notification-period=604800

Example of a local profile with the password policy read from a file:

zcli auth-profile create MY_AUTH_PROFILE --type=local --password-config=passwordconfig.json

View an authentication profile

List all profiles in the enterprise, filter the list by a name substring, or show one profile by name or UUID.

zcli auth-profile show [[[<name> | --uuid=<uuid>] [--detail]] | [[--name-pattern=<name-pattern>] [--page-size=<page-size>]]]

Flag	Description
`--detail`	Show the full configuration of the profile.
`--uuid=<uuid>`	Select the profile by UUID instead of name.
`--name-pattern=<name-pattern>`	Match all profiles whose name contains this substring.
`--page-size=<page-size>`	Number of records returned per API call. ZCLI still retrieves the full list; a smaller page size only increases the number of calls and reduces the chance of a timeout.

Example of listing every profile:

zcli auth-profile show

Example of filtering by name:

zcli auth-profile show --name-pattern=okta

Example of viewing the full configuration of one profile:

zcli auth-profile show MY_AUTH_PROFILE --detail

Example response for a local profile:

ID: 6e26442f-2c7e-4590-bd80-ca33b7919984
Name: MY_AUTH_PROFILE
Type: AUTH_TYPE_LOCAL
TestOnly: False
Active: True
DefaultRole:

MinLength: 10
MaxLength: 64
MinNumericChars: 2
MinSymbolChars: 2
MinUppercaseChars: 2
MinLowercaseChars: 2
MaxPasswordAge: 94608000
MinPasswordAge: 86400
NumPrevPasswordCheck: 3
PasswordExpiryNotificationPeriodInSeconds: 604800

Version: 1
Created at: Sun Mar 30 2025 05:50:39 AM
Created By: user@zededa.com
Last Updated at: Sun Mar 30 2025 05:50:39 AM
Last Updated By: user@zededa.com

For an OAuth profile, the detail view shows the OpenID Connect endpoint, client ID, role scope, and JWT algorithm instead of the password parameters. The client secret is never displayed. To print the unformatted API record, for example to inspect the disableAutoUserCreate field, use the global --format=raw option:

zcli --format=raw auth-profile show MY_AUTH_PROFILE --detail

Update an authentication profile

Change the settings of an existing profile. ZCLI retrieves the current record, applies the values you pass, and writes the whole record back. You cannot change the profile type; create a new profile instead.

zcli auth-profile update <name> [--test-only] [--active] [--jwt-algorithm=[RS256|RS384|RS512]] (--client-secret=<client-secret> [--client-id=<client-id>] [--endpoint=<endpoint>] | (--password-config=<config-path> | [--min-len=<min-len>] [--max-len=<max-len>] [--min-num-chars=<min-num-chars>] [--min-sym-chars=<min-sym-chars>] [--min-upper-chars=<min-upper-chars>] [--min-lower-chars=<min-lower-chars>] [--max-pwd-age=<max-pwd-age>] [--min-pwd-age=<min-pwd-age>] [--num-prev-pwd-check=<num-prev-pwd-check>] [--pwd-expiry-notification-period=<pwd-expiry-notification-period>])) [--role-scope=<scope>] [--default-role=<role-name>] [--disable-auto-user]

Keep the following in mind:

Every update rewrites the active and test-only settings of the profile. If you omit --active from an update command, the profile becomes inactive. Pass --active on every update to a profile that must stay in service.
For a local profile, you only need to pass the password parameters that you want to change. ZCLI validates the merged policy against the allowed ranges before it sends the update.
For an oauth profile, --client-secret is required on every update, because the secret is not returned by the show command and cannot be carried over.
Every update also rewrites the automatic user creation setting, for both local and oauth profiles. Passing --disable-auto-user turns automatic user creation off. Omitting it turns automatic user creation on, even for a local profile that was created with it off. Pass --disable-auto-user on every update to a local profile, and on every update to an oauth profile that must not create users automatically.
--default-role sets the role attached to users who are created automatically, as it does on create.
In the current version of ZCLI, zcli auth-profile update ignores --jwt-algorithm. The command succeeds, but the JWT algorithm of the profile does not change. ZCLI sends --jwt-algorithm only when you create a profile, so choose the algorithm when you run zcli auth-profile create.

Example of activating a profile:

zcli auth-profile update MY_AUTH_PROFILE --active

Example of changing the maximum password age while keeping the profile active:

zcli auth-profile update MY_AUTH_PROFILE --active --max-pwd-age=63072000

Example of replacing the whole password policy from a file:

zcli auth-profile update MY_AUTH_PROFILE --active --password-config=passwordconfig.json

Example of rotating the client secret of an OAuth profile:

zcli auth-profile update MY_AUTH_PROFILE --active --client-secret=MY_NEW_CLIENT_SECRET

Delete an authentication profile

Delete a profile by name. ZCLI asks for confirmation unless you pass -f. Deleting the active OAuth profile disables single sign-on for the enterprise, and local user creation becomes available again.

zcli auth-profile delete <name> [-f]

Example:

zcli auth-profile delete MY_AUTH_PROFILE -f

Next Steps

Enable Single Sign-On

End-to-end OIDC setup, including realms, enterprise inheritance, and role mapping.

Manage Users

Create local users and review users provisioned through SSO.

Manage Roles

Create and assign the roles referenced by --default-role.

Overview

All ZCLI command procedures, organized by resource type.

Get started

Infrastructure

Applications

Monitoring and Usage

Administration and Marketplace

Manage Authentication Profiles

Before You Start

Profile Types

Password Policy Parameters

Manage Authentication Profiles

Create an authentication profile

View an authentication profile

Update an authentication profile

Delete an authentication profile

Next Steps

Enable Single Sign-On

Manage Users

Manage Roles

Overview

​Before You Start

​Profile Types

​Password Policy Parameters

​Manage Authentication Profiles

​Create an authentication profile

​View an authentication profile

​Update an authentication profile

​Delete an authentication profile

​Next Steps

Enable Single Sign-On

Manage Users

Manage Roles

Overview

Before You Start

Profile Types

Password Policy Parameters

Manage Authentication Profiles

Create an authentication profile

View an authentication profile

Update an authentication profile

Delete an authentication profile

Next Steps