VAM signs users in with OpenID Connect (OIDC) against an identity provider that you already run. Set up the identity provider before you run the installer. The Authorization settings on the installer's Deployment Configuration screen ask for the IDs and the secret that you create here, so with them at hand the installation runs in a single pass. See Running the Installer > Deployment Configuration.

This page covers sign-in. The TLS certificates of VAM, including certificates from Active Directory Certificate Services (ADCS), are set separately, in the cert-manager (ADCS) settings of the same screen. See Prerequisites > Certificate Template for ADCS and Running the Installer > View 2: Deployment Options.

Supported Identity Providers

Identity provider

Setup

Microsoft Entra ID

Microsoft Entra ID

Microsoft Entra ID is the only officially supported identity provider. Other options that the installer offers are not officially supported and are experimental.

How VAM Uses Your Identity Provider

VAM uses the tokens of the identity provider in the following places:

VAM component

What it does with the token

Configuration Service

Signs the user in from the browser with the authorization code flow and PKCE. The user's token is the entry point.

VAM API and services

Validate the incoming user token, then act as that user for every downstream call.

Object storage

Exchanges the user token for short-lived, user-scoped storage credentials (STS AssumeRoleWithWebIdentity).

Message broker

Accepts the connections of the VAM services with the token of the VAM service identity, authorized by the messaging roles granted to the application.

Background work

Passes the user's token on while it is valid. Longer work and system jobs run as the VAM service identity (client credentials), with the roles granted to the application.

This shapes the whole setup:

  • Roles travel in the token. VAM authorizes users by the roles claim, and object storage maps the same role values to its storage policies. A user without the right roles signs in but can do nothing. If you manage access through groups, assign the groups to the app roles, so that the tokens of their members carry the role values in roles. The Configuration Service has no screen that maps groups to roles.
  • The service identity needs its own roles. VAM does not exchange the user's token. Work that runs without a user, such as message broker connections and longer background jobs, uses a token that VAM gets for the application itself (client credentials). That token carries only the roles that you grant the application as application permissions, see Add API Permissions and Grant Consent.

Microsoft Entra ID

Microsoft Entra ID (formerly Azure Active Directory) needs the following app registrations:

  • Vizrt Back-Ends, for every VAM client. The Configuration Service, the VAM API, the message broker, object storage and the Pilot web applications all use this one registration.
  • Vizrt MSE, only if the Media Sequencer (MSE) works with Viz Pilot Edge and VAM.

Each app registration comes with an enterprise application, which holds the users and groups that may sign in and their roles. The names of the registrations are free text. This page uses Vizrt Back-Ends and Vizrt MSE. Choose the names that fit your naming convention.

You need an Entra ID account that may create app registrations and grant admin consent, such as an Application Administrator, a Cloud Application Administrator or a Global Administrator.

On this page, replace <vam-host> with the host name that users reach VAM by, for example vam.example.com, and <client-id> and <tenant-id> with the IDs of Vizrt Back-Ends.

The setup has the following steps:

  1. Register Vizrt Back-Ends
  2. Add the Redirect URIs
  3. Expose an API
  4. Define the App Roles
  5. Add API Permissions and Grant Consent
  6. Add a Client Secret
  7. Register Vizrt MSE, only with the Media Sequencer
  8. Force v2 Access Tokens
  9. Assign Users and Groups
  10. Values for the Installer

Register Vizrt Back-Ends

  1. Sign in to the Microsoft Entra admin center. If your account has access to more than one tenant, open your account menu at the top right and use Switch directory to select the tenant that VAM uses.

  2. Go to Entra ID > App registrations and click New registration.

  3. In Name, type Vizrt Back-Ends.

  4. In Supported account types, select Single tenant only - <your tenant>.

  5. In Redirect URI, select Single-page application (SPA) and enter the address of the Configuration Service:

    https://<vam-host>:30443/config/
  6. Click Register.

  7. On the Overview page, note the Application (client) ID and the Directory (tenant) ID. The installer asks for both.

Add the Redirect URIs

Each VAM web application signs in from the browser and needs its own redirect URI on Vizrt Back-Ends:

Redirect URI

Used by

https://<vam-host>:30443/config/

Configuration Service, added during the registration

https://<vam-host>:30443/pilot/pcs-admin/

Pilot Core Service admin

https://<vam-host>:30443/pilot/pilotedge/

Viz Pilot Edge

https://<vam-host>:30443/pilot/template-builder/

Template Builder

https://<vam-host>:30443/pilot/data-server-config/

Data Server Config

Entra ID matches a redirect URI exactly, including the trailing slash. A URI that differs in any character fails the sign-in with AADSTS50011. Each URI is the path that an application is served on, not a callback route beneath it, and Entra ID rejects * wildcards for single-page applications.

  1. Open Authentication.
  2. Under Single-page application, add every URI from the table, one per application.
  3. Click Save.

Write each URI with the port that users type in the browser. For the gateway port 30443 and the load balancer case, see Prerequisites > Network. Add one set of URIs for every host name that users reach the installation by, written as the fully qualified name they type in the browser, for example vam.example.com, not vam.

The Pilot URIs are needed only if you deploy Viz Pilot Edge, Template Builder, the Pilot Core Service admin or Data Server Config. See Pilot Core Service and Viz Pilot Edge.

Expose an API

VAM checks that the audience of a token is the application (client) ID, and the application exposes an Application ID URI for its scopes.

  1. Open Expose an API.
  2. Next to Application ID URI, click Add, accept the default api://<client-id> and click Save.

No scope has to be added, because VAM authorizes on app roles, not on scopes. VAM requests the scope <client-id>/.default, which covers the permissions granted to the application.

Define the App Roles

VAM authorizes on app roles. The Value of a role is what appears in the roles claim of a token. VAM, the message broker, object storage and Pilot Core Service match on it, so the values must be exactly as shown. Display names and descriptions are free text, and you can enter the purpose from the tables as the description.

  1. Open App roles and click Create app role.
  2. Enter Display name, Allowed member types, Value and Description as in the tables below, keep the role enabled and click Apply.
  3. Repeat for every role that your deployment needs.

In Allowed member types, Both stands for Both (Users/Groups + Applications). The roles of VAM:

Display name

Value

Allowed member types

Purpose

VAM-SERVICE

vam

Both

Access to the VAM API. Required: without it, sign-in succeeds but every API call is refused.

VAM-SERVICE Admin

vam-admin

Users/Groups

Access to the Configuration Service, which requires this exact role on every request. There is no read-only tier.

VAM-Storage Read/Write

readwrite

Both

Read and write access to object storage, through the storage policy readwrite.

VAM-Storage Admin UI

consoleAdmin

Users/Groups

Full object-storage administration, through the storage policy consoleAdmin.

VAM-Messaging Write All

<client-id>.write:*/*/*

Both

Message broker write access for the VAM services.

VAM-Messaging Read All

<client-id>.read:*/*/*

Both

Message broker read access for the VAM services.

VAM-Messaging Configure All Vhosts

<client-id>.configure:*/*

Both

Message broker configure access for the VAM services.

kb-agent

kb-agent

Both

Access to the KB-Agent, only if you deploy it.

In the messaging values, replace <client-id> with the Application (client) ID from the Overview page.

The messaging roles authorize the messages between the VAM services. The administration consoles of object storage and the message broker are not part of this setup, so no browser sign-in is set up for them.

If you deploy Viz Pilot Edge and Pilot Core Service, add the following roles as well. Pilot Core Service checks them by their exact value:

Display name

Value

Allowed member types

Purpose

pilot-admin

pilot-admin

Both

Administrator access to the Viz Pilot settings and all Pilot applications. Only this role can open the Pilot Core Service admin and Data Server Config, and it has all rights of the other Pilot roles.

pilot-editor

pilot-editor

Both

Use Viz Pilot Edge to create, edit and delete Pilot data elements.

pilot-journalist

pilot-journalist

Both

Use Viz Pilot Edge to create, edit and delete Pilot data elements. It has the same rights as pilot-editor.

graphic-designer

graphic-designer

Both

Use Template Builder to create, edit and delete templates, script units, concepts, tags, categories, channels and external IDs. It can also use Viz Pilot Edge with the rights of pilot-editor.

pilot-mse

pilot-mse

Applications

Read-only access for the Media Sequencer and other Vizrt services that connect to Viz Pilot.

For how these roles map to the authorization policies of Pilot Core Service, see Pilot Roles and Policies.

Add API Permissions and Grant Consent

Users sign in with the delegated permissions of Microsoft Graph. The VAM service identity uses a token of the application itself, so the application also needs its own roles as application permissions.

  1. Open API permissions.
  2. Check that Microsoft Graph has the delegated permissions openid, profile, email, offline_access and User.Read. Add the missing ones with Add a permission > Microsoft Graph > Delegated permissions.
  3. Click Add a permission, select the My APIs tab, select Vizrt Back-Ends and choose Application permissions. Select vam (VAM-SERVICE), readwrite (VAM-Storage Read/Write) and the messaging roles, plus pilot-mse if you deploy Viz Pilot Edge, and click Add permissions.
  4. Click Grant admin consent for <your tenant> and confirm with Yes. Every permission must show the status Granted.

When you are done, the permissions are:

API

Permission

Type

Admin consent required

Microsoft Graph

email

Delegated

No

Microsoft Graph

offline_access

Delegated

No

Microsoft Graph

openid

Delegated

No

Microsoft Graph

profile

Delegated

No

Microsoft Graph

User.Read

Delegated

No

Vizrt Back-Ends

<client-id>.configure:*/*

Application

Yes

Vizrt Back-Ends

<client-id>.read:*/*/*

Application

Yes

Vizrt Back-Ends

<client-id>.write:*/*/*

Application

Yes

Vizrt Back-Ends

readwrite

Application

Yes

Vizrt Back-Ends

vam

Application

Yes

Vizrt Back-Ends

pilot-mse, only with Viz Pilot Edge

Application

Yes

Without the application permissions, the service identity has no roles, so message broker connections, object storage for background jobs and calls between VAM services are refused. Without admin consent, every user is asked to consent, and permissions that need admin consent are blocked.

Add a Client Secret

VAM authenticates to Entra ID with a client secret, for example when it gets the token of its service identity.

  1. Open Certificates & secrets > Client secrets and click New client secret.
  2. Enter a description, for example VAM, and an expiry that matches your rotation policy.
  3. Click Add and copy the secret value at once, because Entra ID shows it only once. You enter the secret of Vizrt Back-Ends as OIDC client secret in the installer.

Set a reminder before the secret expires. When it expires, VAM can no longer get tokens for its service identity: message broker connections and background work fail, and the VAM service does not start again after a restart. Sign-in to the VAM web applications keeps working. Enter a new secret as OIDC Client Secret under Platform > Authentication in the Configuration Service, see Changing the Provider After Install.

Register Vizrt MSE

Create this registration only if the Media Sequencer (MSE) works with Viz Pilot Edge and VAM. The Media Sequencer calls Pilot Core Service with a token of its own application, and Vizrt MSE is that application.

  1. Go to Entra ID > App registrations and click New registration.
  2. In Name, type Vizrt MSE, and in Supported account types, select Single tenant only - <your tenant>. Leave Redirect URI empty and click Register.
  3. Open API permissions, click Add a permission, select the My APIs tab, select Vizrt Back-Ends and choose Application permissions.
  4. Select vam (VAM-SERVICE), readwrite (VAM-Storage Read/Write), pilot-mse, pilot-admin, graphic-designer, pilot-editor and pilot-journalist, and click Add permissions. The Media Sequencer needs these roles for its work with Viz Pilot Edge and VAM.
  5. Click Grant admin consent for <your tenant> and confirm with Yes. Every permission must show the status Granted.
  6. Create a client secret for Vizrt MSE as described in Add a Client Secret. The Media Sequencer signs in with the client ID and the client secret of Vizrt MSE, so this secret goes into the Media Sequencer, not into the installer.

Role IDs are generated when a role is created, so they differ in every tenant and every app registration, and this page does not list them. If you need them, read them on the App roles page of Vizrt Back-Ends or in its Manifest.

Force v2 Access Tokens

VAM expects v2.0 access tokens, because it validates the v2.0 issuer. Do the following on Vizrt Back-Ends and, if you created it, on Vizrt MSE.

  1. Open Manifest.

  2. In the api section, find requestedAccessTokenVersion. If it is missing, null or 1, set it to 2:

    "requestedAccessTokenVersion": 2
  3. Click Save.

Assign Users and Groups

Entra ID lets every user of your tenant sign in unless Assignment required? is set to Yes, and only assigned users receive role claims.

Assigning a group needs Microsoft Entra ID P1 or P2. Where you can, assign roles to groups rather than to individual users, because groups are easier to manage.

  1. On the Overview page of Vizrt Back-Ends, click the link next to Managed application in local directory. It opens the enterprise application. You also find it under Entra ID > Enterprise apps.
  2. Open Users and groups and click Add user/group.
  3. Select the users or groups and the roles they need, for example vam for everyone who uses VAM, readwrite for the users who work with the stored media and vam-admin for the administrators of the Configuration Service. Click Assign, and repeat for the other assignments.
  4. Open Properties, set Assignment required? to Yes and click Save. Users without an assignment then cannot sign in.

Values for the Installer

On the installer's Deployment Configuration screen, under Authorization, set Security to External OIDC (recommended) and enter the following values:

Installer field

Value

External OIDC provider

Entra

OIDC host URL

https://login.microsoftonline.com

OIDC App ID (tenant)

The Directory (tenant) ID of Vizrt Back-Ends

OIDC client ID

The Application (client) ID of Vizrt Back-Ends

OIDC client secret

The secret value from Add a Client Secret

OIDC shared client ID

The same Application (client) ID. The installer requires the field, and Entra ID uses one client ID for all VAM applications

The installer derives the following values from them. You do not type them in. They are listed for reference and for support cases:

Derived value

Form

Authority

https://login.microsoftonline.com/<tenant-id>/v2.0

Token endpoint

https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

Discovery URL

https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

Requested scope

openid profile email offline_access <client-id>/.default

Role claim

roles

Object Storage Trust

VAM's object storage gives each user short-lived, user-scoped credentials after it validates the user's token itself (STS AssumeRoleWithWebIdentity). For this, object storage does the following:

  • It trusts the issuer of your identity provider. The installer sets the OIDC settings of object storage to the authority and client ID that you entered, so a standard installation needs no manual step.
  • It maps the role claim to a storage policy. Object storage reads the roles claim and looks for a policy of the same name. This is why the role values in Define the App Roles must match the storage policy names:

Role value

Storage policy

Effect

readwrite

readwrite

Read and write objects.

consoleAdmin

consoleAdmin

Full storage administration.

Pilot Core Service and Viz Pilot Edge

If your deployment includes Viz Pilot Edge and Pilot Core Service (PCS), they need the following on top of the base setup. Skip this section if you do not deploy Viz Pilot Edge.

Part

Sign-in

Pilot web applications

Pilot Core Service admin, Viz Pilot Edge, Template Builder and Data Server Config sign in from the browser with the authorization code flow and PKCE. Their redirect URIs are in Add the Redirect URIs.

Pilot Core Service

Validates the user's access token on API calls: it checks the audience, then authorizes on the Pilot roles.

Media Sequencer and other Vizrt services

Call Pilot Core Service with a token of their own application, see Register Vizrt MSE.

The Pilot web applications share the Vizrt Back-Ends registration, because the sso.json of Pilot Core Service maps all of them to one client ID. You can give Pilot its own registration instead, but the redirect URIs must be present either way.

Pilot Roles and Policies

Pilot Core Service authorizes requests on the roles claim, by exact role value. The Pilot roles from Define the App Roles map to its authorization policies as follows:

Policy

Satisfied by the roles

Used for

Pilot admin

pilot-admin

Pilot Core Service admin (schemas, data import and log level) and Data Server Config (search providers, adding and removing Pilot settings)

Graphic designer

graphic-designer, pilot-admin

Template Builder: creating, editing and deleting templates, script units, concepts, tags, categories, channels and external IDs, and changing the values of Pilot settings

Pilot journalist

pilot-journalist, pilot-editor, graphic-designer, pilot-admin

Viz Pilot Edge: creating, editing and deleting Pilot data elements, and listing templates, data elements, concepts, tags, channels and categories

Pilot read-only

pilot-mse, pilot-journalist, pilot-editor, graphic-designer, pilot-admin

Reads by the Media Sequencer and other Vizrt services, for example a data element with its payload, a template with its model, thumbnails and the Pilot settings

The roles add up: pilot-admin satisfies every policy. The Pilot web applications check the roles at sign-in as well. Viz Pilot Edge accepts every Pilot role except pilot-mse, Template Builder accepts graphic-designer and pilot-admin, and the Pilot Core Service admin and Data Server Config accept only pilot-admin. Template Builder shows its settings entry only to pilot-admin. Assign pilot-mse to applications such as the Media Sequencer, not to people.

Audience

Pilot Core Service accepts a token only if it validates the issuer and the audience (aud). The installer configures both. With Microsoft Entra ID, Pilot Core Service expects the client ID of Vizrt Back-Ends as audience (SSO:Audience), and the Pilot web applications request the extra scope <client-id>/.default, so Entra ID issues their tokens for that audience. No separate Pilot API registration is needed.

Collection-Scoped Roles

Besides the roles above, Pilot Core Service supports access per collection. A role whose value is pilot-collection- followed by a collection name, for example pilot-collection-sports, limits a user to the concepts and tags of that Pilot collection. A user without a collection role sees all collections, and graphic-designer and pilot-admin are never limited. A collection role grants no access on its own, so assign it together with pilot-editor or pilot-journalist. Define such roles only if you separate Pilot content by collection, and make the name match a Collection Name in the Pilot Collection Editor of Template Builder. A role that matches no collection does not limit the user. Keep the prefix pilot-collection-, because Viz Pilot Edge expects it.

Changing the Provider After Install

You can change the identity provider settings later in the Configuration Service under Platform > Authentication, for example to rotate the client secret or to point VAM at a different tenant. The section has the following fields:

  • OIDC Provider URL: the authority. For Microsoft Entra ID it is https://login.microsoftonline.com/<tenant-id>/v2.0.
  • Client ID: the application (client) ID.
  • Realm: not used with Microsoft Entra ID. The page marks the field as required while it is empty, which does not block saving.
  • OIDC Client Secret: write-only. A Set or Not set chip shows whether a secret is stored. Leave the field empty to keep the current secret, or paste a new value to rotate it.

When you save, the Configuration Service fetches the discovery document of the provider and checks its issuer against what you entered. A wrong host, realm or tenant is refused before any service is pointed at it. Sign-in is briefly interrupted while a change rolls out.

A new Client ID needs the client secret of the new application in OIDC Client Secret, and Save Changes stays disabled until you enter it. After you save a new Client ID or OIDC Provider URL, the Configuration Service signs you out. Sign in again with an account that has the vam-admin role in the new application and click Keep new settings within 5 minutes, otherwise the change reverts. Then click Apply to all services in the banner, so that the message broker, Pilot and the other services use the new application.

If you point VAM at a different tenant, assign the roles there first, so that users are not locked out. The checks and the safety window that apply to every platform change are described in Platform Settings > Validate Before Apply, and the Safety Window.

Troubleshooting Sign-In

Symptom

Cause and fix

After the sign-in at the provider, an error page reports a redirect URI or reply URL mismatch (AADSTS50011).

The redirect URI is not registered exactly. Add the exact URI, with scheme, host, port, path and trailing slash, see Add the Redirect URIs.

Sign-in succeeds, but every VAM action is refused or the UI stays empty.

The user has no vam role. Assign it, see Define the App Roles and Assign Users and Groups.

A user signs in to the Configuration Service but cannot use it.

The account lacks the vam-admin role, which the Configuration Service requires on every request. Assign it, see Assign Users and Groups.

Uploads or downloads fail with an access denied error from storage, although the user is signed in.

The user lacks a storage role, or the role value does not match a storage policy name. Use exactly readwrite or consoleAdmin, see Object Storage Trust.

Background jobs cannot access storage, although interactive use works.

Background jobs run as the VAM service identity, and its token has no storage role. Grant the application its own readwrite role as an application permission and grant admin consent, see Add API Permissions and Grant Consent.

Users are asked to consent one by one, or application permissions are blocked.

Admin consent was not granted. Grant it, see Add API Permissions and Grant Consent.

Conditional Access blocks the sign-in, for example because the device is not managed or not compliant.

A Conditional Access policy in your tenant blocks the device or network. Ask your Entra ID administrator to allow the device, or to adjust the policy for the application.

After weeks without problems, message broker connections and background work fail, and the VAM service does not start again after a restart. Sign-in to the VAM web applications keeps working.

The client secret has expired, so VAM can no longer get tokens for its service identity. Create a new secret, see Add a Client Secret, and enter it as OIDC Client Secret under Platform > Authentication.

Token validation fails, or the role claim is missing.

The access tokens are still v1. Set requestedAccessTokenVersion to 2, see Force v2 Access Tokens.

Pilot Core Service returns 401 Unauthorized for a user who can sign in to the rest of VAM.

The token most likely has the wrong audience. Check that the Pilot web applications request the scope <client-id>/.default and that SSO:Audience of Pilot Core Service matches the aud of the issued token, see Audience.

Sign-in fails although the settings look right.

Tokens are time-sensitive. Check that the clocks of the cluster nodes are synchronized (NTP).

To check the live settings, open Platform > Authentication in the Configuration Service and compare the OIDC provider URL and the client ID with Values for the Installer. If a change to these settings locked you out of the Configuration Service, see Troubleshooting the Configuration Service > Cannot Sign In.