Single sign-on with OpenID Connect

What Mirra supports

Any standards-compliant OpenID Connect provider. Mirra reads your provider's discovery document and works out the rest, so there is no per-vendor configuration to maintain — the settings panel names Entra ID, Okta, Google Workspace, Authentik and Keycloak, and anything else that publishes the same document behaves the same way.

The flow is authorisation code with PKCE. Mirra asks for the openid, email and profile scopes, and verifies the returned ID token against your provider's published signing keys, checking the issuer and that the token was issued for your client. Nothing is taken on face value.

• OpenID Connect only. SAML is not supported.
• One connection per Mirra account, matched to one email domain.
• People still arrive at the ordinary sign-in page; the handoff happens after they type their address.

What you need from your provider

Create an application — a web application, confidential client — in your identity provider, and collect four things. Registering the redirect URI is the step people forget, and the symptom is an error page from the provider rather than from Mirra.

• The issuer URL. It must be https, and appending /.well-known/openid-configuration to it must return the provider's OpenID configuration. For Entra ID that looks like https://login.microsoftonline.com/<tenant>/v2.0.
• The client ID.
• The client secret.
• The redirect URI to register with your provider: your Mirra address followed by /api/auth/sso/callback. The exact string is printed at the foot of the settings panel so you can copy it rather than construct it.
• The email domain your people sign in with, such as example.com.

Setting it up

1. Register the application with your provider

   Web application, authorisation code flow, with your Mirra address plus /api/auth/sso/callback as the redirect URI. Grant it the openid, email and profile scopes.

2. Open Settings and find Single sign-on (Enterprise)

   Settings is in the account menu under your own name. The section is below Branding and Notifications, and above Your data. Who can sign in is not there — it moved to the Account page, beside Change password.

3. Fill in the four fields

   Issuer URL, Email domain, Client ID, Client secret. The domain is lower-cased for you and must look like a real domain.

4. Decide about automatic accounts

   Create accounts on first sign-in is ticked by default. Untick it if you would rather create every account yourself, in which case somebody your provider authenticates but Mirra has never seen is turned away.

5. Tick Enabled

   An unticked connection is saved and dormant — the panel labels it "configured, off" — which is how you stage the setup before anybody depends on it.

6. Press Save connection

   The button reads Verifying… while Mirra fetches the discovery document at your issuer. If it cannot read it, nothing is saved and you are told so. That refusal is deliberate: a broken connection would lock people out of their own account.

7. Test with a second browser

   Sign out, or use a private window, and enter an address on your domain. You should be sent to your provider and returned signed in. Keep your existing signed-in session open until this works.

When you edit an existing connection, leaving the client secret blank keeps the stored one. The field is never populated with the current value — Mirra does not return it to the browser at all.

The settings

Issuer URL

Where your provider's OpenID configuration lives. Must be https. Trailing slashes are trimmed. Mirra fetches the discovery document from it when you save, and caches it for an hour afterwards.Default: Empty

Email domain

The domain that routes to this connection. Somebody typing a matching address at sign-in is handed to your provider; everybody else gets the password form.Default: Empty

Client ID

The application identifier from your provider. Also the audience the ID token is checked against.Default: Empty

Client secret

Stored encrypted, using the same envelope as every other integration credential, and never sent back to a browser. Leave blank when editing to keep the one already stored.Default: Empty — required the first time

Enabled

Whether sign-ins for the domain are actually handed to your provider. Off means the connection is saved and does nothing, which is the safe state while you are testing.Default: Off

Create accounts on first sign-in

Whether somebody your provider vouches for, who has no Mirra account, gets one automatically. Off means they are turned away with "No Mirra account for that address, and automatic sign-up is off."Default: On

What signing in looks like

There is no separate SSO button. Somebody fills in the ordinary sign-in form and presses Sign in; if the domain has an enabled connection, they are handed straight to your provider and the password is never checked against anything. The form still asks for one, because it is the same form everybody else uses — so tell your people to type something in that box and ignore it.

When they come back, Mirra exchanges the code, verifies the ID token's signature against your provider's keys, and only then issues a session.

A sign-in attempt is remembered for ten minutes and held in the memory of the process that started it. If Mirra restarts mid-sign-in, or an install runs several instances without sticky sessions and the return lands on a different one, the attempt shows as expired. Trying again is the whole fix.

Email-domain matching

The domain is checked twice, and the second check is the one that matters. On the way out it decides whether to use SSO at all. On the way back, the address your provider asserts must still be in the configured domain — otherwise a provider that can be talked into issuing a token for some other address would be able to walk into your account with it.

A mismatch fails the sign-in, is recorded, and shows on the sign-in page as "Your identity provider returned an email outside the configured domain."

• The address in the ID token, not the address that was typed, is what the account is matched on.
• An address that already belongs to an account in a different Mirra household is refused rather than moved.
• A domain belongs to one connection. If two accounts on the same install claim the same domain, sign-ins for it go to whichever connection is found first — so use a domain you actually control.

Accounts created on first sign-in

With Create accounts on first sign-in left on, somebody from your domain who has never used Mirra gets an account the moment they successfully sign in. Their name comes from the token, and they are given a password that cannot be used, because they will never need one.

Those accounts are not created as owners. In practice that means a new person can sign in and will find most of the portal closed to them until somebody with full access says otherwise. That is the safe direction for an automatic account to fail in, but it does mean provisioning is not the last step — somebody still decides what each person may do.

1. Open Account and find Who can sign in

   Beside Change password. Every account in the household is listed there with a role beside it.

2. Set the role you want for the new person

   Full access reaches screens, scenes, schedules, photos and billing. Menus only signs in, edits menus, and sees nothing else.

3. If the row already reads Full access but the person cannot reach anything

   Switch the dropdown to Menus only and then back to Full access. The dropdown falls back to showing Full access for a role it does not recognise, so leaving it alone changes nothing. That writes the role for real, and the change takes effect on their next request rather than their next sign-in.

Only an owner can change roles, nobody can change their own, and the last owner cannot be demoted — a household with no owner has lost its screens, its billing and any way of appointing a replacement.

When it goes wrong

A failed round trip returns to the sign-in page with the reason in the address bar rather than silently dropping you back at the form. The message on screen names it.

• domain_mismatch — your provider returned an address outside the configured domain.
• no_account — the person is not in Mirra and automatic sign-up is off.
• wrong_tenant — that address already belongs to an account in a different household.
• expired — more than ten minutes passed, or the attempt was started by a process that has since restarted.
• discovery_failed — the issuer's OpenID configuration could not be read at that moment.
• verification_failed — the code exchange failed, or the ID token did not verify. Check the client secret and that the redirect URI registered with your provider matches exactly.
• missing_code — the provider returned without a code, usually because the sign-in was cancelled.
• Anything else in brackets is your provider's own error code, passed through unchanged.

Turning it off

Remove deletes the connection and everyone goes back to signing in with a password.

1. Give anybody who needs continued access a password first

   Under Who can sign in, an owner can create a sign-in with an initial password and pass it on. The person changes it from their own account page.

2. Press Remove in the Single sign-on section

   You are asked to confirm. The removal is recorded in the audit log.

Accounts created by single sign-on hold no password anybody knows, and Mirra has no password-reset email. Removing the connection leaves those people unable to sign in at all. The repair is for an owner to delete each account under Who can sign in and create it again with an initial password — so do this deliberately, not to see what happens.