Running it · Chapter 12

Sign-in and OpenID Connect.

There are three ways in: the password, the media server account and a sign-in service you run anyway. Nexview can do all three at once, and a new way takes no old way away by itself. Each leads into the same account. Role, quota, approvals and history hang on the Nexview account, not on the way in.

What the sign-in page shows

Out of the box there is exactly one field for “Username or e-mail” and one for “Password”. Everything else appears only once you set it up. If a media server is connected, a button “Sign in with Plex” joins them (or Jellyfin, Emby). If sign-in services are entered, one button per provider joins, with the name you gave it.

With a password

The password needs at least four characters. Anyone reachable from the internet is better off with a long one. Signing in with a password requires a confirmed e-mail address. If the confirmation is missing, the page shows “Address not confirmed yet” and offers “Resend confirmation mail” and “Correct address”. “Forgot your password?” sends a link, which needs the mail server. The owner of the installation gets in even with an address that is not confirmed yet.

After a few wrong passwords Nexview slows the next attempt down, and after ten it closes the door for fifteen minutes. It opens again by itself. That covers signing in, signing in with a media server password and the links from mails. Counting always happens per account. If you also want to count per address, set NEXVIEW_CLIENT_IP, see Behind a proxy.

With the media server account

Plex, Jellyfin and Emby all work, also at the same time. Whoever has the account there already does not need to create it a second time in Nexview. Matching happens only to an address that is confirmed in Nexview or set by the operator; one taken over from the provider does not count. The chapter Connect your media server describes it.

With a sign-in service

OpenID Connect is a standard, so there is no list of supported providers. From Nexview’s point of view a provider is an issuer, a client ID and a secret. Whether authentik, Microsoft Entra ID, Keycloak, Authelia, Pocket ID, Zitadel or Google sits behind it makes no difference. Several providers at once work, each gets a button on the sign-in page, in an order you drag. Everything lives under “Settings › System › Sign-in” in three cards:

Sign-in
Whether people may still sign in with a password (“Sign-in with a password”), and the “Public address”.
Sign-in providers
The list in the order of the buttons, with “Add a provider”, “Edit” and “Remove”.
authentik in one step
Sets up provider and application in authentik for you.

The public address first

A provider rejects any redirect address that is not stored with it exactly. Nexview builds it from your public address and shows it, ready to copy, at “Redirect address for the provider”:

Redirect address

https://nexview.example.com/api/oidc/<short name>/callback

If Nexview runs under a sub-path, it belongs in it. If the public address changes later, Nexview asks first when a provider still knows the old redirect address. Behind a proxy that ends TLS, Nexview has to believe the proxy about the scheme, otherwise the address starts with http. That is in the chapter Behind a proxy.

Entering a provider by hand

Field	What goes there
Name on the button	What the button says, such as “Sign in with Company SSO”.
Short name	Part of the redirect address, a to z, digits and dashes. It cannot be changed after saving.
Issuer	The base address of the provider. Nexview reads `/.well-known/openid-configuration` itself and checks it before anything is saved. You never enter single endpoints. A slash at the end makes no difference.
Client ID, Client secret	Both arise when you register Nexview at the provider. A stored secret never leaves the server, and an empty field on edit keeps it.
On	Switched off, the button disappears and the provider lets nobody in. The links stay.
New people get an account	Off out of the box. Off: only invited people and accounts that linked themselves come in. On: whoever has an account at the provider gets one here as an ordinary user whose requests need approval.
More › Scopes	`openid profile email`, unless you need something else.

Good to knowWith Google and Microsoft, “New people get an account” means literally: every person with an account there. Switch it on only if you yourself decide who has an account at the provider, or if you have limited the application there to your own organisation. Nexview writes exactly that next to the switch.

authentik in one step

In the third card enter the address of authentik and an API token that may create applications (in authentik under “Directory › Tokens and App passwords”, an API token of an administrator). “Set up” then creates the signing key, the mappings for name and address, an OAuth2 provider and the application, or updates them when you press it again, and fills in the entry here. Every step is listed with a tick or a cross, and a failed one says why: authentik not reachable, the token refused, another application already using the name. The token is used for this run only and never stored.

A second Nexview against the same authentik gets a provider of its own, the first stays untouched.
If Nexview moves to another address, the button finds its own provider by the client ID, and every link stays.
Pointed at a different authentik, that is a different issuer: Nexview asks first and names how many accounts would have to link again.
“Download blueprint instead” gives you nexview-authentik.yaml, which you apply in authentik yourself (Customization › Blueprints).
Without a public address the card suggests the one you are using in the browser right now. “Use it and set up” saves it first. Nexview never registers an address it guessed from the request.

Microsoft Entra ID

In the Entra admin center register an application under “App registrations”, add the redirect address as a redirect of the “Web” platform (Entra takes only https, localhost aside) and create a client secret. The issuer is https://login.microsoftonline.com/TENANT-ID/v2.0 for your own tenant, or …/common/v2.0 or …/organizations/v2.0 for several. Nexview then accepts a token from any tenant whose iss and tid agree. Entra sends the e-mail address only as the optional claim email.

Other providers

Keycloak. “Clients › Create client”, type OpenID Connect, “Client authentication” on, “Standard flow”. The redirect address goes under “Valid redirect URIs”. Issuer: https://keycloak.example.com/realms/<realm>.
Pocket ID. “OIDC Clients › Add client”. The issuer is the address of your Pocket ID.
Authelia. A client under identity_providers.oidc.clients with the redirect address and scopes: [openid, email, profile]. Nexview gets the plaintext secret that you hashed for Authelia. Authelia leaves the address out of the ID token, so Nexview reads it from userinfo.
Zitadel. “New application”, type Web, authentication method Basic. The issuer is the address of your instance.
Google. “APIs & Services › Credentials › OAuth client ID”, type Web application. Issuer: https://accounts.google.com. Leave “New people get an account” off unless the client is limited to your own workspace.

Who is this? Linking, invitations, new people

Nexview recognises a person only by the identity at the provider, that is issuer plus subject, never by the e-mail address, even when the provider says it is confirmed. If you rename the person at the provider or change their address there, the link holds.

Existing accounts link themselves under “Profile › Account › Security” in the section “Sign-in providers”. “Link” asks for the account’s own password once more, goes to the provider and back. “Unlink” removes the link. An account without a password keeps its last link, or it would be locked out. Afterwards both work: the provider’s button and still the password.
Invited people choose “Continue with …” on the invitation page instead of choosing a password. The invitation travels with them to the provider and back and is used up exactly once.
Everybody else gets in only if “New people get an account” is on for that provider. Otherwise the sign-in page says that an invitation is needed or that the account can be linked in the profile.
Administrators see each account’s providers as small marks in “Settings › Users” and can remove a link with their own password. Nobody but the operator touches the operator’s own account.

Groups are not read. The provider vouches for who someone is. What they may do here, role, quotas, blocked profiles and automatic approval, stays in Nexview. When an account is deleted, its identity is blocked, so that “New people get an account” does not let it straight back in. The list “Blocked sign-ins” sits below the three cards, and “Lift block” lets the identity in again.

Switching the password off

Once at least one provider is on, “Sign-in with a password” can be switched off. The sign-in page then shows only the providers’ buttons and, underneath, “Sign in as the operator with a password”: the operator can always sign in with the password, which is the way back when the provider fails. If the last provider goes or is switched off, passwords work again for everyone.

Changing or removing a provider

A different issuer is a different provider: the links of that entry go, and the people concerned link again. The form says how many accounts that is before it saves. The same issuer with or without a slash at the end changes nothing. When you remove an entry, the question names how many accounts lose the link and for how many it was the only way in.

And the second factor?

Nexview has no second factor of its own. Whoever wants one switches it on at their sign-in service, and that checks it at every sign-in through the provider.

What Nexview checks, and when it does not work

The ID token is checked against the provider’s published keys, never against a shared secret, plus issuer, audience, expiry, nonce and a non-empty subject. The attempt itself runs with PKCE and a state that is used once. If a sign-in is refused, the log under “Settings › System › Log” gets exactly one line with the reason, such as OIDC sign-in refused: oidc_no_account. Addresses appear shortened there, tokens and secrets never. The person themselves reads a short sentence that says what to do, such as “There is no account for you here. Ask for an invitation, or sign in with your password and link your account in your account settings.”

Next is what stands between you and your people: Behind a proxy. A short version of the ways in is on the Sign-in page under Features.