> ## Documentation Index
> Fetch the complete documentation index at: https://help.nops.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Security architecture, API usage, RBAC requirements, and resource footprint for the nOps Azure integration.

# Microsoft Azure - Security

## Security & API Access Overview

Prepared for customer security assessment.

## Integration Summary

| Auth Model                       | Write Access to Resources    | Supported Agreements | Data Scope                         |
| -------------------------------- | ---------------------------- | -------------------- | ---------------------------------- |
| Multi-tenant App (Admin Consent) | None (Savings Analysis tier) | EA and MCA (No CSP)  | Cost, commitments, recommendations |

## 1. Purpose of This Document

This document is provided to support your organisation's security assessment of the nOps
Azure integration. It enumerates every Azure API call nOps makes, the exact RBAC
permissions required, the resources created in your environment, and what nOps explicitly does
not access.

nOps offers two integration tiers:

* Savings Analysis: Read-only cost visibility, commitment inventory, and optimisation
  recommendations.
* Commitment Management: Automated purchasing and lifecycle management of Azure
  Reservations and Savings Plans. This tier builds on Savings Analysis and requires
  additional write-level roles scoped to commitment purchasing only.

<Info>
  **Supported Agreement Types**

  nOps supports Enterprise Agreement (EA) and Microsoft Customer Agreement (MCA) only. Cloud
  Solution Provider (CSP) subscriptions are not supported.
</Info>

## 2. Authentication Model

nOps registers a multi-tenant Azure AD application. During onboarding a Global Administrator
grants admin consent via Microsoft's standard OAuth 2.0 flow. This creates a service principal in
your tenant, an identity managed entirely by Azure AD. nOps never stores your credentials; it
authenticates using its own app registration against the service principal that lives in your
tenant.

| Item            | Detail                                                           |
| --------------- | ---------------------------------------------------------------- |
| Credential Type | Multi-tenant App Registration                                    |
| Token Endpoint  | `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` |
| OAuth Scope     | `https://management.azure.com/.default`                          |
| Token Lifetime  | 1 hour (auto-refreshed)                                          |
| Revocation      | Remove Service Principal or Lighthouse delegation                |

## 3. Azure APIs Called

The following tables document every API endpoint nOps calls, grouped by service area. All calls
use the base URL [https://management.azure.com](https://management.azure.com).

### 3.1 Subscriptions & Resource Discovery

Baseline calls to enumerate accessible subscriptions and retrieve cost optimization
recommendations.

| # | Method | Endpoint                                                                                     | API Version | Purpose                                                                                        | Tier |
| - | ------ | -------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- | ---- |
| 1 | GET    | `/subscriptions`                                                                             | 2022-12-01  | List subscriptions the service principal can access                                            | SA   |
| 2 | GET    | `/subscriptions/{id}/providers/Microsoft.Advisor/recommendations?$filter=Category eq 'Cost'` | 2023-01-01  | Cost recommendations only — no security, reliability, or performance recommendations retrieved | SA   |

### 3.2 Cost Management

Used to query cost data and manage FOCUS exports. The PUT export call (#6) runs once
during customer setup. The POST run call (#7) is customer-initiated for backfill only.

| # | Method | Endpoint                                                            | API Version        | Purpose                                                                | Tier          |
| - | ------ | ------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------- | ------------- |
| 3 | POST   | `/subscriptions/{id}/providers/Microsoft.CostManagement/query`      | 2023-03-01         | Query actual cost data (monthly aggregation)                           | SA            |
| 4 | GET    | `/{billingScope}/providers/Microsoft.CostManagement/exports`        | 2023-07-01-preview | List FOCUS exports at a billing scope                                  | SA            |
| 5 | GET    | `/{billingScope}/providers/Microsoft.CostManagement/exports/{name}` | 2023-07-01-preview | Verify the FOCUS export exists and is active                           | SA            |
| 6 | PUT    | `/{billingScope}/providers/Microsoft.CostManagement/exports/{name}` | 2023-07-01-preview | Create the FOCUS export. Runs once during setup only                   | SA (setup)    |
| 7 | POST   | `/{scope}/providers/Microsoft.CostManagement/exports/{name}/run`    | 2023-07-01-preview | Trigger export run for a specific month (backfill, customer-initiated) | SA (backfill) |

<Info>
  **FOCUS Export Data Flow**

  The FOCUS export (*nops-clara-focus-export*) writes daily Parquet files to *focus-exports/nops-clara*
  inside the dedicated storage account. The nOps data ingestion service reads these files from outside Azure using static IPs *44.246.45.84*, *52.11.53.164*, and *52.39.155.200*. If you enforce storage firewalls, only these three IPs need to be whitelisted.
</Info>

### 3.3 Billing Account Discovery

Used to discover billing account structure and validate/assign billing roles. The PUT call (#11)
assigns the EnrollmentReader or EA Purchaser role and runs only during the customer-
executed setup script.

| #  | Method | Endpoint                                                                          | API Version | Purpose                                                      | Tier            |
| -- | ------ | --------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ | --------------- |
| 8  | GET    | `/providers/Microsoft.Billing/billingAccounts`                                    | 2024-04-01  | Discover the EA or MCA billing account ID                    | SA              |
| 9  | GET    | `/providers/Microsoft.Billing/billingAccounts/{id}/billingProfiles`               | 2024-04-01  | List billing profiles (MCA)                                  | SA              |
| 10 | GET    | `/providers/Microsoft.Billing/billingAccounts/{id}/billingRoleAssignments`        | 2024-04-01  | Validate billing role assignment exists                      | SA              |
| 11 | PUT    | `/providers/Microsoft.Billing/billingAccounts/{id}/billingRoleAssignments/{guid}` | 2024-04-01  | Assign EnrollmentReader / EA Purchaser role (EA, setup only) | SA / CM (setup) |

### 3.4 Monitoring (Activity Log)

Called once per subscription to validate Monitoring Reader access. The query is intentionally
minimal for the last 1 hour, top 1 event only. Also used as a rightsizing signal.

| #  | Method | Endpoint                                                                        | API Version | Filter               | Tier |
| -- | ------ | ------------------------------------------------------------------------------- | ----------- | -------------------- | ---- |
| 12 | GET    | `/subscriptions/{id}/providers/Microsoft.Insights/eventtypes/management/values` | 2015-04-01  | Last 1 hour, \$top=1 | SA   |

### 3.5 Storage Account Access

Scoped exclusively to the nopsfocus dedicated storage account. listKeys (#14) is used during
setup validation, not in ongoing runtime operations.

| #  | Method | Endpoint                                             | API Version | Purpose                                                                      | Tier       |
| -- | ------ | ---------------------------------------------------- | ----------- | ---------------------------------------------------------------------------- | ---------- |
| 13 | GET    | `/Microsoft.Storage/storageAccounts/{name}`          | 2023-05-01  | Verify the dedicated storage account exists                                  | SA         |
| 14 | POST   | `/Microsoft.Storage/storageAccounts/{name}/listKeys` | 2023-05-01  | Verify Owner access on the dedicated storage account (setup validation only) | SA (setup) |

### 3.6 Lighthouse Delegations

Used to verify the Lighthouse delegation is active. nOps deploys an Azure Lighthouse ARM template at the management group scope for Savings Analysis, and additionally at the
dedicated subscription scope for Commitment Management.

| #  | Method | Endpoint                                                                                                             | API Version | Purpose                                                                                                | Tier |
| -- | ------ | -------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ | ---- |
| 15 | GET    | `/subscriptions/{id}/providers/Microsoft.ManagedServices/registrationAssignments?$expandRegistrationDefinition=true` | 2022-10-01  | Verify Lighthouse delegation is active (checks for nOpstenant ID 9a93f7e1-76f9-4a8d-a15e-5eeb73cf1d18) | SA   |

<Info>
  **Lighthouse Visibility & Revocation**

  All Lighthouse delegations are fully visible in Azure Portal under Service Providers > Service provider
  offers and can be removed at any time. Removal immediately terminates nOps access.
</Info>

### 3.7 Reservations API

Read calls are Savings Analysis. The PUT purchase call (#19) is Commitment Management
only and creates a new reservation — no existing resources are modified or deleted.

| #  | Method | Endpoint                                                            | API Version | Purpose                                                                 | Tier    |
| -- | ------ | ------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- | ------- |
| 16 | GET    | `/providers/Microsoft.Capacity/.../permissions`                     | 2022-04-01  | Check effective permissions at Reservations provider scope (validation) | SA      |
| 17 | GET    | `/providers/Microsoft.Capacity/reservationOrders`                   | 2022-11-01  | List all reservation orders                                             | SA / CM |
| 18 | GET    | `/providers/Microsoft.Capacity/reservationOrders/{id}/reservations` | 2022-11-01  | List reservations within an order                                       | SA / CM |
| 19 | PUT    | `/providers/Microsoft.Capacity/reservationOrders/{id}`              | 2022-11-01  | Purchase a new Reservation                                              | CM Only |

### 3.8 Savings Plans API

Read calls are Savings Analysis. The PUT purchase call (#22) is Commitment Management
only and creates a new savings plan — no existing resources are modified or deleted.

| #  | Method | Endpoint                                                      | API Version | Purpose                                                                      | Tier    |
| -- | ------ | ------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------- | ------- |
| 20 | GET    | `/providers/Microsoft.BillingBenefits/.../permissions`        | 2022-04-01  | Check effective permissions at the Savings Plans provider scope (validation) | SA      |
| 21 | GET    | `/providers/Microsoft.BillingBenefits/savingsPlans`           | 2022-11-01  | List all savings plans                                                       | SA / CM |
| 22 | PUT    | `/providers/Microsoft.BillingBenefits/savingsPlanOrders/{id}` | 2022-11-01  | Purchase a new Savings Plan                                                  | CM Only |

## 4. Required RBAC Permissions (Savings Analysis)

The following roles are assigned during the Savings Analysis onboarding process. Roles at the
Management Group scope cascade to all subscriptions underneath. The two storage-account
roles are scoped exclusively to the single dedicated nopsfocus storage account.

### 4.1 Management Group Scope

| Role                        | Role Definition ID                   | Purpose                                              |
| --------------------------- | ------------------------------------ | ---------------------------------------------------- |
| Reader                      | acdd72a7-3385-48ef-bd42-f606fba81ae7 | List/view all resources (inventory, rightsizing)     |
| Cost Management Contributor | 434105ed-43f6-45c7-a02f-909b2ba83430 | Query cost data; create/manage FOCUS exports         |
| Monitoring Reader           | 43d0d8ad-25c7-4714-9337-8ba259a9fe05 | Read activity logs and metrics (rightsizing signals) |

### 4.2 Storage Account Scope (Dedicated Only)

| Role                     | Role Definition ID                   | Purpose                                                 |
| ------------------------ | ------------------------------------ | ------------------------------------------------------- |
| Owner                    | 8e3af657-a8ff-443c-a75c-2fe8c4bcb635 | Manage the nOps FOCUS export storage account (see note) |
| Storage Blob Data Reader | 2a2b9908-6ea1-4ae2-8e65-a410df84e7d1 | Read exported cost data blobs (data-plane)              |

<Warning>
  **Important: Storage Account Owner scope is strictly limited**

  The Owner role is granted exclusively on the nopsfocus\<first-15-hex-chars-of-tenant-id> storage
  account created by nOps. It does not grant Owner access to any other storage account or resource
  in your environment. This permission is required at setup time so Azure can assign the managed
  identity its StorageBlobDataContributor role on the export container. Once the export is created,
  nOps does not rely on the owner for ongoing operations.
</Warning>

### 4.3 Tenant Scope

| Scope                                | Role                | Role Definition ID                   | Purpose                                    |
| ------------------------------------ | ------------------- | ------------------------------------ | ------------------------------------------ |
| /providers/Microsoft.Capacity        | Reservations Reader | 582fc458-8989-419f-a480-75249bc5db7e | Read existing reservations, no purchasing  |
| /providers/Microsoft.BillingBenefits | Savings Plan Reader | d534ad90-4ac5-4815-a178-b2e47397baab | Read existing savings plans, no purchasing |

### 4.4 Billing Account Scope

| Billing Account Type               | Role                   | Role Definition ID                   | Purpose                         |
| ---------------------------------- | ---------------------- | ------------------------------------ | ------------------------------- |
| Enterprise Agreement (EA)          | EnrollmentReader       | 24f8edb6-1668-4659-b5e2-40bb5f3a7d7e | Read EA enrollment billing data |
| Microsoft Customer Agreement (MCA) | Billing Account Reader | (built-in)                           | Read MCA billing account data   |

## 5. Additional Permissions (Commitment Management)

Commitment Management is an optional tier that enables nOps to autonomously purchase and
manage Reservations and Savings Plans on your behalf. The following roles are assigned in
addition to all Savings Analysis roles.

### 5.1 Tenant Scope (Additional)

| Scope                                | Role                     | Role Definition ID                   | Purpose                       |
| ------------------------------------ | ------------------------ | ------------------------------------ | ----------------------------- |
| /providers/Microsoft.Capacity        | Reservations Contributor | b4ebc951-a0c2-41f7-a3cd-a57fe27c8e3a | Read and manage reservations  |
| /providers/Microsoft.BillingBenefits | Savings Plan Contributor | 28c0d4cd-558d-4de9-91a0-faa18e7b3266 | Read and manage savings plans |

### 5.2 Dedicated Subscription Scope (via Lighthouse)

| Role                   | Role Definition ID                   | Purpose                                              |
| ---------------------- | ------------------------------------ | ---------------------------------------------------- |
| Reservations Purchaser | f7b75c60-3036-4b75-91c3-6b41c27c1689 | Purchase reservations on the dedicated subscription  |
| Savings Plan Purchaser | 3d24a3a0-c154-4f6f-a5ed-adc8e01ddb74 | Purchase savings plans on the dedicated subscription |

### 5.3 Billing Account Scope (Additional)

| Billing Account Type               | Role                        | Role Definition ID                   | Purpose                                                 |
| ---------------------------------- | --------------------------- | ------------------------------------ | ------------------------------------------------------- |
| Enterprise Agreement (EA)          | EA Purchaser                | da6647fb-7651-49ee-be91-c43c4877f0c4 | Purchase reservations and savings plans via EA billing  |
| Microsoft Customer Agreement (MCA) | Billing Profile Contributor | (built-in)                           | Purchase reservations and savings plans via MCA billing |

## 6. Resources Created in Your Environment

During onboarding, nOps creates the following resources in the Azure subscription you
designate. No resources are created in any other subscription.

### 6.1 Service Principal

An App Registration is created automatically by Azure AD when you grant admin consent for the
nOps application. This is the identity used for all API access described in this document.

### 6.2 FOCUS Export Resources

| Resource Type     | Name                                     | Location      | Purpose                                        |
| ----------------- | ---------------------------------------- | ------------- | ---------------------------------------------- |
| App Registration  | nOps Application (created automatically) | Azure AD      | Identity used for all API access               |
| Resource Group    | nops-focus-exports-rg                    | East US       | Container for all nOps export resources        |
| Storage Account   | nopsfocus\<tenant-prefix>                | East US       | Storage destination for FOCUS cost export data |
| FOCUS Cost Export | nops-clara-focus-export                  | Billing scope | Scheduled export of FOCUS-format cost data     |

<Info>
  These resources incur minimal cost — only standard Azure Blob Storage fees for the exported
  cost data.
</Info>

### 6.3 Lighthouse Delegations

| Resource                           | Scope                  | Tier Required         |
| ---------------------------------- | ---------------------- | --------------------- |
| Lighthouse delegation (read-only)  | Management Group       | Savings Analysis      |
| Lighthouse delegation (purchasing) | Dedicated Subscription | Commitment Management |
| Azure Policy assignment            | Management Group       | Savings Analysis      |

<Info>
  **What is a Lighthouse Delegation?**

  Azure Lighthouse allows nOps to access your resources from the nOps tenant without requiring you
  to create credentials in nOps's environment. The delegation is read-only for Savings Analysis. For
  Commitment Management, a separate delegation on a dedicated subscription enables purchasing.
  You can review and revoke any Lighthouse delegation at any time from the Azure portal under
  Managed Services.
</Info>

### 6.4 Required Resource Providers

| Scope                     | Resource Provider               | Purpose                                      |
| ------------------------- | ------------------------------- | -------------------------------------------- |
| FOCUS Export Subscription | Microsoft.Storage               | Storage account for FOCUS export data        |
| FOCUS Export Subscription | Microsoft.CostManagement        | Cost queries and management                  |
| FOCUS Export Subscription | Microsoft.CostManagementExports | FOCUS export creation and scheduling         |
| All Subscriptions         | Microsoft.ManagedServices       | Lighthouse delegated resource access         |
| All Subscriptions         | Microsoft.PolicyInsights        | Policy compliance evaluation and remediation |

## 7. What nOps Does Not Access

The following are explicitly out of scope for the nOps integration. These restrictions are enforced
by the RBAC permissions listed in Section 4 — nOps has no path to access any of the
following.

| Items                                                                                                                             | Details      |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| VM state, disk contents, application configs, or deployment details                                                               | Not Accessed |
| Key Vault secrets, certificates, or keys                                                                                          | Not Accessed |
| Any storage account other than the dedicated nopsfocus export account                                                             | Not Accessed |
| Azure AD users, groups, or role assignments                                                                                       | Not Accessed |
| Network topology, NSG rules, or firewall configurations                                                                           | Not Accessed |
| Security Center / Microsoft Defender alerts or findings                                                                           | Not Accessed |
| Log Analytics workspaces or diagnostic logs (Activity Log access limited to 1 hour window, top 1 event, for role validation only) | Not Accessed |
| Any delete or modify operation on existing Azure resources                                                                        | Not Accessed |
| The ability to change subscription ownership or modify RBAC assignments after setup                                               | Not Accessed |
| Invoices or payment instruments                                                                                                   | Not Accessed |

## 8. Network Requirements

If your organisation enforces firewalls on storage accounts, the following nOps IP addresses
must be whitelisted on the FOCUS export storage account. Additionally, ensure Allow Azure
services on the trusted services list is enabled on the storage account firewall.

If your storage account allows public network access (the default), no firewall configuration is
needed.

| IP Address    | Purpose              |
| ------------- | -------------------- |
| 44.246.45.84  | nOps data processing |
| 52.11.53.164  | nOps data processing |
| 52.39.155.200 | nOps data processing |

## 9. Billing Policy Requirements

The following billing policies apply only to Commitment Management. Savings Analysis has no
billing policy dependencies.

| Agreement Type                     | Policy Location                  | Setting                      | Required Value |
| ---------------------------------- | -------------------------------- | ---------------------------- | -------------- |
| Enterprise Agreement (EA)          | Enrollment > Settings > Policies | Reserved Instances           | On             |
| Microsoft Customer Agreement (MCA) | Billing Profile > Policies       | Azure Reservation purchases  | Yes            |
| Microsoft Customer Agreement (MCA) | Billing Profile > Policies       | Azure Savings Plan purchases | Yes            |

## 10. Security Summary

The table below summarises the key security properties of the nOps Azure integration for
Savings Analysis.

| Property                           | Detail                                                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Authentication                     | Multi-tenant App Registration — service principal created via admin consent in your tenant. nOps never stores your credentials. |
| Write access to customer resources | None (Savings Analysis). Commitment Management is scoped to purchasing commitments only.                                        |
| Storage account Owner              | Scoped exclusively to the nOps-managed `nopsfocus&lt;tenant-prefix&gt;` storage account                                         |
| Data accessed                      | Cost data, reservation/savings plan inventory, Advisor cost recommendations, billing account structure, activity logs           |
| Data not accessed                  | VM config, secrets, application data, AD objects, network config, security alerts                                               |
| Access revocation                  | Remove the service principal from your tenant or delete the Lighthouse delegation — access terminates immediately               |
| Lighthouse                         | Read-only delegation at Management Group scope. Reviewable and revocable from Azure Managed Services portal.                    |
| CSP support                        | Not supported — EA and MCA only                                                                                                 |

<Info>
  For security questions, contact your nOps account team.
</Info>