What your IT department prepares before anything is configured in Viz Mosart: the OIDC client, the roles, and the certificate. At the end of this page, IT hands back three values: the Authority (issuer) URL, the Client ID and the Client Secret.

The identity provider

Any standards-compliant OpenID Connect provider works. Keycloak, Okta and Microsoft Entra ID are the ones documented and tested. Your IT department needs to:

  1. Create an OIDC client, or app registration, for the Mosart Web Apps, using the authorization code flow with a client secret, and register these URIs on the Web Apps host:

    Purpose

    URI

    Redirect

    https://<webapps-host>/signin-oidc

    Post-logout redirect

    https://<webapps-host>/signout-callback-oidc

    Provider-initiated logout, optional

    https://<webapps-host>/signout-oidc

  2. Define roles with exactly these names, for the apps you use:

    • mosart-admin, mosart-viewer for the Named Overlays Editor

    • showmaker-admin, showmaker-viewer for Showmaker

    • smartpanel-admin, smartpanel-viewer for Smart Panel and the Timing Display

  3. Make sure the roles reach the tokens as described in The roles claim below.

  4. Assign the roles to your users or groups.

  5. Allow the scopes the Web Apps request, as described in The scopes below.

  6. If a Generic REST device will call the Mosart REST API, create a separate client for it, using the client credentials flow, and assign the roles that device needs (for example mosart-admin to manage named overlays) to that client's service account. A device token carries the service account's roles, not a user's. Hand its Client ID and secret to whoever configures the device.

  7. Hand back three values:

    Item

    Used by

    Authority, or issuer, URL

    both the Mosart servers and the Web Apps

    Client ID

    the Web Apps, and the audience value on the Mosart server

    Client secret

    the Web Apps only

The scopes

The Web Apps always request openid, profile and email. Anything else is added in the Scopes field of the Web Apps Configuration Tool, and the client in your identity provider has to allow it.

One scope is worth adding deliberately: offline_access.

A sign-in gives the Web Apps tokens that expire, typically within an hour, and the session itself has a lifetime too. Someone working in an app never notices, because their activity keeps the session alive, and if it ever ends they simply sign in again. A screen that nobody is sitting at is different: a Rundown Viewer or Smart Panel on a gallery wall has no one to sign it back in, so when its session ends it is redirected to the provider's sign-in page and stays there, showing a login form for the rest of the day.

Requesting offline_access asks the identity provider for a refresh token, which lets the Web Apps server obtain fresh tokens in the background, with no user present. Add it whenever any screen runs unattended.

Info: Most providers allow offline_access by default, but some require it to be enabled per client. If unattended screens still end up on a sign-in page after a few hours, check that the provider is actually issuing a refresh token for this client.

The roles claim

The claim carrying the roles must be:

  • flat and top-level, not nested. Keycloak's default realm_access.roles is not read, because the claim name is matched exactly. Add a protocol mapper that writes a top-level roles claim.

  • named exactly roles.

  • present in both the ID token and the access token.

That last point is the most common misconfiguration in a new installation:

Layer

Reads

Decides

Mosart Web Apps server

the ID token

whether an app opens, and which controls appear

Mosart server

the access token

whether the REST API accepts the call

If the roles reach only the ID token, the apps look completely correct and every save fails. In Keycloak, the role mapper must be enabled for the ID token and the access token separately. In Microsoft Entra ID, app roles that you have defined and assigned are emitted in a roles claim with no further claim mapping.

For a provider-specific walkthrough, see Vizrt SSO (Keycloak) in the Appendix.

The certificate

Authentication requires HTTPS with your own certificate; the built-in one is not enough. One certificate covering every host that presents it is simplest. Ask IT for:

  • Type: X.509.

  • Format: PEM-encoded certificate and private key. A .pfx must be converted to PEM first.

  • Key type: RSA. ECDSA is not supported.

  • Encryption: the private key must be encrypted and supplied with its password. An encrypted key begins with -----BEGIN ENCRYPTED PRIVATE KEY-----.

  • Host coverage: the Subject Alternative Names must cover the Web Apps host and both Mosart servers. If the certificate names hosts by fully qualified domain name, the addresses you enter in Mosart and in the Configuration Tool must be fully qualified too. The comparison is case sensitive.

Trust the certificate everywhere

The certificate must be trusted on every machine involved: the Web Apps and proxy host, each Mosart server, and each machine running a browser client.

An untrusted certificate normally shows as a browser warning. When a Mosart web app is embedded as a plugin inside another application, such as ENPS, there may be no warning at all and the page simply stays blank.

Trust also runs the other way. Each Mosart server connects to the identity provider to validate sign-ins, and it checks the provider's certificate the same way a browser does. So the identity provider's certificate must be trusted on both Mosart servers, and the authority host name must resolve correctly from each of them.