Part #2: Tips for Microsoft Graph PowerShell SDK
In Part 1, I gave you an introduction to Microsoft Graph and specifically to the PowerShell SDK. In this Part 2 article, I’m sharing some tips which should help with your daily tasks. Of course, these tips also apply when you use the module for automation.
Authentication or authorization?
This topic is always good for confusion. Let me try to explain with an example.
When you purchase a plane ticket and you check-in, you need to provide proof that you are the person listed on the ticket (authentication) by presenting a government issued ID proving you are that person. When you board the plane, you are authorized to sit in a specific section of the plane where a seat has been assigned to you. So, while a person with an economy ticket may have successfully authenticated at the gate, they do not have the authorization to sit in first class!
Microsoft Graph won’t let you connect anonymously. You always need to provide an access token. This token authorizes you to perform actions e.g.: retrieve or modify data, change settings.
Permissions
We can distinguish between two buckets of permissions:
Delegated permissions
When delegated permissions are used, a user is always involved in flow. This is since an application act on behalf of the user, AFTER consent for the permission was granted by someone (this could be either the user itself or another privileged user).
The official documentation can be found here. The typical authorization flow is OAuth2.0 auth code and interactive. In case of restrictions e.g.: IoT devices or printers, OAUth2.0 device code flow would be your choice.
Application permissions
Application permissions do not have a user involved at all and therefore non-interactive. The typical scenarios are daemons or services as part of Line of Business applications. OAuth2.0 client credentials flow is used, which allows you to use either a shared secret (which is basically a string like a password) or a certificate.
Note: In any scenario, consent is required!
Another great documentation about authorization, authentication and permissions can be found in the Microsoft Graph Basics.
Connect-MgGraph
The Microsoft Graph PowerShell SDK is using by default the application with AppID 14d82eec-204b-4c2f-b7e8-296a70dab67e.
At this point I need to highlight that this app has no verified publisher configured:
If your organization has followed the best practices outlined by Microsoft itself here, you will not be able to use this application as you won’t be able to grant consent!
In this scenario, you need to register your own application as described here and use this to establish a connection.
Example:
The command used was the following:
Currently the cmdlet has the following parameters:
You might have spotted that there is no option for using client secret! Even OAuth2.0 client credentials flow supports this, it is not supported by the module.
However, if you have the need and can’t use a certificate, you can retrieve an access token outside of this module and pass the token to the cmdlet.
# Create body$Body = @{ client_id = '2f0701ae-1b5a-4fd2-b853-7f693da0b0f9' client_secret = 'DZ18Q~jZx3x-t8cJMd34pdYyo.MW6FHBYziiGaJY' scope = 'https://graph.microsoft.com/.default' grant_type = 'client_credentials'
}
# Splat the parameters for Invoke-Restmethod for cleaner code$PostSplat = @{ ContentType = 'application/x-www-form-urlencoded' Method = 'POST' Body = $Body Uri = 'https://login.microsoftonline.com/738f9144-7447-467c-ade6-7c2f1c064146/oauth2/v2.0/token'}
$accessToken = Invoke-RestMethod @PostSplatConnect-MgGraph -AccessToken $accessToken.access_token
As you can see, I’m now connected without usage of a certificate:
Multiple sessions with different context
The module uses by default the context of the current user when you not use Even OAuth2.0 client credentials flow. If you have already established a connection with one PowerShell process and you want to establish in another PowerShell process to Microsoft Graph with a different user, you need to use the parameter -ContextScope. This parameter accepts two values:
In this scenario you need to use Process, which means the module will use for this process another identity. This allows you to establish connections with different identities or different tenants, which is helpful in M&A scenarios.
Tweak your PowerShell profile
Now that we know how to connect, we want to simplify our daily work. For this we can leverage our PowerShell profile.
In my daily work, I don’t want to add all the application and client ids as parameters. Of course, we can save them all somewhere and perform copy and paste. To me this seems to be not efficient. As an example, I add two custom functions. One is for connecting using my registered application as user and the other to use OAuth2.0 client credentials flow with my secret:
function Connect-MGwithSecret{ # Create body $Body = @{ client_id = '2f0701ae-1b5a-4fd2-b853-7f693da0b0f9' client_secret = 'DZ18Q~jZx3x-t8cJMd34pdYyo.MW6FHBYziiGaJY' scope = 'https://graph.microsoft.com/.default' grant_type = 'client_credentials' } # Splat the parameters for Invoke-Restmethod for cleaner code $PostSplat = @{ ContentType = 'application/x-www-form-urlencoded' Method = 'POST' Body = $Body Uri = 'https://login.microsoftonline.com/738f9144-7447-467c-ade6-7c2f1c064146/oauth2/v2.0/token' } $accessToken = Invoke-RestMethod @PostSplat Connect-MgGraph -AccessToken $accessToken.access_token}function Connect-MGcustomApp{ $params = @{ ClientId = '2f0701ae-1b5a-4fd2-b853-7f693da0b0f9' TenantId = '738f9144-7447-467c-ade6-7c2f1c064146' ForceRefresh = $true ContextScope = 'Process' } Connect-MgGraph @params}
Now I can connect by running only the short commands either Connect-MGwithSecret or Connect-MGcustomApp:
Conclusion
I hope this article helps to understand the principals of authentication and authorization as well as gives you some ideas to improve your daily tasks.
Active Directory is the foundation of your network, and the structure that controls access to the most critical resources in your organization. The ENow Active Directory Monitoring and Reporting tool uncovers cracks in your Active Directory that can cause a security breach or poor end-user experience and enables you to quickly identify and remove users that have inappropriate access to privileged groups (Schema Admins, Domain Administrators). While ENow is not an auditing software, our reports reduce the amount of work required to cover HIPAA, SOX, and other compliance audits.
Access your FREE 14-day trial to accelerate your security awareness and simplify your compliance audits. Includes entire library of reports.