Introduction
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).
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).
- Any OIDC-compliant Identity Provider can be used. 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 — inheritance can only be turned 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; user-defined roles can also be used.
- 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:
- Google as an authentication server
- Create an OAuth 2.0 app in Okta
- Protect an API by using OAuth 2.0 with Azure Active Directory and API Management
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.
- Navigate to your Profile in the top navigation.
- Hover over Enterprise and click Settings.
- Scroll to the Authentication Profile section.
- Click the Edit icon.
- Select the External Authentication Profile checkbox to enable it.
- Select OAuth as the authentication type, then complete the profile attributes in Authorization profile attributes.
Authorization profile attributes
| Attribute | Required | Description |
| Profile Name | Yes | Name of the authorization profile. |
| Client ID | Yes | Client ID issued by your Identity Provider. |
| Client Secret | Yes | Client secret issued by your Identity Provider. |
| OpenID Connect Endpoint | Yes | Issuer endpoint of your Identity Provider. |
| 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. |
| Scope (role claim name) | 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: RS256, RS384, or RS512. |
| Disable automatic user creation | No | By default, a user record is created automatically on a user's first successful SSO login. Enable this option to require that user records already exist; logins by unknown users are then rejected instead of provisioning a new user. |
| IdP ID | No | Passed to the Identity Provider as the idp_id authorization parameter. Required by some providers to select a specific upstream IdP. |
| Additional parameters | No | Extra key-value pairs appended to the authorization request URL, for providers that require non-standard parameters. |
The **Default Role for New Users** setting only takes effect when automatic user creation is enabled. If you disable automatic user creation, assign roles to users when you create them.
Finding your OpenID Connect endpoint
The OpenID Connect endpoint can be read 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 (role claim name) 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 (role claim name) 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] ...
Realms can also be supplied during onboarding:
zcli enterprise onboard <name> [--realm=<realm>...] ...
Switch between OAuth and Local Authentication
Keep at least one local administrator account so you retain access if the Identity Provider becomes unavailable.
- 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.
Disable SSO
After SSO is disabled, local user creation is available again. Existing OAuth user records remain but can no longer authenticate through the removed profile.
- In the Edge Infrastructure Services console, go to Profile > Enterprise > Settings and open the Authentication Profile section.
- Clear the External Authentication Profile checkbox.
Using ZCLI, clear the --active flag by activating a different profile, or delete the profile:
zcli auth-profile delete <name>
User Logout Behavior
When a user logs out of ZEDEDA, ZEDEDA deletes only your 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
Provision and manage child enterprises, including the `--inherit-auth` authentication inheritance setting. Create, edit, and delete custom roles that SSO users can be assigned.