Integration Guide
meshcloud can automatically provision Azure Subscriptions as Tenants for meshProjects and configure them according to your organiziations policies using Landing Zones.
Integration Overview
To enable integration with Azure, operators need to deploy and configure the meshStack Azure Replicator. Operators can configure one or multiple PlatformInstance
s of PlatformType.Azure
. This makes Azure available to meshProjects like any other cloud platform in meshStack.
Azure relies on Azure Active Directoy (AAD) for authentication and authorization. meshcloud can seamlessly integrate with common AAD setups like Azure Hybrid Identity. meshcloud helps you implement Azure in line with Governance best-practices by integrating Blueprints and Management Groups using Landing Zones
In order to plan and execute a successful integration of Azure using meshcloud, organizations need to consider the following parts described in the sections below.
Azure Active Directory Integration
All subscriptions in Azure must be associated with exactly one AAD Tenant storing role and permission assignments. Azure uses this AAD Tenant to evaluate permissions on all resources contained in that subscription. meshcloud manages roles and assignments by automatically replicating meshProject Role Assignments to this AAD Tenant.
However, a key decision in any Azure integration is how your organization wants to provision user identities in this AAD Tenant. The two different ways supported by meshstack are described below.
Externally-provisioned Identities
The default model expected by Microsoft is Hybrid Identity, i.e. a local Active Directory (AD) synced to Azure (Azure Active Directory, AAD). Organizations can implement this sync using Azure Active Directory Connect (AD Connect). This sync populates user identities into an AAD Tenant owned by the organization and can also synchronize existing groups and memberships.
The user identities are synchronized to your organization's "home tenant", which also owns the email domains identifying these users. In most organizations, other applications like Office 365 already consume user identities from this AAD Tenant.
Please make sure that all users who need access to the Azure Portal are replicated into the AAD. meshcloud will issue a replication warning for projects that have role assignments that cannot be replicated because a user identity could not be found on the home tenant.
Workload AAD Tenant
Because meshcloud requires read-write permissions to manage user roles on Azure Subscriptions, we recommend creating a separate "Workload AAD Tenant" to be exclusively used by meshcloud. Our orchestration engine then creates Guest Users in the meshcloud AAD Tenant that reference user identities from the "home tenant" (AAD B2B). This way, users have a single cloud identity managed by your organization-wide policies while isolating "workload" related Azure activies into its own AAD Tenant which has no way of affecting other applications using the home tenant like Office 356 etc.
External User Ids (euid)
Using externally-provisioned user identities requires your IdP to provide a user identifier suitable to locate user identities
in the "home tenant". This external user id needs to be mapped to the euid
user attribute in the meshIdB.
It is important that the provided euid's are case-sensitive and must match the user entries saved in the AAD against which the replication should happen! This is a limitation imposed by the search queries of Microsoft Graph API.
meshcloud can support complex Azure AD setups involving user identity lookup rules and multiple home tenants. Please contact our experts for more details.
Licensing Considerations
Users managed in the meshcloud AAD Tenant do not require AAD Premium Licenses.
Subscription Provisioning
To provide Azure Subscription for your organization's meshProjects, meshcloud supports using Enterprise Enrollment or allocating from a pool of pre-provisioned subscriptions. Operators can find the corresponding configuration options in the Provisioning Configuration Reference.
Enterprise Enrollment Account
meshcloud can automatically provision new subscriptions from an Enterprise Enrollment Account owned by your organization. This is suitable for large organizations that have a Microsoft Enterprise Agreement, Microsoft Customer Agreement or a Microsoft Partner Agreement and want to provide a large number of subscriptions in a fully automated fashion.
Microsoft currently has limitation of a maximum of 2000 Subscriptions per Enrollment Account (EA). It's therefore possible to configure meshStack to consume subscriptions from multiple EA's for the same meshPlatform. Please contact our experts for more details.
Setting up the Enrollment Account
We recommend using dedicated enrollment accounts (EA) for exclusive use by meshcloud.
EA Administrators must be careful to chose an EA Account Owner that's homed in the meshcloud AAD Tenant!
Subscriptions provisioned through the EA get automatically associated with the AAD Home-Tenant of the EA Account Owner. If your organization uses Microsoft (i.e. outlook.com) identities as EA Account Owner, please invite the EA Owner user first into the meshcloud AAD Teant before creating the enrollment account.
To list your available EA accounts you can use the Get-AzEnrollmentAccount
powershell command:
PS C:\> Get-AzEnrollmentAccount
ObjectId PrincipalName
-------- -------------
dbd8453d-071f-4fb4-8e01-c99f5b067649 jason@contoso.onmicrosoft.com
7ff524ac-a0de-4402-876f-934ccee3b601 carol@contoso.onmicrosoft.com
After creating (or finding) a suitable EA Account, please note down the accounts object id as EA_ACCOUNT_ID
.
Ensuring Retained Subscription Owners
Azure requires that there's at least one "Owner" or "Classic Administrator" role assignment on each subscription. Unfortunately, it's not a sufficient workaround to inherit the Owner role via the Management Group Hierarchy onto the Subscription. Instead a direct role assignment must exist. this Owner can also be the Azure Blueprint Service Principal
In contrast to other provisioning methods, EA provisioning will not retain a default
"Classic Administrator" role assignment on the subscription from the billing account owner. Operators should therefore configure at least one explicit owner under subscriptionOwnerObjectIds
. This owner can also be an empty AAD group or Service Principal.
You should never grant subscription owner roles to the meshStack replicator SPN.
Pre-provisioned Subscriptions
If your organization does not have access to an Enterprise Enrollment, you can alternatively configure meshcloud to consume subscriptions from a pool of externally-provisioned subscriptions. This is useful for smaller organizations that whish to use "Pay-as-you-go" subscriptions or if you're organization partners with an Azure Cloud Solution Provider to provide your subscriptions.
The meshcloud Azure replication detects externally-provisioned subscriptions based on a configurable prefix in the subscription name. Upon assignment to a meshProject, the subscription is inflated with the right Landing Zone configuration and removed from the subscription pool.
Service Principal Setup
meshStack uses separate service principals for different tasks following the best practice of least privilege principle.
Replicator
In order to manage user roles and permissions, meshcloud requires a Service Principal on the AAD Tenant containing your Azure Subscriptions and workloads. The Service Principal must be authorized in the scope of this AAD Tenant.
AAD Level Permissions
- Under Azure Active Directory → App registrations create a new web app (call it e.g.
meshReplicator
). - Add an client secret under Certificates & secrets and write it down (it is the
SERVICE_PRINCIPAL_CLIENT_SECRET
). - Add the following application permissions (not delegated permissions) for the Microsoft Graph API (not Azure AD Graph API):
Directory.Read.All
- this permission is required to search the directory for existing users, groups and service principalsGroup.ReadWrite.All
this permissions is required to create new groupsUser.Invite.All
- this permission is required if you want to enable B2B User Invitation (see below)
- Click Grant permissions and make sure to also grant admin consent for each permission by clicking Grant admin consent in the permissions screen of the app.
- The following values are needed for meshPlatform configuration:
- Go to Azure Active Directory and write down either the AAD Tenant ID or the Primary domain (typically a
*.onmicrosoft.com
domain) ->AAD_TENANT
- Go to Azure Active Direcory → Enterprise application and search the newly created web app (created in step 1.)
- Application (client) ID ->
SERVICE_PRINCIPAL_CLIENT_ID
- Application object id ->
SERVICE_PRINCIPAL_OBJECT_ID
- Application (client) ID ->
- Go to Azure Active Directory and write down either the AAD Tenant ID or the Primary domain (typically a
Operators need to supply these variables to the meshStack Configuration for this Azure Platform Instance.
Azure RBAC Permissions
Created subscriptions will have the Service Principal of the replicator registered as an owner at first. As soon as all needed maintenance steps are performed (e.g. renaming the subscription, moving it into the final management group), the replicator removes itself as an owner.
All permissions left are therefore granted only via the management group hierarchy. The meshstack software does not need access related to actual workload inside these subscriptions. However in order to perform certain maintenance tasks, the following permissions/roles must be granted to the replicator principal:
# Assigning Users
"Microsoft.Authorization/permissions/read",
"Microsoft.Authorization/roleAssignments/*",
"Microsoft.Authorization/roleDefinitions/read",
# Assigning Blueprints
"Microsoft.Resources/deployments/*",
"Microsoft.Blueprint/blueprintAssignments/*",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Resources/deployments/*",
# Fetching Blueprints
"Microsoft.Management/managementGroups/read",
"Microsoft.Management/managementGroups/descendants/read",
# Assigning Subscriptions to Management Groups
"Microsoft.Management/managementGroups/subscriptions/write",
"Microsoft.Management/managementGroups/write",
# Permissions for reading and writing tags
"Microsoft.Resources/tags/write",
# Permission we need to activate/register required Resource Providers
"*/register/action"
You must must grant the meshcloud Service Principal this level access to all management groups used in Landing Zones.
In Azure Portal, navigate to the "Management Groups" blade, then click on the "Details" link of the management group you want to give access to. Select "Access Control (IAM)" from the menu and create a role assignment of the custom IAM role created above for the replicator Service Principal.
Access to the Management Groups may require the "Global Administrator" role with elevated access. In case you're not able to see all management groups after elevating access, try signing out and back in to Azure Portal.
Privilege Escalation Prevention
Furthermore in order to prevent the replicator from assigning itself more permissions, we recommended to add the following policy on a root management group level:
{
"properties": {
"mode": "all",
"displayName": "meshcloud Privilege Escalation Prevention",
"description": "Prevent replicator SPN from assigning itself new roles.",
"policyRule": {
"if": {
"allOf": [
{
"equals": "Microsoft.Authorization/roleAssignments",
"field": "type"
},
{
"allOf": [
{
"field": "Microsoft.Authorization/roleAssignments/principalId",
"equals": "<SERVICE_PRINCIPAL_OBJECT_ID>"
},
]
}
]
},
"then": {
"effect": "deny"
}
}
}
}
EA Account Permissions
When using an Enterprise Enrollment Account (EA) for Subscription provisioning, an EA Administrator must authorize the meshcloud Service Principal on the Enrollment Account following the official instructions.
When using powershell, use the following command and substitue parameters as follows:
<replicatorSpnApplicationId>
the Application Client Id of the Replicator SPN. In Azure Portal, this is the "Application Id" of the "Enterprise Application" but can also be retrieved via the "App Registration" blade as "Application (Client) Id".<enrollmentAccountObjectId>
the object id of the Enrollment Account, retrieved e.g. viaGet-AzEnrollmentAccount
New-AzRoleAssignment -RoleDefinitionName Owner -ApplicationId <replicatorSpnApplicationId> -Scope /providers/Microsoft.Billing/enrollmentAccounts/<enrollmentAccountObjectId>
Metering
In order to read resource usages, a metering principal is needed. It requires the following permissions/roles on all resources which should be accessed by meshStacks's metering service:
Cost Management Reader
Blueprint Configuration
The Azure Blueprints
service principal id is different in every AAD Tenant, so we need to find the id
of the app in the managed AAD Tenant.
The easiest way to accomplish this is to start an Azure cloud shell in a subscription on the meshcloud AAD Tenant and execute the following command:
Get-AzureRmADServicePrincipal -ApplicationId f71766dc-90d9-4b7d-bd9d-4499c4331c3f
The response should be similar to
ServicePrincipalNames : {f71766dc-90d9-4b7d-bd9d-4499c4331c3f}
ApplicationId : f71766dc-90d9-4b7d-bd9d-4499c4331c3f
ObjectType : ServicePrincipal
DisplayName : Azure Blueprints
Id : 2a6a62ad-e28b-4eb4-8f1e-ce93dbc76d20
This Id
needs to be configured in the Azure Platform configuration.