Microsoft Graph PowershellSDK
In our last blog, we introduced Microsoft Graph and its benefits for workforce management. Today, we’re going to delve into the practical aspects of Microsoft Graph: how to install and connect to it. We’ll provide specific commands and illustrate different methods of connection, outlining their pros and cons to help you choose the best approach for your organization.
To facilitate seamless interaction with the Microsoft Graph API, Microsoft offers the Microsoft Graph PowerShell SDK. This toolkit comprises a collection of purpose-built PowerShell cmdlets that align with various Microsoft Graph API functions. Designed to enhance accessibility and efficiency, the Microsoft Graph PowerShell SDK serves as a valuable resource for developers and IT professionals. By leveraging PowerShell scripting, users can effectively engage with the Microsoft Graph API, which functions as a unified gateway to a diverse spectrum of Microsoft 365 services and data.
Introduction to Installing Microsoft Graph
You have two options for installing Microsoft Graph in your environment. Firstly and mandatory, you’ll need to install the primary Microsoft Graph PowerShell module, which focuses on the stable v2.0 version of the API. This can be accomplished using the following command:
Install-Module Microsoft.Graph -Scope CurrentUser
Alternatively, for those looking to experiment with the latest features, Microsoft also offers a beta module that targets the beta version of the API. This can be installed using the following command:
Install-Module Microsoft.Graph.Beta -Scope CurrentUser
Note: using Microsoft.Graph will install all the Microsoft Graph modules. however Best practice would be to only install the modules you intend to use, for example:
Install-Module -Name Microsoft.Graph.Authentication, Microsoft.Graph.Users, Microsoft.Graph.Groups, Microsoft.Graph.Identity.SignIns, Microsoft.Graph.Users.Actions -Scope CurrentUser.
Connecting to Microsoft Graph via PowerShell
There are a few ways to connect to Microsoft Graph, but here are three to get started:
1. Connect-MgGraph (Delegated Permissions) – Good
The Connect-MgGraph cmdlet is part of the Microsoft Graph PowerShell SDK and provides a simple way to establish a connection to Microsoft Graph using delegated permissions. Delegated permissions are used by apps that have a signed-in user present. The app is delegated permission to act as the signed-in user when making calls to the target resource.
Here’s a simple example of using Connect-MgGraph:
Connect-MgGraph -Scopes “User.ReadWrite.All”
When you run this command, a sign-in window will pop up, asking for your credentials. After successful authentication, you’re connected to Microsoft Graph and can start making requests.
Pros:
- It’s simple to use. You just need to run the cmdlet, and you’ll be prompted to sign in interactively.
- It handles the complexity of authentication behind the scenes, which makes it a good choice for quick, ad hoc queries and for those new to Microsoft Graph.
Cons:
- This method requires interactive sign-in, which may not be suitable for automated scripts or background tasks.
2. Using Application Secret (Application Permissions) – Better
Another way to connect to Microsoft Graph is by using an application secret, which is essentially a password for your application. This method is typically used for background services or daemons that run without a signed-in user being present.
To use an application secret, you’ll need to register an application in the Azure portal, then generate a secret for that application. After that, you can use the application (client) ID and the secret to authenticate.
Here’s an example of using Connect-MgGraph with an application secret:
# Add environment variables to be used by Connect-MgGraph.$Env:AZURE_CLIENT_ID = “application id of the client app”$Env:AZURE_TENANT_ID = “Id of your tenant”$Env:AZURE_CLIENT_SECRET = “secret of the client app” # Tell Connect-MgGraph to use your environment variables.Connect-MgGraph –EnvironmentVariable.
Pros:
- This method is suitable for server-to-server interactions that require application-level permissions and can run without user interaction.
- The secret can be set to expire after 2 years (unless you manually expire it), making it suitable for long-running applications.
Cons:
- If the secret is compromised, it could be used to gain access to your data. Therefore, you should handle and store the secret with care.
- The secret is not revocable, and it will continue to work until it’s manually expired. If it’s leaked, you need to expire it and update your applications with a new secret.
3. Using Application Certificate (Application Permissions) – Best
A third way to connect to Microsoft Graph is by using an application certificate. This is also typically used for background services or daemons. Using a certificate can be more secure than using a secret because the certificate can be more tightly controlled.
To use an application certificate, you’ll need to register an application in the Azure portal, then upload a certificate (self-signed or 3rd party) for that application. After that, you can use the application (client) ID and the certificate to authenticate.
Here’s a simple example of using Connect-MgGraph with an application certificate:
$AZURE_CLIENT_ID = “application id of the client app”$AZURE_TENANT_ID = “Id of your tenant”$CERT_THUMBPRINT = “thumbprint of certificate uploaded to app”Connect-MgGraph -ClientId “Client_Id” -Tenant “Tenant” -CertificateThumbprint “Cert_Thumbprint”.
Pros:
- Like the application secret, this method is also suitable for server-to-server interactions that require application-level permissions and can run without user interaction.
- Certificates are generally considered more secure than secrets as they can be protected with a private key and are harder to compromise.
- Certificates can also be revoked, which provides an additional level of security.
Cons:
- Managing certificates is more complex than managing secrets. You need to handle certificate creation, renewal, and potentially revocation.
- If the private key associated with the certificate is compromised, the certificate can be used by an unauthorized party until it’s revoked.
In all cases, remember that application-level permissions allow the application to perform actions without a user’s presence or consent, so they should be granted sparingly and protected carefully. Always follow the principle of least privilege and grant only the permissions that are only necessary, for your application.
Additionally, always run Disconnect-MgGraph when you are done to prevent your session from staying open.
Whether you’re connecting interactively, using an application secret, or using an application certificate, Microsoft Graph offers a variety of options to suit different scenarios. We’ve just scratched the surface of what’s possible with Microsoft Graph, and in our next blog, we’ll dive even deeper. Stay tuned!