Modules/M365DSCTenantInfo.psm1
|
<#
.SYNOPSIS Derives the tenant name from a bound parameter set. .DESCRIPTION Returns the tenant identifier directly when TenantId is present. Otherwise, it derives the tenant name from the credential user principal name. .PARAMETER ParameterSet Specifies the bound parameter hashtable to inspect. .FUNCTIONALITY Internal .OUTPUTS System.String #> function Get-M365DSCTenantNameFromParameterSet { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter(Mandatory = $true, Position = 1)] [System.Collections.HashTable] $ParameterSet ) if ($ParameterSet.ContainsKey('TenantId')) { return $ParameterSet.TenantId } elseif ($ParameterSet.ContainsKey('Credential')) { try { $tenantName = $ParameterSet.Credential.Username.Split('@')[1] return $tenantName } catch { return $null } } } <# .SYNOPSIS Resolves the organization domain from credential or tenant id. .DESCRIPTION Extracts the DNS domain part from the credential username when available. If no credential is provided, it validates and returns the tenant id when it represents a domain value. .PARAMETER Credential Specifies the credential containing a user principal name. .PARAMETER TenantId Specifies the tenant id or domain value to return. .FUNCTIONALITY Internal #> function Get-M365DSCOrganization { param ( [Parameter()] [System.Management.Automation.PSCredential] $Credential, [Parameter()] [System.String] $TenantId ) if ($null -ne $Credential -and $Credential.UserName.Contains('@')) { $organization = $Credential.UserName.Split('@')[1] return $organization } if (-not [System.String]::IsNullOrEmpty($TenantId)) { if ($TenantId.Contains('.')) { $organization = $TenantId return $organization } else { throw 'Tenant ID must be name of the tenant, e.g. contoso.onmicrosoft.com' } } } <# .SYNOPSIS Retrieves the tenant short name from initial Microsoft Graph domains. .DESCRIPTION Connects to Microsoft Graph and finds the initial onmicrosoft domain. Returns the tenant short name portion that is used to build workload-specific endpoints. .PARAMETER UseMFA Obsolete. This parameter has no effect and is ignored. .PARAMETER Credential Specifies the credential used for delegated authentication. .FUNCTIONALITY Internal #> function Get-M365TenantName { [CmdletBinding()] param ( # TODO: Remove during next breaking change release [Parameter(Mandatory = $false)] [switch] $UseMFA, [Parameter()] [System.Management.Automation.PSCredential] $Credential ) $initialDomain = Get-M365DSCInitialDomain -InboundParameters $PSBoundParameters $tenantName = $initialDomain.Split('.')[0] Write-Verbose -Message "M365 tenant name is $tenantName" return $tenantName } <# .SYNOPSIS Resolves API endpoint base URLs for the connected cloud. .DESCRIPTION Returns endpoint values used by Microsoft365DSC. Currently resolves the Azure management endpoint from the Azure connection profile, without a trailing slash. Requires an Azure connection. .PARAMETER TenantId Specifies the tenant id or tenant domain. Not used, the endpoint comes from the Azure connection profile. .EXAMPLE PS> Get-M365DSCAPIEndpoint -TenantId 'contoso.onmicrosoft.com' .FUNCTIONALITY Internal .OUTPUTS System.Collections.Hashtable #> function Get-M365DSCAPIEndpoint { [CmdletBinding()] [OutputType([System.Collections.Hashtable])] param( [Parameter(Mandatory = $true)] [System.String] $TenantId ) $managementUrl = (Get-MSCloudLoginConnectionProfile -Workload 'Azure').ManagementUrl if ([System.String]::IsNullOrEmpty($managementUrl)) { throw 'The Azure management endpoint is not available. Connect to the Azure workload first.' } return @{ AzureManagement = $managementUrl.TrimEnd('/') } } <# .SYNOPSIS Retrieves the SharePoint Online administration URL. .DESCRIPTION Connects to Microsoft Graph, discovers the initial tenant domain, and builds the SharePoint admin URL of the tenant cloud. Returns the URL in the https://tenant-admin.sharepoint.com format, with the SharePoint domain of US Government (sharepoint.us), DoD (sharepoint-mil.us), China (sharepoint.cn) and sovereign cloud tenants. .PARAMETER UseMFA Obsolete. This parameter has no effect and is ignored. .PARAMETER Credential Specifies the credential used for delegated authentication. .FUNCTIONALITY Internal #> function Get-SPOAdministrationUrl { [CmdletBinding()] param ( # TODO: Remove during next breaking change release [Parameter(Mandatory = $false)] [switch] $UseMFA, [Parameter()] [System.Management.Automation.PSCredential] $Credential ) Write-Verbose -Message 'Getting SharePoint Online admin URL...' $initialDomain = Get-M365DSCInitialDomain -InboundParameters $PSBoundParameters $tenantName = $initialDomain.Split('.')[0] $environmentName = (Get-MSCloudLoginConnectionProfile -Workload 'MicrosoftGraph').EnvironmentName if ($initialDomain -like '*.onsovcloud.*') { $adminHost = $initialDomain.Replace('.onsovcloud.', '-admin.sovcloud-sharepoint.') } elseif ($initialDomain -like '*.partner.onmschina.cn') { $adminHost = "$tenantName-admin.sharepoint.cn" } elseif ($environmentName -eq 'AzureDOD') { $adminHost = "$tenantName-admin.sharepoint-mil.us" } elseif ($environmentName -eq 'AzureUSGovernment') { $adminHost = "$tenantName-admin.sharepoint.us" } else { $adminHost = "$tenantName-admin.sharepoint.$($initialDomain.Split('.')[-1])" } $adminUrl = "https://$adminHost" Write-Verbose -Message "SharePoint Online admin URL is $adminUrl" return $adminUrl } <# .SYNOPSIS Returns the initial domain of the tenant (e.g. contoso.onmicrosoft.com). .DESCRIPTION Connects to Microsoft Graph and returns the initial onmicrosoft, onmschina or onsovcloud domain of the tenant. The default domain is not used because it could be a custom domain. .PARAMETER InboundParameters Specifies the parameters used to connect to Microsoft Graph. .FUNCTIONALITY Internal .OUTPUTS System.String #> function Get-M365DSCInitialDomain { [CmdletBinding()] [OutputType([System.String])] param( [Parameter(Mandatory = $true)] [System.Collections.Hashtable] $InboundParameters ) Write-Verbose -Message 'Connection to Microsoft Graph is required to determine the initial domain of the tenant...' $null = New-M365DSCConnection -Workload 'MicrosoftGraph' ` -InboundParameters $InboundParameters $domains = (Invoke-MgGraphRequest -Uri 'beta/domains' -Method GET -ErrorAction Stop).value $initialDomainPattern = '^[^.]+\.(onmicrosoft\.(com|de|us)|partner\.onmschina\.cn|onsovcloud\..+)$' foreach ($domain in $domains) { if ($domain.isInitial -eq $true -and $domain.id -match $initialDomainPattern) { return $domain.id } } throw 'Could not determine the initial onmicrosoft domain of the tenant.' } Export-ModuleMember -Function @( 'Get-M365DSCTenantNameFromParameterSet', 'Get-M365DSCOrganization', 'Get-M365TenantName', 'Get-M365DSCAPIEndpoint', 'Get-SPOAdministrationUrl' ) |