Skip to content

Installing Smarter Visitor Registration

From the deployment in Azure to the first sign-in: which resources are created, which permissions are required and how you put the application into operation.

How the installation works

Smarter Visitor Registration is deployed directly from Azure Marketplace into your own Azure subscription. The wizard creates the Azure resources, installs the certified application package and waits until the application is available. Allow about 20 to 30 minutes when the required permissions are ready.

Only the Microsoft Entra steps before and after the deployment use our scripts once. The normal Marketplace flow requires neither a local ARM template nor a manual ZIP upload. Open the Marketplace installation in the Azure portal.

1

Preflight: subscription, names and providers

Complete these checks before preparing the app registration or selecting Create. A Microsoft 365 tenant is not itself an Azure subscription. Run the commands in Azure Cloud Shell with Bash.

CheckAction
Subscription and billingUse an active Azure subscription in the correct company tenant with billing agreed. A Free Trial does not guarantee B1 capacity. The label Azure Plan alone does not prove that restrictions have been removed.
App Service quotaSearch the portal for Quotas, select App Service (Public Preview), the subscription and target region — not Compute. At least one additional B1 instance and sufficient regional total quota are required. For SubscriptionIsOverQuotaForSku with limit 0, request a new total of at least 1. If ineligible, ask the billing owner to check subscription eligibility first.
Free Trial upgradeUse Upgrade subscription or the upgrade banner in the subscription overview. If unavailable, contact the billing owner or Azure billing support; do not create a second subscription just because the button is missing. Pay-as-you-go enables billable usage; upgrading does not guarantee immediate quota or regional capacity.
Company-specific namesDo not simply accept visitorreg. Examples: prefix firma-vr-gwc-01, web app firma-visitor-gwc-01, resource group rg-firma-vr-gwc-01. Examples are not reserved. The prefix creates globally unique Cosmos DB/Key Vault names; the web app name must also be globally available. Choose names before running the preparation script.
Active permissionsAzure RBAC and Entra roles are separate. A PIM Eligible assignment is not active: activate the required role for the deploying user in the correct tenant, then sign in again. If an operation fails, check its actual executing identity instead of blindly adding more roles.

Check resource providers

This first block only reads the active subscription and provider states. Providers cover the web app, Cosmos DB, identities, Key Vault, monitoring including Microsoft.OperationalInsights for Log Analytics, plus Storage and Container Instances for package installation. Verify the customer subscription before proceeding.

Bash — read-only precheck
az account show --query "{subscription:name,id:id,tenant:tenantId}" -o table

for provider in Microsoft.Web Microsoft.DocumentDB Microsoft.ManagedIdentity Microsoft.KeyVault Microsoft.Insights Microsoft.OperationalInsights Microsoft.Storage Microsoft.ContainerInstance; do
  az provider show --namespace "$provider" \
    --query "{Provider:namespace,Status:registrationState}" -o table || break
done

Only if providers are missing: the next block registers those services in the active subscription. It creates no web app or database and grants no Graph consent. Registration needs subscription-level register permissions (for example Contributor/Owner); resource-group-only access is insufficient.

Bash — register missing providers
for provider in Microsoft.Web Microsoft.DocumentDB Microsoft.ManagedIdentity Microsoft.KeyVault Microsoft.Insights Microsoft.OperationalInsights Microsoft.Storage Microsoft.ContainerInstance; do
  state=$(az provider show --namespace "$provider" --query registrationState -o tsv) || break
  if [ "$state" != "Registered" ]; then
    echo "Registering $provider (current status: $state)"
    az provider register --namespace "$provider" || break
  else
    echo "$provider: Registered"
  fi
done

Check progress explicitly

Registration is asynchronous. Repeat the precheck afterwards. For a simple readiness check, wait for Registered. Registering is not necessarily an error: Azure registers regions separately. There is no fixed completion time. If a command fails, check the error and target subscription before deploying.

Microsoft guidance: Resource providers, App Service quotas and Free Trial upgrade.

2

What the two SBS scripts change

Download the scripts using this guide and inspect them in an editor first. The Cloud Shell guide explains downloading and running them. These are administrative changes in your tenant, not read-only checks.

Script / whenChanges and purpose
prepare-app-registration — before deploymentCreates or updates Visitor Registration and its service principal. Configures sign-in/redirect URLs, API scope, requested delegated Graph permissions and Office/Teams pre-authorisation; prints the client ID. Creates no Azure hosting resources and does not grant tenant-wide Graph consent.
grant-graph-permissions — after deploymentReads -identity from the specified resource group and assigns User.Read.All and Group.Read.All as Graph application permissions: tenant-wide user/group read access without a signed-in user. With the client ID supplied, it also grants or updates tenant-wide consent for the documented delegated permissions including Mail.Send. The script itself sends no emails.

Review targets and privileges first

The preparation script reuses a registration with the same display name and updates its configuration. Use a separate prefix per environment, never another or production app for a new test. Always supply the client ID to the second script. Neither script deletes visitor data, but they change authentication and permissions. Preparation needs Application/Cloud Application Administrator; granting Graph application permissions needs Privileged Role Administrator (Global Administrator is also supported). Azure Owner alone is not sufficient.

3

Failure recovery: redeploy or change region?

Open the failed nested deployment and its Error details / Raw error. DeploymentFailed or Conflict alone is not the root cause. Record the error code, region and correlation ID; do not share secrets or SAS tokens.

ErrorNext action
Provider not registeredRegister the required provider named in the error, especially Microsoft.OperationalInsights for monitoring. Then retry with unchanged deployment values.
B1 VMs: 0 / SubscriptionIsOverQuotaForSkuResolve subscription eligibility and quota first. Provider registration and admin consent cannot fix quota. Retry only with sufficient available capacity allowance.
Cosmos DB: high demand in North Europe region … cannot fulfill your requestThis specific error indicates an Azure regional capacity/access restriction, not a visitor application error. Check another approved region or request regional access through Microsoft support. Germany West Central is an alternative, not a capacity guarantee.
Authorization_RequestDenied / graphPermissions-deploymentCheck the active Entra role, tenant and actual executing identity. App-registration admin consent and managed-identity Graph application roles are separate grants. Sign in again; if it still fails, send SBS the full nested error.
Cosmos account already in Failed stateDo not repeatedly redeploy. Resolve the original creation error. Only if Azure explicitly requires recreation and this is an empty failed first installation, delete the specifically affected account after checking it. Never delete an account containing data without a backup/migration plan.

Retrying in the same region

After fixing the cause, keep the same subscription, resource group, region, prefix, web app name, client ID and administrator object ID. Re-enter the stored session/JWT secret and retain successful resources. Secure parameters may not be carried over: do not assume a blank artifact SAS value is correct or invent package URLs. Ask SBS if artifact parameters are unclear.

  1. For a region change during a failed first installation, do not just change Location on Redeploy. Choose a new empty resource group, a new company-specific prefix and a new globally unique web app name.
  2. Check quota and providers first. Run the preparation script with the new names and use its client ID. Then start a new Marketplace deployment.
  3. Validate the new installation including sign-in before cleaning up old test resources. Check data, other uses and costs first. Delete an entire old resource group only if it belongs exclusively to this failed test and contains no required data.
  4. Deleting a resource group does not delete the Entra app registration. Have obsolete test registrations reviewed and removed separately. Parallel resources may incur costs. Existing production data needs a planned migration, not a new installation followed by deletion.
4

Prerequisites

AreaRequirement
AzureOwner on the target resource group or subscription; alternatively Contributor plus User Access Administrator. The template assigns one narrowly scoped role to a temporary deployment identity.
Microsoft Entra IDApplication Administrator to create the app registration, plus Privileged Role Administrator or Global Administrator for Graph application roles and admin consent.
WorkstationRecommended: Azure Cloud Shell with Bash. Alternatively, use Azure CLI and the Bash or PowerShell scripts locally.
Microsoft 365Exchange Online for the Outlook add-in and for sending emails, optionally Microsoft Teams.
Object ID of the first administratorThe Entra object ID of the person who carries out the initial setup. You find it in the user profile in the Entra admin center or with az ad signed-in-user show --query id -o tsv.
Session secretA random string of at least 32 characters, for example from openssl rand -hex 32.
Azure regionA region with App Service, Cosmos DB Serverless, Azure Container Instances and a storage account. Check quota first; for capacity restrictions, follow the region-change instructions above.

No first sign-in without an object ID

As long as no admin group is set up, only the object IDs specified during deployment may open the settings. If the value is left empty, nobody can carry out the initial setup.

5

What is created in Azure

ResourcePurpose
App Service (Linux, Node.js 22)The web application with terminal, settings, analytics and the interface for the Outlook add-in. HTTPS only, TLS 1.2 or higher.
Azure Cosmos DB (Serverless)Database with the containers for planned appointments, visitor contacts, check-ins, settings, audit log and files.
Managed identityReads group memberships and users through Microsoft Graph (application roles Group.Read.All and User.Read.All). No client secret is required.
App registrationSign-in for browser, Outlook and Teams. Exposes the scope access_as_user; Outlook and Teams are already pre-authorised for it.
Application Insights (optional)Logs and telemetry for operations.
Key Vault (optional)Stores the database key and the session secret instead of keeping them in the app settings.

The running Azure costs depend on the pricing tier and on usage. In the smallest configuration (App Service B1, Cosmos DB Serverless) they are around 20 euros per month as a guide value. Microsoft bills these Azure resources to you directly.

Licensing and billing

The current Marketplace offer is an Azure Application (Solution Template). Deployment starts the SBS licence trial, but it does not create an automatic Marketplace charge for the SBS licence. The License page in the application shows the status, validity and number of configured locations.

6

Preparing the app registration

The application signs users in through an app registration in Microsoft Entra (browser, Outlook, Teams). Azure Marketplace cannot create this registration in your tenant. First choose the final web app name and deployment prefix, sign Azure CLI in to the target tenant and then run the preparation script.

Not comfortable with az or Bash yet?

Open the step-by-step Azure Cloud Shell and Azure CLI help. It requires no local CLI installation and provides copy-ready commands for both SBS scripts.

Connect to the target tenant and subscription
az login --tenant <tenant-id>
az account set --subscription <subscription-id>
az account show --query "{subscription:name, tenant:tenantId, user:user.name}" -o table
Azure CLI, signed in with an account that may create app registrations
# Bash
./prepare-app-registration.sh <web-app-name> <deploymentName>

# PowerShell
.\prepare-app-registration.ps1 -WebAppName <web-app-name> -DeploymentName <deploymentName>

Use the same web app name and prefix as later in the deployment. The script creates the registration “Visitor Registration <deploymentName>” with the redirect URIs, the scope access_as_user, the pre-authorisation for Outlook and Teams and the identifier URI api://<name>.azurewebsites.net/<client ID>, and prints the client ID. A second run updates the existing registration. Download: prepare-app-registration.sh, prepare-app-registration.ps1.

Keep the client ID for the Marketplace wizard

The script prints the client ID. Copy it for the deployment. Do not reuse an app registration from another tenant or an earlier test installation.

7

Deploy from Azure Marketplace

Open Smarter Visitor Registration – Standard in the Azure portal and select Create. We recommend a new, empty resource group.

Azure Marketplace wizard on the Basics step with subscription, resource group, region, deployment prefix and web app name
On Basics, choose the subscription, a new resource group and the region, then enter unique deployment and web app names.
Wizard stepValue or recommendation
BasicsTarget subscription, a new resource group and Azure region. “Germany West Central” has worked reliably for tests.
Deployment prefix3 to 20 lower-case letters, numbers or hyphens, specific to your company and environment, for example firma-vr-gwc-01. Do not simply accept visitorreg; see the preflight checks.
Web app nameGlobally unique name. It becomes part of https://<name>.azurewebsites.net and must exactly match the value used by the preparation script.
Azure configurationKeep App Service “Basic B1”, Cosmos DB “Serverless”, Application Insights and Key Vault enabled.
Initial administratorObject ID of the person who opens the setup wizard afterwards.
Entra applicationClient ID printed by prepare-app-registration.
Session secretEnter the random value of at least 32 characters twice.
Azure configuration with App Service Basic B1, Cosmos DB Serverless, Application Insights and Key Vault
Recommended starting values: App Service B1, Cosmos DB Serverless, with Application Insights and Key Vault enabled.
Marketplace Identity and security step with fields for administrator object ID, Entra client ID and session secret
On Identity and security, enter the first administrator object ID, the client ID created earlier and a new session secret.

Do not supply package paths or ZIP files

Azure Marketplace supplies the signed artifact location automatically. Do not change _artifactsLocation or _artifactsLocationSasToken. The normal Marketplace flow requires neither az deployment group create nor az webapp deploy.

Select Review + create and then Create. Deployment usually takes 10 to 15 minutes. The final longer-running step is <prefix>-install-package: it installs the certified package and waits for the health endpoint.

The address is tied to the installation

Sign-in, the Outlook manifest and the Teams app use the address <name>.azurewebsites.net. Choose the name of the web app with care. A custom domain requires additional changes to the app registration. Please contact us about this.

8

Verify the deployment

After a successful Marketplace deployment, the application is already installed. Check the public health endpoint first:

curl https://<name>.azurewebsites.net/api/health

Expected response

{"status":"ok","timestamp":"…"} with HTTP status 200. Then open https://<name>.azurewebsites.net/.

Safe to run again

If only <prefix>-install-package fails, open its log in the resource group. You can start the deployment again with the same values; the template is idempotent.

9

Grant Graph permissions and admin consent

Run the second script once after the Marketplace deployment. It assigns the required Microsoft Graph application roles to the managed identity and grants tenant-wide admin consent to the app registration.

Bash or PowerShell
# Bash
./grant-graph-permissions.sh <resource-group> <deployment-prefix> <client-id>

# PowerShell
.\grant-graph-permissions.ps1 -ResourceGroup <resource-group> -DeploymentName <deployment-prefix> -ClientId <client-id>

Expected output

Group.Read.All: assigned, User.Read.All: assigned and admin consent granted. Microsoft Graph can take a few minutes to use the new permissions.

PermissionTypePurpose
User.Read, User.ReadBasic.All, People.ReaddelegatedSign-in and people search
Group.Read.AlldelegatedGroup selection in the settings
Mail.SenddelegatedEmails to visitors on behalf of the terminal account
Group.Read.All, User.Read.AllApplication (managed identity)Check group memberships, resolve contact persons for Teams calls

Verify manually in the Entra admin center

You can review the delegated permissions under App registrations › Visitor Registration <prefix> › API permissions. The managed identity application roles are under Enterprise applications › <prefix>-identity › Permissions.

10

First sign-in and setup wizard

Open https://<name>.azurewebsites.net/admin and sign in with the account whose object ID you specified during deployment. As long as the solution has not been set up, the wizard starts.

Setup wizard with the first step, Basic Configuration
The wizard guides you through the initial setup in four steps.

1. Basic Configuration

Name and time zone of the first location. Optionally the admin group, which you can also set later.

2. Locations

Create further locations with terminal users and check-in behavior.

3. Branding

Company name, logo and colours of the terminal.

4. Timeouts

How long success messages stay on screen and when the terminal returns to the home screen.

With Complete Setup, the wizard saves your entries and opens the terminal. You can change all values later in the settings.

Do not forget the admin group

Under Settings › Security, enter an Entra group as the admin group and check that you are a member yourself. As soon as the group is set, the object IDs from the deployment no longer apply.

11

Next steps

  1. Set up locations: terminal users, guidelines and emails.
  2. Publish and roll out the Outlook add-in.
  3. Set up the terminal as a kiosk, in the browser or in Microsoft Teams.
  4. Test the first visit.
12

Updates and operations

  • Updating the application: Follow the release notes. You can deploy a new Marketplace version again with the same resource names; settings and data stay in Cosmos DB.
  • Changes to the infrastructure: Run the Marketplace deployment again with the same values, for example to change the pricing tier. Do not delete the resource group.
  • Checking the version: The installed version is shown in the footer of the settings and the analytics.
  • Backup: Cosmos DB backs up the data automatically at regular intervals. For longer retention, adjust the backup policy of the database account.
  • Monitoring: The App Service checks the application through /api/health. You find errors and logs in Application Insights.

After an update

If the Outlook add-in or the Teams app has changed, the release notes say so. In that case, publish the manifest again or upload the new Teams package with a higher version number.

13

Troubleshooting

After sign-in, a message says that you are signed in but not authorised for this area.

Your account is neither an administrator nor a terminal user. During the initial setup: check whether your object ID is in the app setting ADMIN_BOOTSTRAP_OBJECT_IDS of the App Service. After that: check your membership of the admin group.

The app registration or Graph picker does not work.

Check that prepare-app-registration ran in the correct tenant and that the Marketplace deployment used the same web app name and prefix. Run grant-graph-permissions afterwards with a Privileged Role Administrator or Global Administrator. The Cloud Shell help covers the most common CLI, tenant and permission errors.

The name of the web app is already taken.

Names under azurewebsites.net are globally unique. Choose a different value for webAppName.

The deployment fails at install-package.

In the resource group, open <prefix>-install-package › Logs. Do not change Marketplace artifact parameters and do not upload a ZIP manually. Start the deployment again with the same values or send us the error message.

Cosmos DB Serverless is unavailable in the region.

Read the nested error first. For regional capacity restrictions, follow Failure recovery: redeploy or change region. The template uses Serverless; Provisioned is not a simple switch in the wizard.

Visitors do not receive emails.

Check whether admin consent has been granted for Mail.Send, whether the terminal account has a mailbox and whether sending is enabled at the location. In the Teams desktop app, the client secret is also required.

The application does not start or responds with error 500.

Check /api/health first, then <prefix>-install-package › Logs and the App Service log stream. Send us the error before changing app settings or packages manually.

Questions about this product?

Our support team is happy to help with any questions about Smarter Visitor Registration.