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.
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.
| Check | Action |
|---|---|
| Subscription and billing | Use 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 quota | Search 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 upgrade | Use 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 names | Do 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 permissions | Azure 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.
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
doneOnly 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.
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
doneCheck 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.
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 / when | Changes and purpose |
|---|---|
| prepare-app-registration — before deployment | Creates or updates Visitor Registration |
| grant-graph-permissions — after deployment | Reads |
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.
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.
| Error | Next action |
|---|---|
| Provider not registered | Register the required provider named in the error, especially Microsoft.OperationalInsights for monitoring. Then retry with unchanged deployment values. |
| B1 VMs: 0 / SubscriptionIsOverQuotaForSku | Resolve 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 request | This 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-deployment | Check 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 state | Do 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.
- 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.
- Check quota and providers first. Run the preparation script with the new names and use its client ID. Then start a new Marketplace deployment.
- 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.
- 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.
Prerequisites
| Area | Requirement |
|---|---|
| Azure | Owner 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 ID | Application Administrator to create the app registration, plus Privileged Role Administrator or Global Administrator for Graph application roles and admin consent. |
| Workstation | Recommended: Azure Cloud Shell with Bash. Alternatively, use Azure CLI and the Bash or PowerShell scripts locally. |
| Microsoft 365 | Exchange Online for the Outlook add-in and for sending emails, optionally Microsoft Teams. |
| Object ID of the first administrator | The 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 secret | A random string of at least 32 characters, for example from openssl rand -hex 32. |
| Azure region | A 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.
What is created in Azure
| Resource | Purpose |
|---|---|
| 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 identity | Reads group memberships and users through Microsoft Graph (application roles Group.Read.All and User.Read.All). No client secret is required. |
| App registration | Sign-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.
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.
az login --tenant <tenant-id>
az account set --subscription <subscription-id>
az account show --query "{subscription:name, tenant:tenantId, user:user.name}" -o table# 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.
Deploy from Azure Marketplace
Open Smarter Visitor Registration – Standard in the Azure portal and select Create. We recommend a new, empty resource group.

| Wizard step | Value or recommendation |
|---|---|
| Basics | Target subscription, a new resource group and Azure region. “Germany West Central” has worked reliably for tests. |
| Deployment prefix | 3 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 name | Globally unique name. It becomes part of https://<name>.azurewebsites.net and must exactly match the value used by the preparation script. |
| Azure configuration | Keep App Service “Basic B1”, Cosmos DB “Serverless”, Application Insights and Key Vault enabled. |
| Initial administrator | Object ID of the person who opens the setup wizard afterwards. |
| Entra application | Client ID printed by prepare-app-registration. |
| Session secret | Enter the random value of at least 32 characters twice. |


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.
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/healthExpected 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.
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
./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.
| Permission | Type | Purpose |
|---|---|---|
User.Read, User.ReadBasic.All, People.Read | delegated | Sign-in and people search |
Group.Read.All | delegated | Group selection in the settings |
Mail.Send | delegated | Emails to visitors on behalf of the terminal account |
Group.Read.All, User.Read.All | Application (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.
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.

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.
Next steps
- Set up locations: terminal users, guidelines and emails.
- Publish and roll out the Outlook add-in.
- Set up the terminal as a kiosk, in the browser or in Microsoft Teams.
- Test the first visit.
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.
Troubleshooting
After sign-in, a message says that you are signed in but not authorised for this area.
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.
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.
azurewebsites.net are globally unique. Choose a different value for webAppName.The deployment fails at install-package.
<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.
Visitors do not receive emails.
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.
/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.