App addresses

Beta: give one app, or a whole workspace, its own web address. People who open it see only the app, with the same sign-in and permissions as anywhere in MaestroHub.

Where

System Management › App addresses

Who

Platform administrators

Before SAML works

Check each address once

Beta

App Studio is in release 3.0 as Beta: a paid add-on that no edition includes by default.

The app link opens one app full screen from a path on MaestroHub's own address. An app address goes one step further: a web name of its own, such as andon.plant.example for the andon board on line 3, or hall-b.plant.example for every app of the hall B workspace. People who open it see only the app (or, for a workspace, the apps of that workspace they may open), with the same strip, the same sign-in and the same permissions as the app link. An address that is not on the list keeps opening MaestroHub as before.

The address decides what people see, not what they may do: a person's sign-in works on every address that reaches MaestroHub, and their permissions are what limits them.

Before you add an address

MaestroHub's own public address must be set first (System Management → Email → Public address). Until it is, the App addresses page shows that notice, with a link to set it, above the steps below, and Add address stays disabled with the same reason written beside it. This way an app address can never take MaestroHub's own place.

Then do the parts MaestroHub cannot do for you. The page lists them under "What you need to do outside MaestroHub", with only the lines for how this MaestroHub runs (the single binary, or the Helm chart, where it also lists the names the chart's ingress routes now); the list folds under its title once an address is confirmed, and Show steps opens it again:

• DNS: point the name at this server. Without DNS, put a hosts-file entry on every station and on MaestroHub's own server, which checks the name itself: on Windows, open C:\Windows\System32\drivers\etc\hosts in an editor started as administrator and add a line with the IP address of the machine people connect to (the IIS or nginx server when one is in front, otherwise MaestroHub's) and the name, such as 10.20.30.40 andon.plant.example, then run ipconfig /flushdns. With SAML, add MaestroHub's own name too. IP addresses cannot be app addresses.
• Routing: route the name to MaestroHub in your proxy, keeping the Host header, or sending X-Forwarded-Host from a proxy listed in http.trustedProxies. Otherwise live values do not update and the address cannot be confirmed. On Helm, add the name to ingress.extraHosts; the page then marks a name you forgot as Not routed, and shows only the steps for how this MaestroHub was deployed.
• HTTPS: use a certificate that lists the name. On the single binary (Lite) that is the certificate in http.tls.certFile, which Lite serves for every name; on Helm, add the name to an ingress.tls[].hosts entry.
• Single sign-on: register each address's callback and sign-out address with every OIDC provider; the page copies both for you. In Entra ID, add both to App registrations → your app → Authentication → Web platform → Redirect URIs, and leave Front-channel logout URL alone; the operator guide says where ADFS, Okta, Keycloak and Google keep them. For SAML, the station must also reach MaestroHub's own address, where the identity provider sends its answer.
• Proxy headers: the proxy must not send Referrer-Policy: no-referrer, or apps do not start.

App addresses cannot work on Siemens Industrial Edge, where the device's proxy owns the names, or when the UI calls the API on another address (an absolute apiURL).

Adding an address

System Management → App addresses → Add address asks for:

• Address: the name, with a port only if it is not the usual one (andon.plant.example, andon.plant.example:8443). The field says at once when a name cannot be used, and why.
• This address uses HTTPS or plain HTTP: choose how people will open this address. It starts on the scheme you are using MaestroHub with right now. Choosing plain HTTP warns that Entra ID, Okta and Google refuse sign-in addresses that are not HTTPS, and that browsers will not open a plain-HTTP name under a company domain that forces HTTPS.
• Opens: one app, or a whole workspace. Choose the workspace, then search for the app by its name or what it does; the list shows the apps you may read there, a page at a time. For an app you cannot read (a platform administrator who is not a member of the workspace), choose The app isn't in the list? and enter its id: a workspace administrator copies it from the app's Settings and operations page (App id). Or choose the whole workspace.
• Shared station: sign people out after this many minutes without input: empty means never. Use it only on an address meant for shared stations, from 5 to 480 minutes: phones and personal computers opening it are signed out too. A separate address for floor stations keeps phones out of it, and screens nobody touches should be paired displays. MaestroHub's server enforces it; see Idle sign-out.
• Note: what the address is for, such as "line 3 andon, hall B".

Save stays disabled until the form is complete, and says what is missing. Before anything is saved, MaestroHub shows the address in large type and asks "Is this exactly your name?", because single sign-on may send sign-in tokens to it. Check every letter: a name one letter off can belong to someone else.

These names are refused, each with its reason:

• MaestroHub's own address, on any port and either scheme;
• the address you are using MaestroHub at right now;
• localhost and every name under it, and every IP address, including short forms such as 127.1;
• names with an underscore or with a dot at the end, which Safari and iPad cannot start apps on;
• a * name, a path, a user name or password, a port with a leading zero;
• letters outside a to z: use the name's xn-- form, which your DNS provider shows.

Confirming an address

A new address opens the app at once, and password, LDAP and OIDC sign-in work there (OIDC once the provider knows its callback). SAML sign-in to it stays off until the address is confirmed, which proves the name really reaches this MaestroHub. Until then, the SAML button on the address's sign-in page is disabled, with "SAML sign-in starts here once your MaestroHub administrator confirms this address (System Management → App addresses → ⋯ → Check)." under it, and sign-in never starts on its own with SAML there. OIDC buttons are not affected.

The button says why when SAML cannot start for another reason: "SAML sign-in is paused here because MaestroHub's own address is not set. Tell your MaestroHub administrator." while MaestroHub's own address is unset, and "SAML sign-in is not available on this address. Ask your MaestroHub administrator to check it under System Management → App addresses." when the name is now MaestroHub's own address or the page was opened over the other scheme.

To confirm an address, press ⋯ → Check on its row. MaestroHub's own server then opens the address itself, the way a station does, and asks it a question only this MaestroHub can answer. When the answer comes back from this MaestroHub, under that name, the row reads "Confirmed" with the date. Nothing is handed to the address for this: there is no link or code that someone could copy and use.

Because the server does the check, the name must work from MaestroHub's server too, not only from the stations. When it does not, Check says what it found and what to do, for example:

• "MaestroHub's server could not look up address.": add the name to the DNS server MaestroHub's server uses, or to its hosts file, pointing at your proxy's network address (MaestroHub never checks a name through 127.0.0.1).
• "MaestroHub's server could not connect to address.": a firewall, or a network that does not route back to itself, stops the server reaching the name. Let it through, or point the name at the proxy in the server's hosts file.
• "MaestroHub's server does not trust the certificate address presents": use a certificate from a certificate authority the server trusts (on Windows the computer's Trusted Root store, on Linux the system bundle or SSL_CERT_FILE).
• "The address address reaches MaestroHub, but the proxy at IP is not listed in http.trustedProxies": list that proxy in http.trustedProxies and restart MaestroHub.
• "The address address reaches MaestroHub, but your proxy changes the name on the way": keep the Host header, or send X-Forwarded-Host from a trusted proxy.

A confirmation lasts 7 days, and MaestroHub's server checks every confirmed address again each day, which renews it. If the address answers as something else (a redirect away, another name, an answer this MaestroHub did not make), the row says so and the address is asked again an hour later; if that answer holds, the confirmation is turned off and SAML sign-in stops there. An error page, a 502 from a proxy while MaestroHub restarts, another MaestroHub version during an upgrade, or a name the server cannot reach for a while keeps the confirmation until its 7 days run out; the row shows the last check's reason, and "ends soon" two days before. Pressing Check yourself never turns a confirmation off. ⋯ → Open opens the address in a new tab, to see what people see; it does not confirm anything. A confirmation cannot catch a new holder of the name who passes every request on to this MaestroHub: delete an address when you give its name up.

What confirming protects against: a mistyped name, a name not yet in DNS, or a parked domain. Someone who holds a mistyped name cannot confirm it for you: MaestroHub's server must reach this MaestroHub through that name, and nothing they can send to MaestroHub, or copy from you, stands in for that. What it cannot protect against: a holder of the name who forwards every request to this MaestroHub, as a proxy would. That is why the Add dialog shows the exact name back before you save it.

The list

Each row shows the address, what it opens, the note, when it was confirmed, when it was last opened, and who changed it and when. On a phone the note, last-opened and changed columns are left out, and a row nobody has opened yet shows Never opened under its address. While any address is not confirmed, the page explains once, above the list, how to confirm it. A target the administrator may not read says "you can't see its name"; MaestroHub never shows app names across workspaces.

Marks on a row tell what to fix, each with its explanation written under it:

Mark	What it means
Not confirmed yet	Press Check (the row's ⋯ menu). MaestroHub's server checks the name and says what is in the way, if anything.
Never opened	Nobody has opened it yet: DNS, proxy or certificate may not be set up.
Opened over the other scheme	Someone opened it over http when it is set up for https, or the reverse. Fix old bookmarks, or change the entry's scheme.
Not routed	Helm only: the name is not ingress.host and not in ingress.extraHosts, so the chart's Ingress will not send it to MaestroHub. If another route serves it, Check still confirms it; otherwise add it to ingress.extraHosts and upgrade the release. On the single binary, and on Helm with the chart's Ingress off, MaestroHub cannot see your routing, so this mark never shows.
Target deleted	The app or workspace it opens no longer exists. People opening it are told it opens no app they can use. Point it elsewhere, or delete it.
Shadowed by MaestroHub's own address	The name is now MaestroHub's own address, so it opens MaestroHub. Delete the entry.
Paused	MaestroHub's own address is no longer set. The app still opens here, but SAML sign-in and Check are off until you set it again.
Can't be used: delete it and add it again	The address was saved under rules MaestroHub no longer accepts, so the name opens MaestroHub itself, not the app. The row says which rule, in MaestroHub's words. Check, Open and Edit are withheld; delete it and add it again.

Copy sign-in addresses on a row copies the two addresses an OIDC provider needs for it, each on a labelled line: the Callback, <address>/auth/oidc/callback, and the Sign-out address, <address>/auth (both with MaestroHub's sub-path, when it has one). Copy all sign-in addresses above the list copies them for every address at once, for your identity provider team. Paste each address without its label: in Entra ID, both go under App registrations → your app → Authentication → Web platform → Redirect URIs; in ADFS, add both addresses under the Application group → Server application → Redirect URI; registering the sign-out address too does no harm. On an http address, the copied message reminds you that Entra ID, Okta and Google won't accept these http addresses. The operator guide has Okta, Keycloak and Google.

Edit changes what an address opens, its scheme, its idle sign-out and its note; the name itself cannot change: to use another name, add it and delete this one. An address with port 80 or 443 in it can't switch between http and https: that port is the other scheme's default, so the address itself would change. Delete it and add it again with the new scheme. Changing what it opens, or its scheme, turns SAML sign-in off there until you confirm it again, and when a SAML provider is set up, the dialog says so before you save and the message after saving offers Check. A note or idle change keeps the confirmation.

Delete removes the address; the name then opens MaestroHub itself. The dialog reminds you to remove its callback and sign-out address from each OIDC provider too.

On the address

People who open an app address see the app with the app link's strip. A workspace address shows the apps of that workspace the person may open. A signed-out person signs in there and comes back to the app; when exactly one single sign-on provider is set up, sign-in starts on its own. With idle sign-out set, the station signs people out after that many minutes without input; see Idle sign-out.

Someone who may not open the app, or whose app or workspace was deleted, sees "This address doesn't open an app you can use. Ask your MaestroHub administrator." On a workspace address with no app the person may open, the page says "There are no apps here you can open. Ask your workspace administrator for access.": the address works, and giving access to the workspace's apps is a workspace administrator's to do.

Two habits help on shared stations:

• On an address where sign-in starts on its own, the sign-in page first shows "Signing in with provider…" for three seconds, with Sign in another way. A person who signs in with a password or LDAP presses it and stays on MaestroHub's sign-in page: no browser Back button is needed, so this works on a kiosk tablet too.
• To pair a new wall screen on an app address, open <address>/pair directly, such as https://andon.plant.example/pair.

SAML with more than one auth replica

When the auth service runs more than one replica (Enterprise on Kubernetes), a SAML sign-in request is remembered only by the replica that sent it. A sign-in answer that comes back to another replica is still checked for its signature, issuer, audience, time window and recipient, but not tied to the request this browser started, so the protection against a replayed or unrequested answer holds only with a single auth replica. This is tracked as #8116. OIDC sign-in is not affected: its sign-in travels in a sealed cookie in the person's browser and completes on any replica. See the operator guide.

Idle sign-out

What the server enforces. A person who signs in on an address with idle sign-out set gets a session bound to that many minutes. Input on the page and inside the app (a key, a pointer, a touch) is reported to MaestroHub's server, at most once every 30 seconds for the whole station. When that many minutes pass with no input, the server refuses to renew the session, and the session's own access has already run out at that moment, and so has the app's: an app's token never lasts longer than the sign-in it came from. At the same moment the page signs the station out and closes the app. Reloading the page, closing the tab, restarting the browser or rebooting the station does not reset the time: the next person finds the station signed out, not signed in as the last person.

What the page shows. The page shows the server's time, it does not keep its own. A minute before the time runs out the strip says "Signing out in 60 s. Touch the screen or press a key to stay signed in."; then the station shows "Signed out after N minutes without input." and offers to sign in again. Every tab of the station shows the same time, so a tab nobody touches never signs out a tab someone is using.

When a change applies. The minutes are fixed when a person signs in. Changing or removing the idle sign-out, or deleting the address, applies to the next sign-in there; it never shortens or lengthens a session already open. To apply a change at once, sign the station out. Paired displays are never signed out by idle sign-out, and sessions signed in on MaestroHub's own address are not affected.

Who can manage addresses

Platform administrators who hold the address permission (the same one as MaestroHub's public address), signed in as themselves. No access token, AI client or paired display can read or change the list, and an administrator who is impersonating someone is refused.

Everyone who can read an app sees the addresses that open it: in the app's menu on the Apps page, as Copy andon.plant.example (and, for its workspace's address, Copy hall-b.plant.example/apps/andon), and on the app's Settings and operations page under Its own addresses, which also says when an address is not confirmed yet. Deleting the app names its own addresses: they keep pointing at it, and people who open them are told it opens no app they can use, until a platform administrator points them elsewhere or deletes them.

A workspace administrator sees Give this app its own address (or Give this app another address, once it has one) in the app's menu and on its Settings page, disabled with "Only a platform administrator can do this: System Management → App addresses." A platform administrator who chooses it lands on the Add dialog with that app chosen.

If an address stops working

MaestroHub is always reachable on its own public address, and on the single binary also on any IP address and on localhost, because none of them can ever be an app address. So a wrong entry never locks administrators out. The operator guide has the commands for Kubernetes and a table of symptoms and fixes.