CloudServicesScriptContext

The CloudServicesScriptContext class is used to work with cloud services. To access an instance of this class, use the CloudServices property of the predefined PowerShell variable called $Context in your script.

Inheritance: Object

Methods

  • Method

  • Description

  • GetO365Tenant()

  • Returns an instance of the IAdmO365Tenant interface that represents the Microsoft 365 tenant the target object is associated with.

  • GetAzureAuthAccessToken()

  • Returns an Azure authentication token for the Microsoft 365 tenant associated with the target object. The token can be used for Microsoft Graph API only.

  • GetAzureAuthAccessToken(String)

  • Returns an Azure authentication token to be used to authenticate to the specified resource in the Microsoft 365 tenant associated with the target object.

  • CreateExchangeOnlinePSSession()

  • Creates a remote PowerShell session to Exchange Online in the Microsoft 365 tenant the target object is associated with.

Details

GetO365Tenant()

Returns an instance of the IAdmO365Tenant interface that represents the Microsoft 365 tenant the target object is associated with.

IAdmO365Tenant GetO365Tenant()

Return value

If there is no Microsoft 365 tenant associated with the target object, the method returns NULL.


GetAzureAuthAccessToken()

Returns an Azure authentication token for the Microsoft 365 tenant associated with the target object. The token can be used for Microsoft Graph API only.

String GetAzureAuthAccessToken()

Examples

The following code sample gets the date when the user last logged on to Azure AD.

# Get access token for Microsoft Graph API
$token = $Context.CloudServices.GetAzureAuthAccessToken()

# Get the last logon date
$userId = [Guid]$Context.TargetObject.Get("adm-O365ObjectId")
$url = 'https://graph.microsoft.com/beta/users/' + $userId.ToString() + '?$select=signInActivity'
$response = Invoke-RestMethod -Method GET `
    -uri $url `
    -Headers @{Authorization="Bearer $token"}

$lastLogonDate = $response.value[0].signInActivity.lastSignInDateTime

GetAzureAuthAccessToken(String)

Returns an Azure authentication token to be used to authenticate to the specified resource in the Microsoft 365 tenant associated with the target object.

String GetAzureAuthAccessToken(String resourceId)

Parameters

The resourceId parameter specifies the identifier of the resource for which to retrieve an authentication token.

Examples

The following code sample uses Azure Active Directory Graph API to add the user to Azure AD security groups containing the word Sales in their names.

# Get access token for Azure Active Directory Graph
$resourceId = "https://graph.windows.net/"
$token = $Context.CloudServices.GetAzureAuthAccessToken($resourceId)

# Get tenant details
$tenant = $Context.CloudServices.GetO365Tenant()
$tenantId = $tenant.TenantID
$credential = $tenant.GetCredential()

# Add the user to the groups
$userId = [Guid]$Context.TargetObject.Get("adm-O365ObjectId") 
Connect-AzureAD -AccountId $credential.AppId -AadAccessToken $token -TenantId $tenantId

$groups = Get-AzureADGroup -SearchString "Sales"
foreach ($group in $groups)
{
    Add-AzureADGroupMember -ObjectId $group.ObjectID -RefObjectId $userId.ToString()
}

CreateExchangeOnlinePSSession()

Creates a remote PowerShell session to Exchange Online in the Microsoft 365 tenant the target object is associated with.

PSSession CreateExchangeOnlinePSSession()

Examples

The following code sample converts the user's mailbox into a shared mailbox in Exchange Online.

try
{
    $session = $Context.CloudServices.CreateExchangeOnlinePSSession()
    Import-PSSession $session -CommandName "Set-Mailbox" 
    
    # Get the user's identifier in Microsoft 365
    $userId = [Guid]$Context.TargetObject.Get("adm-O365ObjectId")
    
    # Change mailbox type
    Set-Mailbox $userId.ToString() -Type Shared
}
finally
{
    # Close the remote session
    if ($session) { Remove-PSSession $session }
}

Requirements

Minimum required version: 2021.1

See also