Two main thigs that I want to concentrate in this post are ADAL deprecation and Graph PowerShell but also little bit about tokens.
Table of Contents
Microsoft is deprecating ADAL and Azure AD Graph
Just as a reminder to all who it concerns. Microsoft is deprecating ADAL and Azure AD Graph in June 2022. The notification all over the portals.
Installing MS Graph modules
|
1 2 3 4 5 6 7 |
# Only for current user, no admin rights needed. Install-Module Microsoft.Graph -Scope CurrentUser -AllowClobber -force # Install for all users, need admin rights Install-Module Microsoft.Graph -Scope AllUsers -AllowClobber -force |
Connecting to Graph with PowerShell
First you need to connect and consent permissions to Graph API.
|
1 |
Connect-Graph -Scopes "User.Read","Application.Read.All" |
And a familiar sign-in prompt will appear, when signed in select “Consent on behalf of your organization”
MS Graph App registrations
Azure AD App registrations
Listing Enterprise application with Graph
Why to upgrade?
Well, first of all it’s kind of mandatory but here a comparison for the differences made by Microsoft.
| Features | MSAL | ADAL |
|---|---|---|
| Security | ||
| Security fixes beyond December, 2022 |  |  |
| Proactively refresh and revoke tokens based on policy or critical events for Microsoft Graph and other APIs that support Continuous Access Evaluation (CAE). | | |
| Standards compliant with OAuth v2.0 and OpenID Connect (OIDC) | | |
| User accounts and experiences | ||
| Azure Active Directory (Azure AD) accounts | | |
| Microsoft account (MSA) | | |
| Azure AD B2C accounts | | |
| Best single sign-on experience | | |
| Resilience | ||
| Proactive token renewal | | |
| Throttling | | |
Get the list of application using ADAL
Basically you are sending your Azure AD sign-in logs to Monitor (Azure Monitor) and then use a Monitor workbooks to get apps that authenticate thru ADAL.
App migration planning checklist
Step 1: Review the differences between the APIs
In many respects, Microsoft Graph is similar to the earlier Azure Active Directory (Azure AD) Graph. In many cases, simply change the endpoint service name and version in your code, and everything should continue to work.
Nonetheless, there are differences. Certain resources, properties, methods, and core capabilities have changed.
Specifically, look for differences in the following areas:
- Request call syntax between the two services
- Feature differences, such as directory extensions, batching, differential queries, and so on
- Entity resource names and their types
- Properties of request and response objects
- Methods, including parameters and types
Step 2: Examine API use
Examine the APIs used by your app, the permissions they require, and compare to the list of known differences.
Verify that the APIs your app needs are generally available in Microsoft Graph v1.0 and that these APIs work the same way.
In some cases, new capabilities and features are designed to replace earlier approaches.
Use Graph Explorer to experiment with new calls and to develop new approaches. For best results, sign in using the credentials of a test user in a test tenant so that you see what the API does over important data sets.
Step 3: Review app details
- App registration and consent changes (which should be none).
- Token acquisition and authentication libraries.
- For .NET applications, use of client libraries.
Step 4: Deploy, test, and extend your app
Before updating your app for everyone, ensure you test thoroughly and stage your rollout to your customer audience.
Now you’ve made the switch to Microsoft Graph, it’s never been easier for you to unlock many more datasets and features that are now at your fingertips. You can get a taste of what’s possible by looking at some of the Major services and features in Microsoft Graph.
Microsoft authentication library (MSAL) is now the recommended authentication library for use with the Microsoft identity platform. If you’re currently using the Azure Active Directory Authentication Library (ADAL), plan to switch to MSAL. See further guidance to migrate applications to the Microsoft Authentication Library (MSAL).
App migration planning checklist – Microsoft GraphChecklist for migrating your apps from Azure Active Directory (Azure AD) Graph to Microsoft Graph
Differences between Delegated and Application permissions
From the on-premises world there one good example from IIS and how you will authenticate the users to different application pools.
Application permissions is like the User Impersonation was inside IIS and Delegated permissions is authenticating user on every request for every page in an application
- Delegated permissions are used by apps that have a signed-in user present. For these apps, either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making calls to Microsoft Graph. Some delegated permissions can be consented by non-administrative users, but some higher-privileged permissions require administrator consent.
- Application permissions are used by apps that run without a signed-in user present. For example, apps that run as background services or daemons. Application permissions can only be consented by an administrator.
PowerShell to Graph
Why Microsoft Graph PowerShell?
The following list summarizes the key advantages of using the Microsoft Graph PowerShell SDK:
- Access to all Microsoft Graph APIs not just Azure Active Directory: Microsoft Graph PowerShell SDK is based on Microsoft Graph API. The Microsoft Graph API includes, in addition to Azure AD, APIs from other Microsoft services like SharePoint, Exchange, Outlook, etc, all accessed through a single endpoint with a single access token. Azure AD Graph PowerShell is based on Azure AD Graph which is deprecated. To learn more on migrating from Azure AD Graph to Microsoft Graph see Microsoft Graph or Azure AD Graph.
- Cross-platform support and available on PowerShell 7 and above: Microsoft Graph PowerShell module works with PowerShell 7 and later and on all platforms including Windows, macOS, and Linux. It’s also compatible with Windows PowerShell 5.1.
- Supports modern authentication: Microsoft Graph PowerShell supports the Microsoft Authentication Library (MSAL) which offers more security that its Azure AD PowerShell Active Directory Authentication Library (ADAL) counterpart.
- Open source: Feature teams and the community can create great PowerShell experiences and share them with everyone.
Upgrading to Microsoft Graph PowerShell
Supported PowerShell versions
PowerShell 7 and later is the recommended PowerShell version for use with the Microsoft Graph PowerShell SDK on all platforms. There are no additional prerequisites to use the SDK with PowerShell 7 or later.
The following prerequisites must be met to use the Microsoft Graph PowerShell SDK with Windows PowerShell.
- Upgrade to PowerShell 5.1 or later
- Install .NET Framework 4.7.2 or later
- Update PowerShellGet to the latest version using
Install-Module PowerShellGet -Force
Scripts written in Azure AD PowerShell won’t automatically work with Microsoft Graph PowerShell. The new cmdlet names have been designed to be easy to learn. Instead of using AzureAD or AzureADMS in cmdlet names, use Mg. For example, the old cmdlet Get-AzureADUser has become Get-MgUser. However, migration is more than just becoming familiar with the new cmdlet names. There are renamed modules, parameters, and other important changes.
Finding the equivalent command?
Microsoft has a page for the commands from old cmdlets to Graph, it’s not complete but there is new commands coming all the time.
Authentication
There some really nice feature with Graph PowerShell and one of them is authentication with an Application.
Here a PowerShell that you can use to create an App registration and authenticate with certificate and Application.
Save the following as registerapp.ps1
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
param( [Parameter(Mandatory=$true, HelpMessage="The friendly name of the app registration")] [String] $AppName, [Parameter(Mandatory=$true, HelpMessage="The file path to your public key file")] [String] $CertPath, [Parameter(Mandatory=$false, HelpMessage="Your Azure Active Directory tenant ID")] [String] $TenantId, [Parameter(Mandatory=$false)] [Switch] $StayConnected = $false ) # Graph permissions constants $graphResourceId = "00000003-0000-0000-c000-000000000000" $UserReadAll = @{ Id="df021288-bdef-4463-88db-98f22de89214" Type="Role" } $GroupReadAll = @{ Id="5b567255-7703-4780-807c-7be8301ae99b" Type="Role" } # Requires an admin if ($TenantId) { Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -TenantId $TenantId } else { Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" } # Get context for access to tenant ID $context = Get-MgContext # Load cert $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath) Write-Host -ForegroundColor Cyan "Certificate loaded" # Create app registration $appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience "AzureADMyOrg" ` -Web @{ RedirectUris="http://localhost"; } ` -RequiredResourceAccess @{ ResourceAppId=$graphResourceId; ResourceAccess=$UserReadAll, $GroupReadAll } ` -AdditionalProperties @{} -KeyCredentials @(@{ Type="AsymmetricX509Cert"; Usage="Verify"; Key=$cert.RawData }) Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId # Create corresponding service principal New-MgServicePrincipal -AppId $appRegistration.AppId -AdditionalProperties @{} | Out-Null Write-Host -ForegroundColor Cyan "Service principal created" Write-Host Write-Host -ForegroundColor Green "Success" Write-Host # Generate admin consent URL $adminConsentUrl = "https://login.microsoftonline.com/" + $context.TenantId + "/adminconsent?client_id=" ` + $appRegistration.AppId Write-Host -ForeGroundColor Yellow "Please go to the following URL in your browser to provide admin consent" Write-Host $adminConsentUrl Write-Host # Generate Connect-MgGraph command $connectGraph = "Connect-MgGraph -ClientId """ + $appRegistration.AppId + """ -TenantId """` + $context.TenantId + """ -CertificateName """ + $cert.SubjectName.Name + """" Write-Host -ForeGroundColor Cyan "After providing admin consent, you can use the following values with Connect-MgGraph for app-only:" Write-Host $connectGraph if ($StayConnected -eq $false) { Disconnect-MgGraph Write-Host "Disconnected from Microsoft Graph" } else { Write-Host Write-Host -ForegroundColor Yellow "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph" } |
And then run it with the following command
|
1 |
.\RegisterAppOnly.ps1 -AppName "Graph PowerShell Script" -CertPath "PATH_TO_PUBLIC_KEY_FILE" |
But there is also limitations
There are limitations that currently exist in Microsoft Graph PowerShell either by design or due to some functionality that is yet to be built in.
- There is not yet an equivalent of -SearchString for Get-AzureADUser, Get-AzureADGroup commands. Use -Filter instead. For example,
Get-MgUser -Filter "DisplayName eq 'Lee Gu'"returns the user whose display name is equal to the specified string. - Search does not yet work for any Azure AD commands.
- You need to use hash tables to pass nested parameters. Here is a sample of Nested parameters.
- Pro-tip: Use the Microsoft Graph PowerShell ConsistencyLevel parameter. It lets you do $count! This is best used for read-only scenarios and you need to be more careful when making changes. To learn more about the ConsistencyLevel parameter see Advanced query parameters.
Migration FAQ
Graph Explorer
Microsoft has Graph explorer, it will help to find out the commands to use but see the permissions that a certain command will need to run.
How to find commands from Graph explorer
When you open Graph explorer you aren’t logged in and the commands need an consent to run.
You can use the samples to see how Graph works.
Or you can just login with your account and consent for organizational access
Once you have consented, you can access the content. There is also an option to use Beta API’s.
In the main page you see the different methods you can use.
HTTP methods
Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.
| Method | Description |
|---|---|
| GET | Read data from a resource. |
| POST | Create a new resource, or perform an action. |
| PATCH | Update a resource with new values. |
| PUT | Replace a resource with a new one. |
| DELETE | Remove a resource. |
- For the CRUD methods
GETandDELETE, no request body is required. - The
POST,PATCH, andPUTmethods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.
API versions
Microsoft Graph currently supports two versions: v1.0 and beta.
v1.0includes generally available APIs. Use the v1.0 version for all production apps.betaincludes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.
Running a query
If you run a query against applications, you will see the equivalent PowerShell command under Code snippets and PowerShell.
And you will also find out that consent is needed and you can consent from Modify permissions tab
You can also see your access token from Access token, it will open jwt.ms and you can see the header and claims in the token.
And this is what it look like, there a lot of info you don’t want to display to all
And in the Claims section you will find the explanation for different claim types collected.
Using Postman
Or you can use Postman for the job. Postman has a web interface and a downloadable version. The downloadable version will allow you to save your work to a workspace and it’s free.
Final words
There is different modules currently in the market for Azure AD management.
| Module | Description |
|---|---|
| AzureAD | Azure Active Directory PowerShell for Graph |
| MSOnline | MSOnline PowerShell |
| AzureADPreview | Azure Active Directory V2 Preview Module |
| Microsoft Graph PowerShell | Microsoft Graph PowerShell module |
And Microsoft will also retire Azure AD PowerShell in June 2022 (June was the end of line for ADAL also)
“In June 2020, we announced the retirement of Azure AD Graph API in favor of the Microsoft Graph API, which provides all the functionality of Azure AD Graph along with new functionality. As a result, all applications calling the Azure AD Graph API would receive an error message from the endpoint after the original proposed retirement date of June 30, 2022. Azure AD PowerShell is one of the applications that utilizes the Azure AD Graph API.
Azure AD PowerShell will continue to function after June 2022 to allow users more time to migrate to Microsoft Graph PowerShell. Customers can migrate to Microsoft Graph PowerShell with a phased shutdown of the Azure AD Graph endpoint. We encourage you to migrate to Microsoft Graph PowerShell.”
So better get prepared for both, right?
RSS - Posts