Azure AD app registration for Pentestas Azure / M365 scanning

Pentestas scans your Microsoft 365 and Azure estate by impersonating a single multi-tenant application that you register once in your own home tenant. Every customer tenant grants that same application admin consent, which provisions a service principal in their directory. Pentestas then authenticates tenant-by-tenant using the same client ID but switching the token audience.

This guide walks through the exact registration, permissions, authentication, and customer onboarding steps. It assumes you are the operator running Pentestas as a service — if you are an end customer trying to grant access to someone else's Pentestas deployment, skip to § 7 Customer admin consent flow.

1. Architecture — one app, many tenants

┌────────────────────────────┐        ┌────────────────────────────┐
│  Pentestas home tenant     │        │  Customer tenant A         │
│  (you own this)            │        │                            │
│                            │        │  SP provisioned on         │
│   App registration         │───────▶│  admin consent             │
│   • Client ID (public)     │        │                            │
│   • Client secret OR cert  │        │  Your app shows up in:     │
│   • Multi-tenant = Yes     │        │  Enterprise applications   │
│                            │        │                            │
└────────────┬───────────────┘        └────────────────────────────┘
             │                         ┌────────────────────────────┐
             │                         │  Customer tenant B         │
             └────────────────────────▶│  Same SP ID, different     │
                                       │  tenant, separate consent  │
                                       └────────────────────────────┘

You register the app exactly once. You do NOT create one app per customer. Per-customer registration does not scale, forces you to maintain dozens of secret rotations, and gives customers no way to see (or revoke) their access from their Enterprise applications panel.

The app is public to the OAuth directory discovery endpoint but has no tokens in any tenant until that tenant's Global Admin explicitly grants consent. Revoking your access is a one-click "Remove" on the service principal in Entra ID → Enterprise applications.

2. Choose the authentication method up front

Pick one per environment. Pentestas supports all three simultaneously (one in the home tenant for graph + another for Exchange Online is common because Exchange insists on a certificate).

Generate a self-signed cert for Exchange Online:

# Run on any Windows or Linux host with pwsh 7
$cert = New-SelfSignedCertificate `
  -Subject "CN=pentestas-exchange-app-only" `
  -KeyAlgorithm RSA -KeyLength 2048 `
  -NotAfter (Get-Date).AddYears(2) `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable
Export-Certificate -Cert $cert -FilePath pentestas.cer         # public key → upload to Entra
Export-PfxCertificate -Cert $cert -FilePath pentestas.pfx `    # private key → keep in your secret store
  -Password (ConvertTo-SecureString -String "<strong-passphrase>" -Force -AsPlainText)

Store pentestas.pfx in your secret manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault — NOT in the repository, NOT in environment variables pasted into a .env file).

3. Register the application (Pentestas home tenant)

1. Sign in to the Azure portal as a Global Administrator of your home tenant (not a customer tenant).
2. Entra ID → App registrations → New registration.
3. Name → Pentestas Security Scanner. This is the name customers see on the consent dialog, so keep it honest and branded.
4. Supported account types → Accounts in any organizational directory (Any Microsoft Entra ID tenant — Multitenant).
5. Redirect URI → Web → https://app.pentestas.com/api/azure/consent-callback (adjust host to your deployment). This is the URL customers land on after granting consent.
6. Click Register. Copy the Application (client) ID and the Directory (tenant) ID — you will reference these in Pentestas settings.

4. Upload the certificate (or create a secret)

Certificate path (recommended)

1. In the registration blade, Certificates & secrets → Certificates → Upload certificate.
2. Upload pentestas.cer (public key only, never the .pfx).
3. Note the Thumbprint — Pentestas needs it for Connect-ExchangeOnline -CertificateThumbprint.

Client secret path

1. Certificates & secrets → Client secrets → New client secret.
2. Description: pentestas-primary. Expiry: 90 days (180 max).
3. Copy the Value immediately — it is only shown once. Store it in your secret manager alongside the certificate PFX.

Set a calendar alert 7 days before expiry. A silently-expired secret will take down every customer scan at once.

5. Grant API permissions

Pentestas uses four API surfaces. Add them in this order.

Inside the registration blade → API permissions → Add a permission.

5.1 Microsoft Graph (application permissions)

These unlock Entra ID, Security, Intune, Policy, and most of SharePoint via Graph:

5.2 Office 365 Exchange Online (application permissions)

Office 365 Exchange Online must be added explicitly — it's not under Graph:

In addition, the app principal must be assigned the Exchange Global Reader directory role (or Exchange Recipient Administrator for read-mostly). This is done under Roles and administrators, NOT API permissions. Without this role the app can authenticate but returns Access is denied on every cmdlet.

5.3 SharePoint (application permissions)

5.4 Azure Service Management (delegated)

Optional surfaces if the customer has E5 / specific licences — add only if you sell those scans:

6. Grant admin consent for your home tenant

After all permissions are added, click Grant admin consent for . This activates the permissions in YOUR tenant. Customers will do the equivalent step for their own tenant in the next section.

All permissions should turn green (status "Granted for "). If any stay yellow ("Not granted"), fix that before proceeding — the scanner will silently skip checks that the token doesn't cover.

7. Customer admin consent flow

Each customer tenant goes through this once. Pentestas ships a consent URL builder; the URL template is:

https://login.microsoftonline.com/{CUSTOMER_TENANT_ID_OR_DOMAIN}/adminconsent
  ?client_id={PENTESTAS_APP_ID}
  &redirect_uri={PENTESTAS_REDIRECT_URI}
  &state={PENTESTAS_NONCE}

Example:

https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent
  ?client_id=00000000-0000-0000-0000-000000000000
  &redirect_uri=https%3A%2F%2Fapp.pentestas.com%2Fapi%2Fazure%2Fconsent-callback
  &state=a3f7e2c1

The customer Global Admin:

1. Opens the URL.
2. Signs in if not already signed in.
3. Reviews the "Permissions requested" dialog — this lists every application permission from § 5. You are responsible for making this list honest. If you asked for Directory.ReadWrite.All when you only need Read, the customer sees that and will (rightly) refuse consent.
4. Clicks Accept.
5. Lands on {PENTESTAS_REDIRECT_URI} with ?admin_consent=True&tenant={tid}.

After consent, the app principal (service principal) exists in the customer's tenant. You can verify in:

Entra ID → Enterprise applications → filter by Application ID.

7.1 Exchange Online post-consent step (customer side)

Because Exchange.ManageAsApp needs a directory role, the customer admin must also run, once, in a PowerShell session connected to their tenant:

# Connect interactively first (customer admin)
Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory" -TenantId <customer-tenant>

$sp     = Get-MgServicePrincipal -Filter "appId eq '{PENTESTAS_APP_ID}'"
$roleId = (Get-MgRoleManagementDirectoryRoleDefinition `
            -Filter "displayName eq 'Global Reader'").Id

New-MgRoleManagementDirectoryRoleAssignment `
  -PrincipalId $sp.Id `
  -RoleDefinitionId $roleId `
  -DirectoryScopeId "/"

Pentestas ships this as a one-click assistant — the customer doesn't see raw cmdlets — but the script above is what it runs on their behalf via a delegated-flow prompt.

7.2 Teams post-consent step

A handful of Teams cmdlets (Get-CsTenantFederationConfiguration, Get-CsTeamsMeetingPolicy in some tenants) still reject app-only tokens. For these, Pentestas falls back to device-code OAuth with the customer's admin. That is one-time per scan; the admin pastes a code and approves. If the customer declines device-code, the Teams check set falls back to the CIS subset reachable via Graph Beta (reduced coverage).

8. Where Pentestas stores the credentials

Inside Pentestas:

Credentials are never returned by the Pentestas API after initial save. The UI shows a breadcrumb ••••••{last 4} and a "Rotate" button.

9. Verifying the setup end-to-end

From a workstation with pwsh 7 and the Microsoft modules (Az, ExchangeOnlineManagement, PnP.PowerShell, Microsoft.Graph, Microsoft.Graph.Beta, MicrosoftTeams) installed:

$ClientId      = "<your app id>"
$TenantId      = "<customer tenant id>"
$Thumbprint    = "<cert thumbprint>"
$Organization  = "<customer>.onmicrosoft.com"

# Graph — should return tenant displayName
Connect-MgGraph -ClientId $ClientId -TenantId $TenantId -CertificateThumbprint $Thumbprint
Get-MgOrganization | Select-Object DisplayName, VerifiedDomains
Disconnect-MgGraph

# Exchange Online — should return mailbox count
Connect-ExchangeOnline -AppId $ClientId -CertificateThumbprint $Thumbprint -Organization $Organization -ShowBanner:$false
(Get-Mailbox -ResultSize Unlimited).Count
Disconnect-ExchangeOnline -Confirm:$false

# SharePoint (PnP) — should return tenant URL and sharing mode
Connect-PnPOnline -Url "https://<customer>-admin.sharepoint.com" `
  -ClientId $ClientId -Tenant $TenantId -Thumbprint $Thumbprint
Get-PnPTenant | Select-Object SharingCapability, DefaultSharingLinkType
Disconnect-PnPOnline

# Teams — expected to prompt device-code unless fully app-only
Connect-MicrosoftTeams -ApplicationId $ClientId -TenantId $TenantId -CertificateThumbprint $Thumbprint
Get-CsTenantFederationConfiguration
Disconnect-MicrosoftTeams

All four should succeed. If any errors, jump to § 11 troubleshooting.

10. Customer offboarding (revoke access)

Two parallel paths exist. Either works — use whichever the customer prefers.

Customer-initiated revoke

Customer Global Admin → Entra ID → Enterprise applications → Pentestas Security Scanner → Properties → Delete.

All tokens are invalidated immediately. Pentestas scans against that tenant start returning AADSTS700016 (app not found in tenant) on the next run — Pentestas catches this and marks the tenant's integration as revoked.

Pentestas-initiated revoke

On the Pentestas UI, Settings → Azure integration → Disconnect tenant. This does NOT delete the SP in the customer tenant (Pentestas cannot — it's the customer's directory) but it:

1. Deletes the stored client secret / cert reference for that tenant.
2. Inserts a revocation log entry with actor + timestamp.
3. Stops scheduling scans against that tenant.

The customer is emailed with the cleanup step they can run on their side.

11. Troubleshooting

12. Reference — minimum permission set by module

If you need to propose a reduced-permission variant to a security-conscious customer (e.g. "we only want you to scan Entra ID, not Exchange"), this table lets you tell them exactly which permissions to decline.

Pentestas' scan config page reflects this — if a customer declines Exchange permissions, the Exchange checks show as Skipped: missing consent in the report rather than silently zero-finding.

Last updated: 2026-04-22. If you change the permission set above, update this doc and the consent-URL builder in backend/app/api/azure.py in the same PR. The doc is the contract with your customers.