Navigating the maze of Graph API authentication can be confusing if you're not familiar with Graph, or APIs in general. To learn more about API authentication, check out this article from Nordic API.
OAuth is a common method of API authentication, but it is actually both authentication and authorization, as the user must provide login credentials to receive a token, and then the token carries the permissions for the user to the request server. Because we're used to typing in a password and authenticating right away, this can be an unfamiliar process for us sys admins.
This post will walk you through Graph API OAuth for Powershell, so that you can leverage the power of Graph to improve the automation in your environment.
Whenever I'm working with an unfamiliar API, I use Postman before starting my Powershell script. Postman is a free program for testing APIs, and can make it easier to figure out how to build your requests in Powershell. You can download it on for free here.
The process for authenticating to a Graph endpoint has two parts:
1. Create an Azure app to allow Graph access in your tenant
2. Retrieve a token from the OAuth endpoint using your creds, and info from the Azure app
In order to retrieve a token with your credentials, you'll need to create an Azure app in your tenant that you will use to grant and control permissions to the Graph API. You will need to be a Global Admin in your tenant to create this app. There's 3 pieces of information that you need to retrieve from the Azure app for your token request:
1. Directory (tenant) ID
2. Application (client) ID
3. Client Secret
Once you have these 3 pieces of information, you can move on to creating your API request to retrieve the token. You can do this in Powershell, or your preferred API test application.
Here are the steps to create your Azure app:
1. Go to portal.azure.com, sign in with global admin
2. Select Azure Active DirectorySelect App Registrations
3. Select + New RegistrationEnter a name for the application, for example "Microsoft Graph Native App"
4. Select "accounts in this organizational directory only"
5. Under Redirect URI, select the drop down and choose "Public client/native" and enter "https://redirecturi.com/"
6. Select "Register"
7. Make a note of your Application (client) ID, and your Directory (tenant) ID
8. Under Manage, select "API Permissions"
9. Click "+ Add Permission"
10. In the Request API Permissions blade, select "Microsoft Graph"
11. Select "Delegated Permissions"
12. Select the correct permissions set based on your request
13. Keep in mind that some requests require multiple permissions
14. Select "Add Permissions"
15. You will get a warning message that says "Permissions have changed, please wait a few minutes and then grant admin consent. Users and/or admins will have to consent even if they have already done so previously."
16. Click "Grant admin consent for <tenant>"
17. Wait for permissions to finish propagating, you'll see a green check-mark if it was successful
18. Under Manage, select Certificates & Secrets
19. Select "+ New client secret"
20. Give the secret a name that indicates its purpose (ex. PowerShell automation secret)
21. Under Expires, select Never
22. Copy the secret value. YOU WILL NOT SEE THIS SECRET AGAIN AFTER THIS
23. Now you have the Client ID, Tenant ID, and Secret to authenticate to Graph using PowerShell
Now that you've allowed permissions to use Graph API in your tenant, you need to grab a token for your request. To retrieve a token, you have to make an API request to a specific OAuth endpoint:
In Postman, create your request with the following Body and URI construction:
Here's how the same request will look in Powershell:
Now, in Postman, all you have to do is hit "Send", and you get your token result. It will look something like this if it's successful:
Just copy the results after "access_token", and you're off to the races.
In Powershell, you'll need to construct the Send request yourself using Invoke-WebRequest. To do this, add this to the top of your script:
Then, build the request:
When you run $tokenRequest, you'll see similar results to the Postman response. But since we're using this in Powershell, we'll probably want the token in a usable form. We can do this by using ConvertFrom-JSON:
Now, when you run $token, you should have a several-thousand character string that is your OAuth token!
You can now start working in Powershell using Graph API.
Here's the entire token request block for reference:
Here's an example call to Graph API using your OAuth token (Powershell):
Post a message to a Microsoft Teams channel:
There's a lot more you can do with Graph that I will be posting about in the future! Stay tuned.
Comments