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

  • GetAzureAuthAccessToken()

  • Returns an Azure authentication token for the Microsoft 365 tenant associated with the 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 object.

  • CreateExchangeOnlinePSSession()

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

Properties

  • Property

  • Description

  • AzureTenant

  • Gets information about the object's Azure AD tenant.

Details

GetAzureAuthAccessToken()

Returns an Azure authentication token for the Microsoft 365 tenant associated with the 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
$url = 'https://graph.microsoft.com/beta/users/' + $user.AzureId + '?$select=signInActivity'
$response = Invoke-RestMethod -Method GET `
    -uri $url `
    -Headers @{Authorization="Bearer $token"}

$lastLogonDate = $response.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 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 groups containing the word Sales in their names.

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

# Add the user to the groups
Connect-MgGraph -AccessToken $token
$groups = Get-MgGroup -ConsistencyLevel eventual -Search "DisplayName:Sales"

foreach ($group in $groups)
{
    New-MgGroupMember -GroupId $group.Id -DirectoryObjectId $Context.TargetObject.AzureId
}

CreateExchangeOnlinePSSession()

Creates a remote PowerShell session to Exchange Online in the Microsoft 365 tenant the 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"
    
    # Change mailbox type
    Set-Mailbox $user.AzureId -Type Shared
}
finally
{
    # Close the remote session
    if ($session) { Remove-PSSession $session }
}

AzureTenant

Gets information about the object's Azure AD tenant. For an on-premises AD object the property gets information about the Microsoft 365 tenant the object is associated with.

Remarks

For on-premises AD objects not associated with any Microsoft 365 tenant the property is null.

Examples

The following code sample updates user permissions over a SharePoint Online folder in the specified site.

$url = "https://company.sharepoint.com/sites/MySite"

# Get Azure app identifier
$appId = $Context.CloudServices.AzureTenant.AuthApplicationId

# Connecto to SharePoint Online
try
{
    Connect-PnPOnline -Url $url -ClientId $appId -Thumbprint $certificateThumbprint`
        -Tenant "company.onmicrosoft.com"
    
    # Grant user permissions
    Set-PnPFolderPermission -List "Shared Documents" -Identity "Shared Documents/Folder"`
        -User "%userPrincipalName%" -AddRole "Contribute"
}
finally
{
    # Close the connection and release resources
    Disconnect-PnPOnline
}

Requirements

Minimum required version: 2023

See also