corso/src/cmd/graph_pwsh

Graph SDK Powershell Troubleshooter

In certain cases, troubleshooting would be significantly simplified if a Corso user had a simple mechanism to execute targeted MS Graph API commands against their environment.

One convenient mechanism to accomplish this without going down to the level of wrapping individual Graph API calls is to use the Microsoft Graph Powershell. It provides a convenient wrapper and great coverage of the API surface.

Build container

Before using the tool you want to build the container that packages it.

docker build -t corso/graph_pwsh:latest .

A prebuilt image is also available currently available as gmatev/graph_pwsh.

Prerequisites

Docker

You need to have Docker installed on your system.

Azure AD app credentials

The tool uses your existing Corso app to make Graph calls and for authentication you want AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET to be set as environment variables. You can read more about this here. You will then pass these into the container run so that authentication can be completed.

Using the tool

Interactive use

This is suitable if you would like to issue a number of MS Graph API commands from an interactive shell in the container.

docker run --rm -it -v $(pwd):/usr/pwsh -e AZURE_TENANT_ID -e AZURE_CLIENT_ID -e AZURE_CLIENT_SECRET corso/graph_pwsh pwsh

Alternatively you can use an environment variable file env_names that has the names of the required environment variables

docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh pwsh

Before you run any command you want to authenticate with Graph using a convenient script that will create a connection using the default permissions granted to the app.

PS> ./Auth-Graph.ps1

If you know what you are doing feel free to use Connect-MgGraph directly.

Specific command use

Suitable when you want to run just a single command. Essentially running the Auth-Graph.ps1 before the actual command you want to run.

docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh \
       pwsh -c "<your Graph command>"

Here is a complete example to get all users

# This is the equivalent of GET https://graph.microsoft.com/v1.0/users
docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh \
       pwsh -c "Get-MgUser -All"

Another example to retrieve an email message for a given user by ID.

# This is the equivalent of GET https://graph.microsoft.com/v1.0/<userID>/messages/<messageId>
docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh \
       pwsh -c "Get-MgUserMessage -UserId <userID or UPN> -MessageID <messageID>"

Running a remote script

In some cases, it may be prudent to run a more complex Powershell script that strings a number of commands together. While it is possible to compact the sctipt to a single line, that is quite inconvenient.

Instead, it is possible to stash the desired script somewhere publically accessible (e.g. Gist) and execute the container which will pull it and then execute it. This can be done using the Execute-Script.ps1 command as follows.

docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh \
       pwsh -c "Execute-Script.ps1 -ScriptUrl <script download URL>"

Debug output

To see the requests and responses made by the specific Graph Powershell commands, add -Debug to you command, similar to the example below.

# This is the equivalent of GET https://graph.microsoft.com/v1.0/users
docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh \
       pwsh -c "Get-MgUser -All -Debug"

Using Beta API calls

In order to use the Beta Graph API, make sure you have done export MSGRAPH_USE_BETA=1 before running the container and pass the environment variable in.

Alternatively you can do the following:

# This is the equivalent of GET https://graph.microsoft.com/v1.0/users
docker run --rm -it -v $(pwd):/usr/pwsh --env-file env_names corso/graph_pwsh \
       pwsh -c "Select-MgProfile -Name "beta" && Get-MgUser -All"

Graph PowerShell reference

To learn about specific commands, see the Graph PowerShell Reference