Identity provider and SSO

Every self-hosted Netzilo Server comes with its own identity provider, Zitadel, set up by the installer. It holds your users' passwords and MFA factors, sends e-mails, and can pass sign-ins on to your corporate identity provider, such as Microsoft Entra ID, Okta or Google Workspace, so that people sign in with their company account.

You manage users in the dashboard under Team > Users. You manage sign-in policies, e-mail and single sign-on in the identity provider's console at https://go.example.com/ui/console (use your server's domain). The admin account the installer created can sign in to both.

How it works

Two layers decide who can use Netzilo:

The dashboard handles the common identity actions for you: creating a user with a password, changing a password, resetting MFA and deleting a user. Deleting a user in the dashboard also deletes the user in the identity provider. Go to the console only for policies, e-mail and single sign-on.

When you connect a corporate identity provider, Zitadel stays the issuer that Netzilo trusts. Nothing changes in the dashboard or in the server's configuration files.

The installer sets up the identity provider like this:

Do not edit the Dashboard or Cli applications in the console. Changing their redirect URIs or their authentication method breaks sign-in.

Add users without single sign-on

In the dashboard, go to Team > Users and click Add User. Choose how the user gets in:

Users whose e-mail domain matches an existing user's domain are added automatically when they first sign in. Choose the role (Owner, Admin or User) and groups on the user's page. See Users.

Configure e-mail (SMTP)

The installer configures no e-mail server. Until you add one, e-mail invitations, password-reset mails and e-mail one-time codes never arrive.

1. Sign in to the console and open https://go.example.com/ui/console/instance?id=smtpprovider.
2. Add an SMTP provider: the server as host:port (for example smtp.example.com:587), the user and password, the sender address and name.
3. Activate it. Only one provider can be active at a time.
4. Send a test e-mail from the provider's page.

With TLS on, the connection uses TLS from the start and falls back to STARTTLS on a plaintext port. Many corporate mail relays only accept a sender address they know: add the sender address to your relay's allow list. Errors such as Errors.SMTP.CouldNotDial or CouldNotStartTLS in the zitadel log mean the server cannot reach the relay or agree on TLS with it.

Connect your corporate identity provider

Single sign-on is set up in the console in four steps. Test it with one user before you tell everyone, and keep at least one admin who signs in with a local password, so that you can still sign in if the corporate identity provider fails.

Step 1: Register Netzilo at your identity provider

Create an application (an OIDC or OAuth web application, or a SAML service provider) at your corporate identity provider, with this redirect address:

Allow the scopes openid, profile and email. Note the client ID and client secret, or the SAML metadata URL.

Step 2: Add the provider in the console

Open https://go.example.com/ui/console/instance?id=idp and add an identity provider of the matching type:

Under the provider's options, set how accounts are matched:

With neither creation nor linking allowed, users see Neither creation of linking is allowed on this provider.

Step 3: Activate the provider on the login page

A provider you added does not appear on the sign-in page until it is active. In the provider list it must show as available; if it shows available but inactive, choose set as available. You can also check the Identity Providers section of https://go.example.com/ui/console/instance?id=login. This step is the one most often forgotten.

Step 4: Test the sign-in

Open https://go.example.com in a private browser window. The sign-in page shows a button for your provider. Sign in with a test user. On the first sign-in, the user is created and joins the Netzilo account if their e-mail domain matches an existing user's domain, or if you invited them.

Once single sign-on works for everyone, you can turn off sign-in with username and password under Login Behavior and Security (?id=login). Keep a local admin first.

Map identity provider groups to Netzilo groups

Netzilo can keep users' group membership in step with a claim in their sign-in token.

1. Zitadel does not pass group claims from your corporate identity provider by default. The installer created the actions addGroupClaim and addGroupMeta for this, but did not attach them. In the console, under Actions, attach them to the flows for external authentication and for complementing the token.
2. In the dashboard, go to Settings > Groups, turn on Enable JWT group sync, and enter the claim name under JWT claim (for example groups).

Groups are matched to existing Netzilo groups by name; they are never created from a token. When the claim changes, the membership it granted is removed again. Optionally, JWT allow group lets only members of one group use Netzilo. Make sure you are in that group before you save, or you lock yourself out.

This is an advanced setup. Test it with one user, and keep a local admin that does not depend on the claim. See Groups.

Passwords, MFA and lockout

These policies live in the console, under the instance settings:

To reset one user's MFA, open the user under Team > Users in the dashboard and use Reset MFA. To set a new password for a user, use Change Password on the same page.

To give another person access to the console, add them as an instance member with the IAM_OWNER role in the instance's Members.

Servers set up with an older template

Servers built from older installation templates connect the management server straight to a corporate identity provider through settings files, without the bundled Zitadel. That setup is no longer documented. Several features need the bundled identity provider: creating users with a password, changing passwords, resetting MFA, importing sign-in events and the tenant logo. To move such a server to the current setup, install a new server and move your configuration to it; contact support@netzilo.com for help.

Troubleshooting

Check the identity provider first:

D=go.example.com
curl -sS https://$D/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"'
curl -sS -o /dev/null -w "console %{http_code}\n" https://$D/ui/console/
curl -sS -o /dev/null -w "ready %{http_code}\n" https://$D/debug/ready

The issuer must be https://go.example.com, and both other checks answer 200.

Invitation or password-reset mails never arrive. No SMTP provider is active, see Configure e-mail (SMTP). Meanwhile, add users with Create password.

The SSO button does not appear on the sign-in page. The provider is not active on the login page, see Step 3.

Neither creation of linking is allowed on this provider. Turn on Automatic creation or automatic linking by e-mail on the provider.

Registration is not allowed. The user does not exist and self-registration is off. Invite the user, or turn on Automatic creation for the provider they use.

User could not be found. Wrong login name. Users sign in with their e-mail address.

User is locked. The lockout limit was reached. Unlock the user in the console.

User is not active. The user was deactivated in the console. Reactivate them there.

The user is stuck on "initialize user". The user never set a first password. Resend the initialization mail from the console, or set a password in the dashboard.

A verification or reset code has expired. Invitation codes are valid for 72 hours, reset codes for one hour. Send a new one.

The requested redirect_uri is missing in the client configuration. You opened the server by another name than its domain, or the Dashboard application's redirect URIs were edited. They must include https://go.example.com/nb-auth, /nb-silent-auth and /nb-auth-x, with https://go.example.com/ and /nb-logout after sign-out.

code_challenge required. The Dashboard application's authentication method was changed. Set it back to None (PKCE).

Instance not found. Make sure you got the domain right. You opened the server by an alias or its IP address. Always use the exact domain the server was installed with.

user does not belong to any of the allowed JWT groups. JWT allow group is set and the user's token does not carry that group. See Map identity provider groups to Netzilo groups.

A device fails to sign in with Token is expired seconds after signing in, or Token is not valid yet. The device's clock is wrong. Correct it and sign in again.

Related Documentation

• Users - add users, set roles and groups
• Groups - JWT group sync and group propagation
• Authentication - peer login expiration
• Install on your own server - the installation that sets up the identity provider