Add approval-gated application creation to guided setup

.github/workflows/ci.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Test application and region selection without Azure access
         shell: pwsh
         run: ./setup/tests/Selections.Tests.ps1
+      - name: Test new application creation without Azure access
+        shell: pwsh
+        run: ./setup/tests/Applications.Tests.ps1
       - name: Test deployment progress without Azure access
         shell: pwsh
         run: ./setup/tests/Progress.Tests.ps1

README.md

@@ -26,8 +26,8 @@ Guided setup deploys **one regional endpoint** using JavaScript by default, with
 
 ## Requirements
 
-- Use a separate test environment with a Microsoft Entra ID tenant, Azure subscription, app
-  registration, and unique resource name prefix.
+- Use a separate test environment with a Microsoft Entra ID tenant, Azure subscription, and
+  unique resource name prefix. Supply a dedicated app registration or create one during guided setup.
 - Check [roles, permissions, tools, regional availability, and quota](setup/docs/README.md#prerequisites-for-step-2).
 - Plan for Azure, telemetry, and provider charges. The [cost estimate](docs/COST-CALCULATOR.md) is not a bill.
 - Use Easy Auth to allow only the approved Microsoft caller.
@@ -49,7 +49,7 @@ See [architecture details](TECHNICAL.md#single-region-architecture).
 Follow the **[five-step setup guide](docs/GETTING-STARTED.md)** in order:
 
 1. <a id="1-get-ready"></a>[Get ready](docs/GETTING-STARTED.md#1-get-ready): confirm access, approvals, permissions, and budget.
-2. <a id="2-register-your-application"></a>[Register the app](docs/GETTING-STARTED.md#2-register-your-application): save the tenant and client IDs.
+2. <a id="2-register-your-application"></a>[Choose the app](docs/GETTING-STARTED.md#2-register-your-application): use an existing registration or create one during setup.
 3. <a id="3-run-guided-setup"></a>[Deploy](docs/GETTING-STARTED.md#3-run-guided-setup): choose the provider and hosting plan.
 4. <a id="4-connect-your-provider-and-test"></a>[Connect and test](docs/GETTING-STARTED.md#4-connect-your-provider-and-test): configure provider access and run approved checks.
 5. <a id="5-activate-and-hand-over"></a>[Activate and hand over](docs/GETTING-STARTED.md#5-activate-and-hand-over): activate after validation and assign owners.

docs/GETTING-STARTED.md

@@ -9,7 +9,7 @@ Deploy one regional endpoint for Microsoft Entra ID SMS and voice requests.
 | Step | Task |
 | --- | --- |
 | 1 | [Prepare access, tools, region, and budget](#1-get-ready) |
-| 2 | [Register the endpoint application](#2-register-your-application) |
+| 2 | [Choose the endpoint application](#2-register-your-application) |
 | 3 | [Run guided setup](#3-run-guided-setup) |
 | 4 | [Connect the provider and test](#4-connect-your-provider-and-test) |
 | 5 | [Activate and hand over](#5-activate-and-hand-over) |
@@ -51,7 +51,17 @@ Assign an **onboarding owner** and review [production readiness](../TECHNICAL.md
 
 ## 2. Register your application
 
-In the customer tenant's **Microsoft Entra admin center > App registrations > New registration**:
+You can create the dedicated application during guided setup or register it manually.
+
+**Create during setup:** in Step 3, choose **Create a new application**, enter its display name,
+and choose a provider by name from the alphabetized list (**Soprano, Telesign**).
+Setup creates the registration only after you approve the final deployment plan.
+Canceling before approval creates no application. The signed-in user must be allowed to register
+applications in the customer tenant.
+
+**Register manually or use an existing dedicated app:** keep its tenant and application client
+IDs handy. To register manually, open the customer tenant's
+**Microsoft Entra admin center > App registrations > New registration**:
 
 1. Give the application a recognizable name.
 2. Select **Accounts in this organizational directory only**. Leave the redirect URI blank,
@@ -79,7 +89,8 @@ See [application registration details](../setup/docs/README.md#step-1---manually
 
 Keep the Azure subscription ID handy. The [setup values worksheet](ONBOARDING.md#inputs-you-supply-to-setup)
 lists every input. Use a new app and prefix for an independent endpoint. After the app exists,
-complete provider onboarding steps that require its application client ID.
+complete provider onboarding steps that require its application client ID; for setup-created
+applications, that ID becomes available after deployment approval.
 
 ## 3. Run guided setup
 
@@ -102,15 +113,17 @@ On a shared workstation, use `.\Setup-Epp.ps1 -ForceAuthentication` for a fresh
 JavaScript is used by default, without a language prompt. To deploy another language, run
 `.\Setup-Epp.ps1 -Language csharp` or `.\Setup-Epp.ps1 -Language python`.
 
-Select the tenant, subscription, and existing application **client ID**. Setup detects the tenant's
+Select the tenant and subscription, then select an existing application, enter its **client ID**,
+or choose **Create a new application** and enter its display name. Setup detects the tenant's
 replication scope and selects the corresponding provider route; it does not ask you to choose EU or
 Global. Select the Azure region, then complete the remaining settings:
 
 - **Azure region:** EU tenants receive recommendations within the EU Data Boundary (EU/EFTA).
   Other tenants retain the existing Azure-recommended shortlist. All-region and manual selection,
   including `-Location`, remain available; EU tenants receive a warning for an out-of-boundary or
   unverifiable choice. Recommendations are not a data-residency or GDPR compliance guarantee.
-- **Provider:** enter or confirm the provider by name. Setup downloads the language's matching
+- **Provider:** enter or confirm the provider by name. New applications show all guided providers
+  in alphabetical order, with no default selection. Setup downloads the language's matching
   stable release asset, verifies `SHA256SUMS.txt`, and builds when required.
 - **Hosting:** FC1 can scale to zero and cold-start. EP1 has paid warm capacity. Review
   [plan details](../setup/docs/README.md#service-plan-selection) and the [cost estimate](COST-CALCULATOR.md).
@@ -128,6 +141,13 @@ runtime, plan, resource names, permissions, certificate key IDs, and vault acces
 The plan includes Microsoft Graph `Application.Read.All` for the Microsoft phone-provider service
 principal. `No`, `N`, or Enter cancels. Responses are case-insensitive.
 
+For a new application, the plan shows its display name and resource-name patterns containing
+`<app-id-hash>`. After approval, setup creates the registration, uses its real client ID to
+calculate the final names, and checks resource ownership before Azure deployment. It prints the
+new client ID and saves `application-<client-id>.json` in `epp-output` for recovery. If deployment
+then fails, reuse that client ID with `-ApplicationId` and the same prefix; do not create another app.
+The registration record is not a successful deployment summary.
+
 **Plan review:** run interactively and choose **No** at the final prompt. See
 [plan review](../setup/docs/README.md#reviewing-the-plan-without-deploying).
 

docs/ONBOARDING.md

@@ -46,7 +46,7 @@ renewal.
 | --- | --- | --- |
 | Customer tenant ID | Microsoft Entra admin center > Overview | `-TenantId` |
 | Azure subscription ID | Azure portal > Subscriptions | `-SubscriptionId` |
-| Endpoint application client ID | Microsoft Entra admin center > App registrations > application > Overview | `-ApplicationId` |
+| Endpoint application | Existing dedicated app's client ID from Microsoft Entra admin center, or a new display name | `-ApplicationId`, or choose **Create a new application** interactively |
 | Azure region | Available Linux FC1/EP1 region that meets quota and organization requirements | `-Location` |
 | Provider | Approved Security Store integration | `-Provider telesign` or `soprano` |
 | Provider route | Detected from the tenant's replication scope; EU for EU tenants, Global otherwise | Optional `-EndpointRegion eu` or `global` must match the detected route |
@@ -60,6 +60,11 @@ are different values. Global or EU identifies provider routing, not Azure locati
 EU tenants receive an EU Data Boundary region shortlist; other tenants retain the existing
 recommendations. Explicit region overrides remain available with a warning for EU tenants.
 
+New registrations are created only after final deployment approval. Choose their provider from
+the alphabetized guided-provider list. Unattended runs still require an existing `-ApplicationId`.
+If setup creates an app and deployment later fails, use the client ID saved in
+`application-<client-id>.json` and the original prefix for a rerun, rather than creating another app.
+
 One guided deployment uses one provider and supports both SMS and voice. Each request selects its
 channel. Reusing the same subscription, application, and prefix reconfigures that deployment.
 

setup/Setup-Epp.ps1

@@ -6,10 +6,15 @@
     Download only this file. Supporting PowerShell, Bicep, and provider JSON files come from
     the selected public GitHub repository (Azure-Samples by default).
     Microsoft Graph operations reuse the Azure CLI user session through az ad and az rest.
-    Interactive setup can select cached tenants, subscriptions, applications, and Azure regions.
+    Interactive setup can select cached tenants, subscriptions, applications, and Azure regions,
+    or create a dedicated app registration after final deployment approval.
     The endpoint supports SMS and voice, selected by each request.
-    Application registration and policy activation are manual steps.
-    No Azure resources are changed until you approve the complete plan.
+    Policy activation remains manual.
+    No Azure resources or app registrations are changed until you approve the complete plan.
+.PARAMETER ApplicationId
+    Existing application client ID. Omit interactively to select, enter, or plan a new application.
+    New applications use an alphabetized provider list and are created only after deployment approval.
+    Required for unattended setup.
 .PARAMETER SourceRepository
     Public GitHub owner/repository containing the setup files. Use with SourceRef to test a fork.
 .PARAMETER PackageReleaseTag