Onboarding Your Tenant

Before anyone in your organization can sign in to InfraScout, an Entra administrator enables the InfraScout SaaS application in your tenant and assigns the first user roles. This page walks you through the one-time setup, with both Azure portal and command-line paths.

The whole flow takes about ten minutes. After you finish, your assigned users can sign in to the InfraScout portal and start installing agents and running assessments.

What You Need

Have these on hand before you start:

• Global Administrator, or Privileged Role Administrator plus Cloud Application Administrator, in your Entra tenant.
• Your Entra tenant ID (Entra admin center → Overview).
• The InfraScout Application ID — provided by InfraScout in your onboarding email.
• One or more user accounts to assign as InfraScout administrators.
• (Optional, for command-line steps) Azure CLI 2.60 or newer.

INFO

Send your tenant ID to InfraScout before you start. InfraScout adds your tenant to the access list as part of accepting the request — without that step, sign-in succeeds against Entra but the InfraScout portal returns a "tenant not onboarded" error.

What Happens During Onboarding

Three actions, all inside your tenant:

1. Grant admin consent for the InfraScout app — this creates the InfraScout service principal in your directory.
2. Set appRoleAssignmentRequired on that service principal — without this, every signed-in user in your tenant becomes an InfraScout user automatically.
3. Assign your initial users to the Admin role so they can sign in to the InfraScout portal.

You can do all three from the Azure portal or from the script provided below.

Quick Path — One Script

If you have Azure CLI and want to finish onboarding in a single block, paste this into a Bash shell after replacing the four placeholder values. The script is idempotent — safe to re-run if a step fails partway through.

# ───── Replace these four values ─────
TENANT_ID="<your-tenant-id>"
INFRASCOUT_APP_ID="<infrascout-app-id-from-your-onboarding-email>"
INFRASCOUT_ADMIN_ROLE_ID="<admin-role-id-from-your-onboarding-email>"
ADMIN_USER_UPN="alice@contoso.com"   # first InfraScout admin
# ─────────────────────────────────────

az login --tenant "$TENANT_ID"

# 1) Create the InfraScout service principal in your tenant (idempotent)
az ad sp create --id "$INFRASCOUT_APP_ID" 2>/dev/null || true
SP_ID=$(az ad sp show --id "$INFRASCOUT_APP_ID" --query id -o tsv)

# 2) Require explicit role assignment for sign-in
az rest --method PATCH \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$SP_ID" \
  --headers "Content-Type=application/json" \
  --body '{"appRoleAssignmentRequired": true}'

# 3) Assign the first admin
USER_OID=$(az ad user show --id "$ADMIN_USER_UPN" --query id -o tsv)
az rest --method POST \
  --uri "https://graph.microsoft.com/v1.0/users/$USER_OID/appRoleAssignments" \
  --headers "Content-Type=application/json" \
  --body "{
    \"principalId\": \"$USER_OID\",
    \"resourceId\": \"$SP_ID\",
    \"appRoleId\": \"$INFRASCOUT_ADMIN_ROLE_ID\"
  }"

echo "Done. $ADMIN_USER_UPN can now sign in to the InfraScout portal."

Skip ahead to Verify the Sign-In once the script finishes.

Step-by-Step in the Azure Portal

If you prefer click-through, follow these steps in the Microsoft Entra admin center.

Step 1 — Grant Admin Consent

Open this URL in a browser, replacing <your-tenant-id> and <infrascout-app-id> with your values:

https://login.microsoftonline.com/<your-tenant-id>/adminconsent?client_id=<infrascout-app-id>

Sign in as a Global Administrator and approve the consent prompt. The page redirects to a confirmation; you can close it once consent succeeds.

This creates an enterprise application named InfraScout in your tenant. It has no permissions in your directory beyond letting your users sign in to the InfraScout portal.

Step 2 — Require Role Assignment

In the Entra admin center, go to Enterprise applications and open InfraScout.

Under Properties, set Assignment required? to Yes and click Save.

WARNING

This switch is the security boundary that prevents every user in your tenant from automatically gaining access to InfraScout. Leave it on Yes.

Step 3 — Assign Your First Admin

Still in the InfraScout enterprise application, go to Users and groups → Add user/group.

1. Pick the user you want to make an InfraScout administrator.
2. Choose the Admin role from the role picker.
3. Click Assign.

Repeat for any additional users you want to onboard now. You can come back later to add more.

Verify the Sign-In

Have your first admin open https://portal.infrascout.cloud (or the URL InfraScout provided in your onboarding email) and sign in with their work account.

A successful sign-in lands on the InfraScout dashboard. If you see one of the errors below, jump to Troubleshooting.

Symptom	Likely cause
tenant_not_onboarded	InfraScout has not added your tenant to the access list yet — contact InfraScout support.
AADSTS50105 (not assigned to an app role)	The user is missing a role assignment. Repeat Step 3 for that user.
Consent prompt appears for an end user	appRoleAssignmentRequired is not set, or admin consent never completed in Step 1.

InfraScout App Roles

InfraScout defines five app roles, all assigned in Entra ID. Assign each user the smallest role that lets them do their job.

Role	Who it's for	What it grants
Users	Read-only stakeholders	View the dashboard, agents, and Insights
MCPUser	Read-only stakeholders connecting an MCP client (such as Claude Desktop)	Everything in Users, plus connecting to the InfraScout MCP server
Operator	Day-to-day assessors	Everything in Users, plus running sessions, executing playbooks, and updating Insights
MCPOperator	Assessors connecting an MCP client	Everything in Operator, plus connecting to the InfraScout MCP server
Admin	InfraScout administrators	Everything above, plus user management, connectors, and policies

MCP access is built into the role rather than a second assignment. Users who run assessments through an MCP client need only MCPOperator (read-only stakeholders need only MCPUser); the matching MCP role already includes its web-portal tier, so a single role grants both. Users who only use the web portal need Users or Operator.

Bulk-Assigning Roles

To assign a role to multiple users at once, loop over the user list. Replace the role ID with the value for the role you want to grant — InfraScout sends all five role IDs in your onboarding email.

TENANT_ID="<your-tenant-id>"
INFRASCOUT_APP_ID="<infrascout-app-id>"
ROLE_ID="<role-id-for-the-role-you-want-to-grant>"
USERS=(
  "alice@contoso.com"
  "bob@contoso.com"
  "carol@contoso.com"
)

az login --tenant "$TENANT_ID"
SP_ID=$(az ad sp show --id "$INFRASCOUT_APP_ID" --query id -o tsv)

for UPN in "${USERS[@]}"; do
  USER_OID=$(az ad user show --id "$UPN" --query id -o tsv)
  az rest --method POST \
    --uri "https://graph.microsoft.com/v1.0/users/$USER_OID/appRoleAssignments" \
    --headers "Content-Type=application/json" \
    --body "{
      \"principalId\": \"$USER_OID\",
      \"resourceId\": \"$SP_ID\",
      \"appRoleId\": \"$ROLE_ID\"
    }"
  echo "Assigned $UPN"
done

A 409 Conflict response on a single user means that role is already assigned — it's safe to ignore.

Removing a Role

To remove a role assignment from a user (for example, when an employee changes teams), find the assignment ID and delete it:

USER_OID=$(az ad user show --id "alice@contoso.com" --query id -o tsv)
SP_ID=$(az ad sp show --id "$INFRASCOUT_APP_ID" --query id -o tsv)

# List the user's InfraScout role assignments
az rest --method GET \
  --uri "https://graph.microsoft.com/v1.0/users/$USER_OID/appRoleAssignments" \
  --query "value[?resourceId=='$SP_ID'].{id:id, role:appRoleId}" -o table

# Delete the one you want to remove
ASSIGNMENT_ID="<id-from-the-table-above>"
az rest --method DELETE \
  --uri "https://graph.microsoft.com/v1.0/users/$USER_OID/appRoleAssignments/$ASSIGNMENT_ID"

Optional — Set Up Identity Sync

If you want InfraScout to display directory information (users, groups, group membership) alongside assessment results, create a separate, single-tenant Identity Sync app in your directory and share its credentials with InfraScout. This is optional — you can run agent-based assessments without it.

InfraScout uses these credentials as your identity connection — the default tenant connection it auto-resolves for cloud lookups and the one that runs directory synchronization on a schedule. For a single tenant, this identity connection is all you need; multi-tenant and GDAP setups can add further connections later.

The sync is read-only. InfraScout never writes to your directory.

Permissions Required

The Identity Sync app needs three Microsoft Graph application permissions, all admin-consented:

Permission	What it enables
User.Read.All	Read user profiles
Group.Read.All	Read groups and their properties
GroupMember.Read.All	Read group membership

Create the App with One Script

This script creates the app, adds and consents the three permissions, and prints a fresh client secret. Run it as a Global Administrator in your tenant.

TENANT_ID="<your-tenant-id>"
APP_NAME="InfraScout Identity Sync"

az login --tenant "$TENANT_ID"

# 1) Create the single-tenant app
APP_ID=$(az ad app create \
  --display-name "$APP_NAME" \
  --sign-in-audience AzureADMyOrg \
  --query appId -o tsv)
echo "Created app: $APP_ID"

# 2) Resolve the three Graph permission IDs
GRAPH_API_ID="00000003-0000-0000-c000-000000000000"
USERS_READ_ALL=$(az ad sp show --id "$GRAPH_API_ID" \
  --query "appRoles[?value=='User.Read.All'].id | [0]" -o tsv)
GROUPS_READ_ALL=$(az ad sp show --id "$GRAPH_API_ID" \
  --query "appRoles[?value=='Group.Read.All'].id | [0]" -o tsv)
GROUPMEMBER_READ_ALL=$(az ad sp show --id "$GRAPH_API_ID" \
  --query "appRoles[?value=='GroupMember.Read.All'].id | [0]" -o tsv)

# 3) Attach the permissions
az ad app permission add --id "$APP_ID" \
  --api "$GRAPH_API_ID" \
  --api-permissions "$USERS_READ_ALL=Role" \
                    "$GROUPS_READ_ALL=Role" \
                    "$GROUPMEMBER_READ_ALL=Role"

# 4) Create the service principal and grant admin consent
az ad sp create --id "$APP_ID" 2>/dev/null || true
SYNC_SP_ID=$(az ad sp show --id "$APP_ID" --query id -o tsv)
GRAPH_SP_ID=$(az ad sp show --id "$GRAPH_API_ID" --query id -o tsv)

for ROLE in "$USERS_READ_ALL" "$GROUPS_READ_ALL" "$GROUPMEMBER_READ_ALL"; do
  az rest --method POST \
    --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$SYNC_SP_ID/appRoleAssignments" \
    --headers "Content-Type=application/json" \
    --body "{
      \"principalId\": \"$SYNC_SP_ID\",
      \"resourceId\": \"$GRAPH_SP_ID\",
      \"appRoleId\": \"$ROLE\"
    }" 2>/dev/null || true
done

# 5) Generate a client secret (valid for 2 years)
SECRET=$(az ad app credential reset \
  --id "$APP_ID" \
  --display-name "InfraScout Identity Sync — created $(date -u +%Y-%m-%d)" \
  --years 2 \
  --query password -o tsv)

echo
echo "── Send these to InfraScout ──"
echo "Tenant ID:     $TENANT_ID"
echo "Client ID:     $APP_ID"
echo "Client Secret: $SECRET"
echo "─────────────────────────────"

DANGER

The client secret is shown once. Capture the three values printed at the end of the script, share them with InfraScout through a secure channel (a password manager share or 1Password vault link), then close the terminal. If you lose the secret, re-run az ad app credential reset to generate a new one.

Manual Setup in the Portal

If you prefer the Entra admin center, the equivalent click-through is:

1. App registrations → New registration. Name it InfraScout Identity Sync, choose Single tenant, leave the redirect URI blank, and click Register.
2. API permissions → Add a permission → Microsoft Graph → Application permissions. Select User.Read.All, Group.Read.All, and GroupMember.Read.All. Click Add permissions.
3. Click Grant admin consent for (your tenant).
4. Certificates & secrets → New client secret. Give it a name and an expiry, copy the Value field immediately.
5. Send your tenant ID, the new app's Application (client) ID, and the secret to InfraScout.

Once InfraScout receives the credentials and configures the connection, the first sync usually completes within minutes, and your directory data appears under Settings → Identity in the InfraScout portal.

Troubleshooting

"User account is not assigned to a role for the application" (AADSTS50105). The user is missing an app role assignment. Open the InfraScout enterprise application, go to Users and groups, and assign at least the Users role.

"Need admin approval" prompt for end users. Either admin consent never completed in Step 1, or appRoleAssignmentRequired was left off — both cause Entra to fall back to a per-user consent prompt. Re-run Steps 1 and 2.

"tenant_not_onboarded" error after sign-in. Sign-in succeeded against Entra, but InfraScout has not yet added your tenant to the access list. Confirm with InfraScout that they have your tenant ID on file.

Identity Sync shows last_sync_error after the first run. The most common causes are a typo in the tenant ID, an expired or mistyped client secret, or one of the three Graph permissions missing admin consent. Re-run the Identity Sync script — it is idempotent and will surface a clearer error if a prerequisite is missing.

Optional — Microsoft Cloud Data Collection

If you want InfraScout to assess your Microsoft Cloud surface (Entra ID, Azure, Microsoft 365, Defender), you also need a data-collection app in your tenant — a separate, single-tenant app registration with read-only permissions across Microsoft Graph and the Defender APIs.

InfraScout publishes a PowerShell script that creates the app, attaches all 41 required permissions, grants admin consent, and generates a client secret in one run. Follow Connecting Entra ID for the script, the full permission list, and how to deliver the credentials to InfraScout.

INFO

The published script is digitally signed with a publicly-trusted, Microsoft-issued certificate through Azure Trusted Signing. Because it carries a valid Authenticode signature, it runs cleanly under PowerShell execution policies without unknown-publisher warnings, and you can confirm the InfraScout publisher identity with Get-AuthenticodeSignature before you run it. See Signing the Onboarding Script for details.

This step is independent of sign-in onboarding above — you can do it now or any time later, and it does not change how your users authenticate to the portal.

What's Next

With your tenant onboarded and admins assigned, follow the Quick Start to install your first agent, connect your AI client, and run your first assessment.