Enable Single Sign-On (SSO) - ZEDEDA Beta Docs

ZEDEDA supports OIDC (OpenID Connect), a wrapper over Open Authorization (OAuth), for third-party authentication alongside local user authentication. Authentication is the basis for authorization. An authentication server provides a network service that Edge Infrastructure Services uses to authenticate credentials. Throughout this document, Edge Infrastructure Services acts as the Service Provider and your authentication server acts as the Identity Provider (IdP).

Diagram showing that Edge Infrastructure Services acts as the Service Provider and your authentication server acts as the Identity Provider (IdP).

Configuration Concepts

Realms

A realm is the domain of a user’s email address. Edge Infrastructure Services uses the realm to decide whether a user must authenticate through SSO. Enter realms as bare domain names, without a leading @ or any other prefix:

Correct	Incorrect
`zededa.com`	`@zededa.com`
`example.io`	`@example.io`

A value containing @ fails domain-name validation.

When a realm is configured on an enterprise, Edge Infrastructure Services redirects users whose email address belongs to that domain to the configured Identity Provider. Only OAuth users belonging to a configured realm can log in to the enterprise.
You can configure multiple realms for one enterprise, for example zededa.com, zededa.dev, and zededa.net.
All realms in an enterprise resolve to the same Identity Provider, because only one authorization profile can be active per enterprise.

Authorization profiles

An authorization profile determines which Identity Provider validates user credentials. In the Edge Infrastructure Services console, this is presented as the External Authentication Profile; in the API and in ZCLI (the ZEDEDA command-line interface) the object is an authorization profile (zcli auth-profile).

You can use any OIDC-compliant Identity Provider. ZEDEDA provides dedicated profile types for Azure AD and Google; other providers, including Okta, are configured as a custom OAuth profile using their client ID, client secret, and OpenID Connect endpoint.
An enterprise can hold more than one authorization profile, but only one profile can be active at a time. Because only one profile is active, only one Identity Provider is in effect: you cannot run Azure AD and Google simultaneously for the same enterprise.
Mark a profile --test-only to stage it without putting it into service, and --active to make it the profile in effect.
The profile type is fixed when the profile is created. zcli auth-profile update cannot change it; create a new profile instead.

Enterprise inheritance

SSO configuration applies at the enterprise level. When SSO is enabled for an enterprise, every user in that enterprise authenticates through SSO. SSO cannot be enabled or disabled per user. A child enterprise can inherit its authorization profile from its parent. The --inherit-auth setting controls this.

Inheritance enabled: the child enterprise uses the parent’s configuration. You cannot configure a separate profile for that child.
Inheritance disabled: you can configure a specific authorization profile for that child enterprise.

Changing the setting later: you can only turn inheritance on, never off:

Change	Result
Disabled → enabled	Permitted after creation, using `zcli enterprise update --inherit-auth`.
Enabled → disabled	Not permitted. The update request succeeds, but the setting is left unchanged. There is no error to tell you it was ignored.

If an enterprise must be able to stop inheriting, do not enable inheritance in the first place.

Self-signup enterprises cannot inherit authentication from a parent, regardless of the --inherit-auth value.

User permissions and roles

SSO handles authentication (verifying identity), not authorization (access rights).

Users who sign in through SSO are recognized as OAuth users.
An administrator must grant roles to those users before they can do anything. The system-defined roles are SysAdmin, SysManager, SysOperator, and SysMonitor; you can also use user-defined roles.
An authenticated SSO user with no role assignment cannot access enterprise resources.
Roles must already exist in ZEDEDA. The Identity Provider only selects which existing role a user receives; it cannot create roles. See Role Management.

Configuration methods

Both the UI and ZCLI can manage SSO:

Edge Infrastructure Services console: enable and configure the external authentication profile and manage realms.
ZCLI: full lifecycle management of realms (zcli realm) and authorization profiles (zcli auth-profile), plus the enterprise-level --inherit-auth setting on zcli enterprise create and zcli enterprise update. See Manage SSO with ZCLI.

Before You Begin

Register Edge Infrastructure Services as a client on your authentication server. The user or resource owner must complete the client registration process. Provider documentation:

Callback URL

Configure this callback (redirect) URL at your Identity Provider:

https://<cluster>/oauth/callback

For example: https://zedcontrol.zededa.net/oauth/callback Include the https:// scheme. Identity Providers reject redirect URIs that omit it.

Attributes to collect

Obtain the following from your Identity Provider before you start. This is a one-time exercise.

Client ID
Client Secret
OpenID Connect endpoint

Enable OAuth for Your ZEDEDA Enterprise

ZEDEDA onboards an enterprise with local admin authentication. The user or resource owner enables third-party authentication when needed. Keeping a local administrator account is a deliberate fail-safe: if your Identity Provider is misconfigured or unreachable, a local admin can still sign in and correct the configuration. This separation also suits organizations where the team that runs the authentication server is not the team that administers ZEDEDA. To enable OAuth using local user authentication:

Log in to the Edge Infrastructure Services console.
Select your profile avatar in the top navigation.
From the dropdown, select Enterprise Settings.
In the sidebar, under Security & Access, select Authentication.
In the Single Sign-On card, click Edit.
In the Authentication Provider dropdown, select Custom OIDC.
In the Authentication Type dropdown, select OAuth.
Complete the remaining profile attributes described in Authorization profile attributes, then click Save.

Authorization profile attributes

The Custom OIDC form is organized into four subsections.

Provider settings

Attribute	Required	Description
Authentication Type	Yes	Authentication protocol. Select OAuth for OIDC/OAuth providers, or SAML for SAML providers.
Display name	Yes	Name displayed for this authentication configuration.
OpenID Connect Endpoint	Yes	Issuer endpoint of your Identity Provider.

Credentials

Attribute	Required	Description
Client ID	Yes	Client ID issued by your Identity Provider.
Client Secret	Yes	Client secret issued by your Identity Provider.

Token settings

Attribute	Required	Description
Scope	No	Name of the ID-token claim that carries role names. See Role Management.
JWT Algorithm	No	Signing algorithm used to validate the ID token: `None`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, or `ES512`.
IDP Id	No	Passed to the Identity Provider as the `idp_id` authorization parameter. Required by some providers to select a specific upstream IdP.

User provisioning

Attribute	Required	Description
Auto-create users on first login	No	When enabled (default), a user record is created automatically on a user’s first successful SSO login. When disabled, logins by unknown users are rejected; user records must already exist.
Default Role for New Users	Yes	Role assigned to an OAuth user when no role can be resolved from the token. Must be an existing ZEDEDA role.

Additional parameters

Extra key-value pairs appended to the authorization request URL, for providers that require non-standard parameters. Click Add to add a parameter.

Default Role for New Users only applies when Auto-create users on first login is enabled. If you disable auto-create, assign roles to users when you create them manually.

Find your OpenID Connect endpoint

You can read the OpenID Connect endpoint from your provider’s OpenID configuration document:

Google: https://accounts.google.com/.well-known/openid-configuration
Okta: https://<your-okta-domain>/.well-known/openid-configuration, where <your-okta-domain> is the Okta domain issued to your organization.

Role Management

ZEDEDA resolves a role for each OAuth user from the ID token, using custom claims (key-value attributes) configured on your authorization server.

How a role is resolved

ZEDEDA reads the role claim from the ID token. By default it reads the claim named roles. If you set the Scope attribute on the profile, ZEDEDA reads that claim name instead.
The claim value might be a single string or an array of strings. Each value is treated as a candidate role name.
ZEDEDA compares the candidate names against roles that already exist in the enterprise and uses the first match.
If no candidate matches an existing role, or the claim is absent, ZEDEDA assigns the profile’s Default Role for New Users.

The Scope attribute holds a claim name, not an OAuth scope to request. Its value must match the name of the claim as it appears in the ID token.

Roles are never created automatically. They must exist in ZEDEDA before a user signs in, created during enterprise onboarding or afterwards by an administrator. The authorization server only drives which existing role is assigned.

Example: group claims in Okta

Some authorization servers, including Okta, can drive role assignment from group membership:

Create a user group in Okta whose name matches a ZEDEDA role, for example zededa-admin or zededa-users.
Assign the group to the application you registered for Edge Infrastructure Services.
In the Okta authorization server settings, add a custom groups claim.
Confirm the groups claim is included in the id_token sent to ZEDEDA. ZEDEDA uses it to assign roles.
On the ZEDEDA authorization profile, set the Scope attribute to the name of that claim, for example groups.

Manage SSO with ZCLI

Realms

zcli realm create <name> --enterprise=<enterprise> --title=<title> [--description=<description>]
zcli realm show   [<name> | --uuid=<uuid>] [--detail]
zcli realm show   [--enterprise=<enterprise>] [--name-pattern=<pattern>]
zcli realm update <name> [--enterprise=<enterprise>] [--title=<title>] [--description=<description>]
zcli realm delete <name> [--enterprise=<enterprise>] [-f]

Pass the realm as a bare domain, for example zcli realm create zededa.com --enterprise=acme --title="ZEDEDA".

Authorization profiles

zcli auth-profile create <name> --type=oauth \
  --client-id=<client-id> --client-secret=<client-secret> --endpoint=<endpoint> \
  [--jwt-algorithm=RS256|RS384|RS512] \
  [--default-role=<role-name> | --disable-auto-user] \
  [--role-scope=<claim-name>] [--active] [--test-only]

zcli auth-profile show   [<name> | --uuid=<uuid>] [--detail]
zcli auth-profile update <name> --client-secret=<client-secret> [--client-id=<client-id>] [--endpoint=<endpoint>] \
  [--jwt-algorithm=RS256|RS384|RS512] [--role-scope=<claim-name>] \
  [--default-role=<role-name>] [--disable-auto-user] [--active] [--test-only]
zcli auth-profile delete <name> [-f]

--type is only accepted on create; a profile’s type cannot be changed later.

Enterprise inheritance

# At creation
zcli enterprise create <name> [--inherit-auth] ...

# After creation: can enable inheritance, cannot disable it
zcli enterprise update <name> [--inherit-auth] ...

You can also supply realms during onboarding:

zcli enterprise onboard <name> [--realm=<realm>...] ...

Switch Between OAuth and Local Authentication

Enabling OAuth blocks the creation of new local users. Local user accounts that already existed continue to work: they remain listed and their owners can still sign in and use ZEDEDA while an external profile is configured.
Disabling OAuth restores normal local user creation.

Keep at least one local administrator account so you retain access if the Identity Provider becomes unavailable.

Disable SSO

Select your profile avatar in the top navigation and select Enterprise Settings.
In the sidebar, under Security & Access, select Authentication.
In the Single Sign-On card, click Edit.
In the Authentication Provider dropdown, select Local.
Click Save.

Using ZCLI, clear the --active flag by activating a different profile, or delete the profile:

zcli auth-profile delete <name>

After SSO is disabled, local user creation is available again. Existing OAuth user records remain but can no longer authenticate through the removed profile.

User Logout Behavior

When a user logs out of ZEDEDA, ZEDEDA deletes only that user’s session. The user remains signed in to the Identity Provider. ZEDEDA does not perform RP-initiated logout (an OIDC mechanism where the application signals the Identity Provider to end the user’s session), so signing out of ZEDEDA does not sign the user out of the IdP.

On a shared or public workstation, a user who logs out of ZEDEDA can immediately sign back in without re-entering credentials, because the IdP session is still valid. Instruct users to sign out of the Identity Provider and close the browser when they finish. Where this matters, shorten session lifetimes at the Identity Provider.

Troubleshooting

Symptom	Likely cause	Action
Identity Provider rejects the redirect URI during app registration	Callback URL missing the `https://` scheme, or a path mismatch	Register exactly `https://<cluster>/oauth/callback`.
Realm value rejected when saving	Realm entered with a leading `@`, or not a valid domain	Enter the bare domain, for example `zededa.com`.
Login fails for a user who authenticates successfully at the IdP	The user’s email domain is not a configured realm for the enterprise, or the account belongs to a different enterprise	Add the domain as a realm on the enterprise and confirm the user belongs to that enterprise.
Login fails immediately after enabling OAuth	The profile’s default role does not exist	Create the role, or point Default Role for New Users at an existing role.
Users log in but can see nothing	No role assigned, or the role claim does not match any existing role	Assign a role, or confirm the claim name and that the claim values match existing role names.
Role from the IdP is ignored and everyone receives the same role	The Scope attribute holds an OAuth scope rather than the claim name, or the claim is absent from the `id_token`	Set Scope to the claim name and confirm the claim is present in the ID token.
Turning off `--inherit-auth` appears to succeed but nothing changes	Inheritance cannot be disabled after creation	Recreate the child enterprise without `--inherit-auth`.
Cannot sign in at all after a misconfiguration	External authentication is broken	Sign in with a local administrator account and correct the profile.

Next Steps

Manage Users

View auto-provisioned users and adjust their role assignments.

Configure Two-Factor Authentication

Enforce 2FA for all users, including those authenticating through SSO.

Enterprise Settings Overview

The full list of enterprise configuration options.

​Configuration Concepts

​Realms

​Authorization profiles

​Enterprise inheritance

​User permissions and roles

​Configuration methods

​Before You Begin

​Callback URL

​Attributes to collect

​Enable OAuth for Your ZEDEDA Enterprise

​Authorization profile attributes

​Provider settings

​Credentials

​Token settings

​User provisioning

​Additional parameters

​Find your OpenID Connect endpoint

​Role Management

​How a role is resolved

​Example: group claims in Okta

​Manage SSO with ZCLI

​Realms

​Authorization profiles

​Enterprise inheritance

​Switch Between OAuth and Local Authentication

​Disable SSO

​User Logout Behavior

​Troubleshooting

​Next Steps

Manage Users

Configure Two-Factor Authentication

Enterprise Settings Overview

Configuration Concepts

Realms

Authorization profiles

Enterprise inheritance

User permissions and roles

Configuration methods

Before You Begin

Callback URL

Attributes to collect

Enable OAuth for Your ZEDEDA Enterprise

Authorization profile attributes

Provider settings

Credentials

Token settings

User provisioning

Additional parameters

Find your OpenID Connect endpoint

Role Management

How a role is resolved

Example: group claims in Okta

Manage SSO with ZCLI

Realms

Authorization profiles

Enterprise inheritance

Switch Between OAuth and Local Authentication

Disable SSO

User Logout Behavior

Troubleshooting

Next Steps