Setup wizard walkthrough (browser)

EIDGuard ships only as the Azure Marketplace solution template, so setup happens entirely in the browser — there is no setup script to run and nothing to install on a workstation.

There are two distinct flows, and it is worth keeping them apart:

Before you start#

Deploy the deployment from the marketplace offer, then read the one-time setup key: it is a secret named setup-key-… in the deployment's Key Vault — the deployment's Outputs give the exact name as setupKeySecretName and the vault as keyVaultName (Key Vault → Secrets → that secret → current version → Show secret value, or az keyvault secret show --vault-name <keyVaultName> -n <setupKeySecretName> --query value -o tsv). The identity that ran the deployment was granted read access to that one secret; anyone else needs Key Vault Secrets User on it. The key is deliberately not a deployment output — outputs sit in plaintext in the deployment record. Then browse to the deployment's URL (the webAppHostname output).

You need:

• Workforce tenant (where the subscription lives): an administrator who can create app registrations and assign app roles — Cloud Application Administrator or higher.
• Each External ID tenant you want to protect: an administrator who can create app registrations and consent to application permissions tenant-wide. Because the restore app requests RoleManagement.ReadWrite.Directory, consenting in practice needs Privileged Role Administrator or Global Administrator; Cloud Application Administrator covers everything else.

The two can be different accounts — the wizard asks you to pick an account at each tenant sign-in.

Part 1 — Setup wizard (once per deployment)#

Until this completes, the deployment has no sign-in configured and the site serves only the wizard.

1. Setup key. Paste the setup-key secret value from Key Vault and choose Begin setup. The key is the only thing guarding this flow, so treat it as a credential.
2. Sign in. The wizard shows a device code. Open microsoft.com/devicelogin, enter the code, and sign in with your workforce tenant administrator account.
3. Finishing. The wizard waits while the deployment restarts with authentication enabled. This takes a couple of minutes and completes on its own.

What it creates, acting as the administrator who just signed in (the deployment's own identity holds no Graph permissions):

• An app registration EIDGuard-WebUI (<site name>) in the workforce tenant, with the three app roles Viewer, Operator and Admin, and its service principal set to require role assignment — so nobody reaches the dashboard without being assigned a role.
• You are assigned Admin automatically. Everyone else is assigned in the Entra portal; the dashboard's Users page is deliberately read-only.
• The EIDGuard licensing application's service principal in the workforce tenant, on a licensed deployment — that is what lets the deployment obtain a token for the licensing service. One that already exists (an administrator approved the application by hand, or another EIDGuard deployment in the same tenant created it) is reused. If this step fails, setup still completes and the dashboard banner offers the approval link.
• Easy Auth is switched to bearer mode on the site.

The setup key is then deleted from the deployment's settings, permanently. The setup endpoints return 403 from that point on, so this part cannot be replayed. The Key Vault secret is disabled on the next deployment, and a version upgrade never re-issues a key: the upgrade reads back that setup is complete and emits nothing setup-pending.

Once the page reloads you sign in normally and land on Tenants, because no tenant is protected yet.

Part 2 — Tenant onboarding (per External ID tenant)#

Dashboard → Tenants → Onboard a tenant. Enter the tenant's domain (contoso.onmicrosoft.com) or GUID and choose Onboard. Requires the Admin role.

The wizard runs seven steps and shows each as it goes:

1. Load the permission manifest — the exact Graph permission names for both apps, served by the deployment.
2. Sign in to <tenant> and consent to Graph access — you are redirected to that tenant's sign-in. Pick the admin account for the tenant being onboarded.
3. Create the backup app (read-only) and restore app (read-write) — EIDGuard-Backup-ReadOnly and EIDGuard-Restore-ReadWrite. Two apps, so a backup run physically cannot write; see permissions.md.
4. Grant their Microsoft Graph application permissions — this is the admin consent step. There is no separate "Grant admin consent" click in the portal afterwards.
5. Issue certificates inside Key Vault — one self-signed RSA-2048 certificate per app, valid 24 months, created inside the deployment's Key Vault. Only the public certificate ever leaves the vault; the private keys cannot be exported by the web tier at all.
6. Attach the public certificates to the apps — as app credentials.
7. Commit the tenant and start a validation backup — the tenant is saved and a backup runs immediately so you can see it work. The link takes you to the job.

Things the wizard may stop and ask about#

• Existing app found — check its credentials. An app with the same display name already exists in the tenant. The wizard will adopt it rather than create a duplicate, but only after you tick every listed concern. Adoption removes all existing owners from the app and from its enterprise application before granting anything, then reads both again just before the first grant and stops if anything you were not shown has appeared. Refused outright: an app that is not single-tenant, one with a federated credential, one whose enterprise application holds a certificate or secret, and two apps sharing the name.
• Onboarding rolled back. The server refused the run at its final step — two people onboarded into the last plan slot at once and this run lost the race, or licensing or the plan count could not be confirmed. The card names which. Objects this run created are deleted and role grants it made are revoked; anything that could not be undone is itemised so you can finish by hand.

Re-running it#

Onboarding the same tenant again is an upsert: it adopts the existing apps, re-enables disabled certificates, and refreshes the stored configuration. It is never blocked by the plan limit, even if you are over the limit after a plan downgrade.

Plan limits#

The plan you bought sets how many tenants you may protect. The count and limit are shown under Configuration → Plan, and the Onboard button is disabled once you reach it. The limit is enforced on the server at the commit step, so it cannot be bypassed from the browser.

Change plans on your EIDGuard SaaS subscription in the Azure portal (Marketplace → your subscription → change plan). The deployment picks the new plan up on its next check-in with the licensing service — within six hours, usually sooner. Do not redeploy the solution template to change plan: a version upgrade re-deploys the same plan, and deploying under a different resource name prefix creates a second, separately billed deployment instead of updating yours. Details, including what a downgrade does and does not do, in plans-and-limits.md.

Optional, any time after setup#

None of these are part of onboarding; each is a page in the dashboard.

• Configuration — email alerting, scheduled verification, retention window, branding, your plan, and exporting snapshots to a storage account you own — each an administrative domain on that page.
• Configuration → Networking — private endpoints and a hybrid worker. See private-endpoints.md.

Removing a tenant#

Tenants → the tenant's row → Offboard…. It deletes both app registrations, disables (never deletes) the certificates, and removes the tenant from the backup schedule. Snapshots already taken are kept and stay listed and browsable under Recovery points (the tenant shows as offboarded) until they age out under the longest retention window still configured — not the tenant's own — or never, while any window keeps snapshots forever (see multi-tenant.md). Restoring or comparing from them needs the tenant onboarded again — offboarding deleted the applications those operations sign in as.