Single sign-on (OIDC)
Aperture can add a Sign in with … button that hands sign-in to an OpenID Connect (OIDC) provider. Local accounts keep working next to it. This page explains the settings, how accounts are matched, provider examples, and what to check when sign-in fails.
How it works
Section titled “How it works”- The person clicks the single sign-on button on Aperture’s sign-in page.
- Aperture redirects the browser to your provider, asking for the
openid,emailandprofilescopes. - After sign-in, the provider redirects back to Aperture’s callback with a code. Aperture exchanges the code for tokens at the provider, server to server, using the client secret, and verifies the ID token’s signature, issuer and audience.
- Aperture reads the
email,email_verified,name(orpreferred_username) and the subject (sub) from the ID token, finds or creates the account, and starts a normal session.
The code is in internal/oidc/oidc.go and internal/api/oidc_handlers.go.
Both the browser and the Aperture server must be able to reach the provider: the browser for the sign-in page, the server for the discovery document and the token exchange.
Set it up
Section titled “Set it up”- Open Integrations › Single Sign-On. Copy the Redirect URI shown at the bottom.
- In your provider, create a confidential OIDC client (an “application”) with that redirect URI. Note its client ID and client secret, and the provider’s issuer URL.
- Back in Aperture, fill in the fields below, turn on Enable SSO login and click Save.
- Open Aperture in a private window and try the new button.
| Field | What to enter |
|---|---|
| Enable SSO login | Shows the button on the sign-in page. |
| Button label | The provider’s name on the button, shown as “Sign in with label”. Default: “Single sign-on”. |
| Issuer URL | The provider’s issuer, exactly as the provider states it, including a trailing slash if it has one. Aperture fetches <issuer>/.well-known/openid-configuration from the server, and the issuer in that document must equal this field character for character. Only spaces around it are removed. |
| Client ID | The client ID from the provider. |
| Client secret | The client secret. It is never shown again; leave the field blank later to keep it. |
| Restrict to email domain (optional) | Only addresses ending in @ plus this domain may sign in. Enter the domain without the @, for example example.com. One domain only. |
| Auto-create accounts | First-time users who match no account become viewers. Off by default. |
| Accept emails without a verified flag | Lets an ID token that has no email_verified claim at all link or create an account by email. Off by default. Only for providers that never send the claim, see Verified email addresses. |
The settings live in the database and take effect on the next sign-in, without a restart. Aperture discovers the provider on first use and again whenever the settings change.
The redirect URI
Section titled “The redirect URI”The redirect URI is built from APERTURE_PUBLIC_URL:
<APERTURE_PUBLIC_URL>/api/auth/oidc/callbackFor APERTURE_PUBLIC_URL="https://nvr.example.com" that is https://nvr.example.com/api/auth/oidc/callback. Note the path is under /api/, not /api/v1/.
APERTURE_PUBLIC_URL must be the address people actually use. If you change it (in /etc/aperture/aperture.env, followed by sudo systemctl restart aperture), update the redirect URI in your provider too. See Configuration.
How accounts are matched
Section titled “How accounts are matched”On every SSO sign-in, Aperture:
- Rejects the sign-in if the ID token has no
email, or if a domain restriction is set and the address does not end in@plus that domain. Subdomains do not match:sam@mail.example.comdoes not passexample.com. - Looks for the account already linked to this provider subject. If there is one, it signs in; the steps below are skipped.
- Otherwise rejects the sign-in unless the provider vouches for the address, see Verified email addresses.
- Looks for an account with the same email address and links it to the subject. From then on the link is used.
- Otherwise, if Auto-create accounts is on, creates a viewer with that email and the name from the provider. The new viewer has no password and no cameras: an administrator assigns cameras under Users.
- Otherwise rejects the sign-in.
A disabled account is refused at any step.
An administrator account can be linked this way too; the role always comes from Aperture, never from the provider. An account created by SSO has no password, so it can only sign in through SSO until an administrator sets one.
Verified email addresses
Section titled “Verified email addresses”Linking and creating accounts by email is only safe when the provider has checked that the person owns the address. Otherwise anyone who can register that address at the provider signs in as the Aperture account, administrators included. So Aperture links or creates an account only when the ID token says email_verified: true (the string "true" counts too). An account that is already linked keeps signing in whatever the claim says, because the link uses the subject, not the email.
email_verified in the ID token |
Link or create by email |
|---|---|
true |
Yes |
false |
Never, whatever the settings |
| Missing | Only with Accept emails without a verified flag on |
A refused sign-in shows “Single sign-on failed” and is written to the activity log as auth.login_failed with sso: email_verified false or sso: email_verified absent, and to the service log as oidc callback: email not verified by the provider.
Two-factor and SSO
Section titled “Two-factor and SSO”Aperture does not ask for its own authenticator code after a single sign-on. Enforce two-factor at the provider. An existing trusted device is reused for the session; SSO does not create one. Sessions from SSO follow the same rules as any other, see How long you stay signed in.
Provider examples
Section titled “Provider examples”The examples use https://nvr.example.com for Aperture. Replace the provider addresses with yours. Menu names in these products change between versions; the values are what matters.
Keycloak
Section titled “Keycloak”- In your realm, open Clients and create a client: type OpenID Connect, client ID
aperture. - Turn Client authentication on and keep Standard flow enabled.
- Set Valid redirect URIs to
https://nvr.example.com/api/auth/oidc/callback. - Copy the secret from the client’s Credentials tab.
| Aperture field | Value |
|---|---|
| Issuer URL | https://keycloak.example.com/realms/<realm> (older Keycloak versions: https://keycloak.example.com/auth/realms/<realm>) |
| Client ID | aperture |
| Client secret | the secret from Credentials |
Each Keycloak user needs an email address with Email verified on. Keycloak’s default email client scope puts both in the ID token. Users an administrator creates in Keycloak start with Email verified off; switch it on in the user’s details, or Aperture will not link the account.
Authelia
Section titled “Authelia”Add a client to Authelia’s configuration (Authelia 4.38 and later key names) and restart Authelia:
identity_providers: oidc: claims_policies: aperture: id_token: ['email', 'email_verified', 'name', 'preferred_username'] clients: - client_id: 'aperture' client_name: 'Aperture' client_secret: '<hashed client secret>' public: false authorization_policy: 'two_factor' claims_policy: 'aperture' redirect_uris: - 'https://nvr.example.com/api/auth/oidc/callback' scopes: ['openid', 'email', 'profile'] token_endpoint_auth_method: 'client_secret_basic'Authelia stores the client secret hashed; enter the plain secret in Aperture. The claims_policy matters: Aperture reads the email and email_verified only from the ID token, and Authelia 4.39 and later leave them out of the ID token unless a claims policy adds them. Keep email_verified in the list, or Aperture will not link accounts by email.
| Aperture field | Value |
|---|---|
| Issuer URL | Authelia’s own address, for example https://auth.example.com |
| Client ID | aperture |
| Client secret | the plain secret |
- In the Google Cloud console, configure the OAuth consent screen for your project.
- Under APIs & Services › Credentials, create an OAuth client ID of type Web application.
- Add
https://nvr.example.com/api/auth/oidc/callbackunder Authorized redirect URIs. Google accepts onlyhttpsredirect URIs (andlocalhost).
| Aperture field | Value |
|---|---|
| Issuer URL | https://accounts.google.com |
| Client ID | the ID ending in .apps.googleusercontent.com |
| Client secret | the client secret |
| Restrict to email domain | your Google Workspace domain, if you have one |
With a personal Google account, leave Auto-create accounts off. Otherwise any Google user could create a viewer account. Add each person under Users with their Google address instead; the first SSO sign-in links it.
Authentik
Section titled “Authentik”In Authentik you create an OAuth2/OpenID Provider (client type Confidential, redirect URI https://nvr.example.com/api/auth/oidc/callback, with a Signing Key selected) and an Application that uses it.
| Aperture field | Value |
|---|---|
| Issuer URL | the application’s issuer, with its trailing slash: https://authentik.example.com/application/o/aperture/ |
| Client ID | the provider’s client ID |
| Client secret | the provider’s client secret |
Authentik’s per-application issuer ends in /. Enter it with the slash, exactly as Authentik shows it: Aperture keeps the Issuer URL as entered, and the OIDC library it uses (go-oidc) requires the issuer in the discovery document to match it exactly.
Signing keys
Section titled “Signing keys”Aperture verifies ID tokens signed with RSA, ECDSA, RSA-PSS or EdDSA keys published by the provider. It does not accept tokens signed with the client secret (HS256). In providers that offer both, select a signing key or certificate for the client.
Turn it off
Section titled “Turn it off”Turn Enable SSO login off and click Save. The button disappears. Linked accounts keep their link for when you turn it on again; accounts that have a password keep signing in with it.
There is no setting to turn off password sign-in while SSO is on.
Where the secret is kept
Section titled “Where the secret is kept”The client secret is stored in the settings table of the database as entered, not encrypted, and is included in a configuration backup. It is never returned to the browser: the settings show only whether one is set. Treat backups accordingly, see Security model and hardening.
Troubleshooting
Section titled “Troubleshooting”When SSO fails after the provider, Aperture sends the browser back to its sign-in page with “Single sign-on failed. Try again or use your password.” Failures of the code exchange are logged as oidc callback with the error; read them with:
journalctl -u aperture --since "10 min ago" | grep -i oidcIf the button itself answers SSO is not available, check discovery from the server. The issuer in the answer must equal your Issuer URL character for character:
curl -s https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"'| Symptom | Cause |
|---|---|
Clicking the button shows {"error":"SSO is not available"} |
The server cannot use the discovery document: wrong Issuer URL, the provider is unreachable from the server, or an issuer mismatch, often a trailing slash present on one side only. The log shows only the 503 for /api/auth/oidc/login. |
| The provider says the redirect URI is invalid | The URI registered at the provider differs from the Redirect URI Aperture shows, often http against https, a port, or a trailing slash. Check APERTURE_PUBLIC_URL. |
oidc callback with token exchange in the log |
Wrong client secret or client ID, or the client is not confidential. |
oidc callback with verify id_token in the log |
The token is signed with the client secret (HS256), or its audience is not the client ID. |
oidc callback with err=<nil> in the log |
The ID token carries no email claim. Make the provider put it in the ID token (Authelia: the claims policy above). |
oidc callback: email not verified by the provider in the log |
The account is not linked yet and the ID token says email_verified: false or has no such claim. Mark the address verified at the provider (Keycloak: Email verified; Authentik: see above), or see Verified email addresses. |
| “Single sign-on failed” with nothing in the log | The address fails the domain restriction, no account matches and Auto-create accounts is off, the account is disabled, or the sign-in started on a different address than APERTURE_PUBLIC_URL. |
| A new SSO user signs in but sees no cameras | Auto-created accounts are viewers with no cameras. Assign cameras under Users. |
Related: Users, roles and camera access, Passwords, two-factor and passkeys, Reverse proxy.