Skip to content

Latest commit

 

History

History
195 lines (131 loc) · 7.25 KB

GET-STARTED.md

File metadata and controls

195 lines (131 loc) · 7.25 KB
Raw
title description ms.topic ms.date ms.author ms.reviewer manager author
Microsoft Entra PowerShell installation and usage guide.
Microsoft Entra PowerShell installation and usage guide.
reference
04/05/2024
eunicewaweru
stevemutungi254
CelesteDG
msewaweru

Get Started

Table of Contents

Installation

PowerShell Gallery

Run the following command in a PowerShell session to install the Microsoft Entra PowerShell module:

Install-Module -Name Microsoft.Graph.Entra -AllowPrerelease -Repository PSGallery -Force

To install the beta module, use:

Install-Module -Name Microsoft.Graph.Entra.Beta -AllowPrerelease -Repository PSGallery -Force

The latest version of PowerShell 7 is the recommended version of PowerShell for use with the Microsoft Entra PowerShell module on all platforms including Windows, Linux, and macOS. This module also runs on Windows PowerShell 5.1 with .NET Framework 4.7.2 or higher.

If you have an earlier version of the Microsoft Entra PowerShell module installed from the PowerShell Gallery and would like to update to the latest version, run the following command in a PowerShell session:

Update-Module -Name Microsoft.Graph.Entra -AllowPrerelease

Update-Module installs the new version side-by-side with previous versions. It doesn't uninstall the previous versions.

For more information on installing Microsoft Entra PowerShell, see the installation guide.

Building the module locally

For preview features, you can build the module locally from GitHub source code. See Build module locally.

Usage

Sign in

To connect to Microsoft Entra ID, use the Connect-Entra cmdlet:

# Opens a new browser window to log into your Microsoft Entra ID account.
Connect-Entra -Scopes 'User.Read.All', 'Group.ReadWrite.All'

For details on authentication scenarios: delegated (interactive) or app-only (noninteractive), see Authentication scenarios.

Sign in to a national cloud

To log into a specific cloud national cloud, use the Environment parameter:

# Log into a specific cloud, for example the Azure China cloud.
Connect-Entra -Environment China

To get a list of available environments, run:

Get-EntraEnvironment

Discovering cmdlets

Use Get-Command to discover cmdlets within a specific module, or cmdlets that follow a specific search pattern:

# List all cmdlets in the Microsoft Entra PowerShell module
Get-Command -Module Microsoft.Graph.Entra

Cmdlet help and examples

To view the help content for a cmdlet, use the Get-Help cmdlet:

# View basic help information for Get-EntraUser
Get-Help -Name Get-EntraUser

# View the examples for Get-EntraUser
Get-Help -Name Get-EntraUser -Examples

# View the full help for Get-EntraUser
Get-Help -Name Get-EntraUser -Full

Run commands with -Debug option

To gain insights into the calls being made, you can add -debug option.

Get-EntraUser -SearchString 'Adele' -Debug

To send debug output stream to a log file, use:

Get-EntraUser -Top 1 -Debug 5>> <your-log-filepath>

For more information, see documentation guide.

Migrate from Azure AD

The Enable-EntraAzureADAlias cmdlet enables compatibility mode through aliases. By default, Enable-EntraAzureADAlias only enables compatibility aliases for the current PowerShell session. For more information, see the migration guide.

Testing compatibility of a script

You can use the Test-EntraScript command to test compatibility of an AzureAD PowerShell module-based script. This helps determine if a script can be migrated to the Microsoft Entra PowerShell module.

Test-EntraScript -Script .\export-apps-with-expiring-secrets.ps1

If the script is compatible, you won't see any output, although you can use $? to display that True was returned. If the script isn't compatible, a warning with details of the issues is displayed. Example:

Test-EntraScript -Script .\export-apps-with-expiring-secrets.ps1

WARNING: Command Get-AzureADApplicationKeyCredential is not supported
WARNING: Script contains commands that are not supported by the compatibility adapter.

Tip

You can access the export-apps-with-expiring-secrets.ps1 from our samples page.

Pipelining feature

With Pipelining, you can perform updates from the output of another command as inputs. For example, updating the Postal Code address for all group members after a reporting line changes.

Get-EntraGroup -Filter "DisplayName eq 'Contoso Team'" | Get-EntraGroupMember | Set-EntraUser -PostalCode 90134

Reporting Issues and Feedback

Issues

If you find any bugs when using Microsoft Entra PowerShell, file an issue in our GitHub repo. Fill out the issue template with the appropriate information. We value your feedback.

Contributing

For details on contributing to this repository, see the contributing guide

Data Collection

Microsoft Entra PowerShell collects telemetry data by default. We collection information about the Microsoft Entra PowerShell version and the cmdlet executed. Microsoft aggregates collected data to identify patterns of usage to identify common issues and to improve the experience of Microsoft Entra PowerShell. Microsoft Entra PowerShell doesn't collect any private or personal data. For example, the usage data helps identify issues such as cmdlets with low success and helps prioritize our work.

Learn more