Hey folks – Eric Woodruff, Customer Engineer here, looking to share some knowledge and notes from the field regarding migration from AD FS to Azure AD. While each organization is unique, we certainly see patterns, and want to help demystify some common blockers to build your own confidence in moving to cloud-native authorization.
The common blockers for migrations can look like:
- We don’t know where to start
- We don’t know how to analyze things
- We don’t have a strong grasp on claim rules
- We are worried about breaking something
These are all valid concerns. Prior to my role at Microsoft, I was always somewhat mystified by the black box characteristics of AD FS. There is a lot of perception around AD FS migrations that make them feel more challenging than they are, so let’s break them down and dig into things.
We don’t know where to start
Not knowing where to start usually stems from either one or a combination of organizational or technical factors. Technically not knowing where to start usually is struggling to wrap your arms around existing Relying Party Trusts (RPT’s, also known as Service Providers (SP’s) in Azure AD). We’ll cover that under We don’t know how to analyze things.
From an organizational perspective, not knowing where to start usually requires answering some business questions around your existing applications, and then using that information to classify them. We focus on three areas: Business Criticality, Usage, and Expected Lifespan, using a scale from 0-10, with 0 having the lowest impact, and 10 having the highest.
We then take this data and apply it to our friend, the Application Matrix of Business Priority
We can use the above data to effectively determine where within this matrix our applications sit and use that to build out the overall priority of the application to the organization. For full details on this entire process, check out our documentation available here:
Migrate application authentication to Azure Active Directory | Microsoft Docs
Field Note #1
Many times, organizations will want to try and tackle the most complex, highest priority applications first, but it can be hard to gain momentum from that angle of attack. For organizations with less experience in this area, it may be most advantageous to start with the lowest priority applications, to use them to build momentum and gain knowledge. It may also help to cut things up into waves/phases and be open to having some flexibility in re-defining these the further you dig into migrations.
Field Note #2
Working in parallel can also help build momentum, trying to stay away from an extremely serialized process. While the first few migrations are a good learning experience and help build processes, as you start to generate traction, you’ll notice that you have potential to accomplish many migrations in a short timeframe.
Field Note #3
You’ll need to bring the application owners onboard in this process, as each change is going to require changes to the application. At the same time, don’t try to boil the ocean – it can be easy to say this is a great time to re-architect the entire business process around an application, and months later that application still sits in AD FS. One thing of beauty about Azure AD is that if you intend on wrapping Identity Governance around an application, it’s easy to backfill those processes onto existing applications, and since you currently can’t apply those things to AD FS, you are no worse off just migrating the application first.
Field Note #4
This however is a time to straighten out security, and align these things between your Identity team, Security team, and application owners. You may try to fit some security model you were using in AD FS into Azure AD – say using traditional network-based access controls, to find that the security team is really looking to go with a Zero Trust model and require device compliance for any application tied to Azure AD. Not having an organizational wide defined security model can stall migrations.
Field Note #5
Whenever available work within a dev/test/staging environment first. If you don’t have one available, some vendors such as Salesforce and ServiceNow offer developer environments that you can test the migration strategy in. While it varies, you’ll also be surprised as to how many SaaS application vendors that fill industry specific needs will stand up a temporary environment for an organization to test Azure AD integrations with, again to build that knowledge before a production migration.
We don’t know how to analyze things
When it comes to analyzing your existing RPT’s, it can be hard to easily understand the usage, which helps inform you about business priority, as well as understand and analyze the claims.
Analyzing Usage
For customers with licensing for Azure AD P1 or higher, Azure AD Connect Health really helps open the mysteries behind AD FS, and even if you have no intentions of AD FS migrations, Azure AD Connect Health is something that every organization that can run it, should.
The core data points you can gain from Azure AD Connect Health are unique user count information, as well as token requests on a per application basis. You will now easily know the shape and size of your application audience, as well as determine application low points of usage, which can be useful for finding that time when a change can be scheduled.
More information on how to leverage Azure AD Connect Health for gathering this information can be found here:
Using Azure AD Connect Health with AD FS | Microsoft Docs
Analyzing Claims
For claims analysis, we have two routes available, and to our benefit we can use both routes if needed.
AD FS Application Activity
The AD FS Application Activity report provides details on every active RPT and highlights any potential migration issues. Within this report you can drill into each application and view both the things that pass all tests, as well as anything that may need attention. You also can view the existing claim rules, which becomes important as you’ll need to ensure that you replicate your claims within Azure AD.
Note that this requires Azure AD Connect Health to be configured for AD FS to gather this data.
Full details on how to use this report can be found here:
Use the activity report to move AD FS apps to Azure Active Directory | Microsoft Docs
AD FS to Azure AD App Migration Tool
For organizations that do not have P1 licensing or have several applications and want to work with and analyzing their claims within a spreadsheet, the migration tool is your place to go.
The data provided by this tool is very similar to the activity report – you’ll get details on all your claims, as well as analysis and highlights of any warnings or potential blockers for application migration. To build this report, you run the provided PowerShell module against your primary AD FS farm server – the process is read only and simply gathers farm information into a series of CSV files. You’ll then want to open the provided Excel Dashboard template and refresh it to pull in the data from the CSV files. At that point you are off to the analysis races.
Full information on how to run this report can be found here:
Deployment-Plans/ADFS to AzureAD App Migration at master · AzureAD/Deployment-Plans · GitHub
Field Note #6
If you are working with many applications, and a lot of the claims have warnings and/or you have many claim rules per application, you may find it easier to work within the application migration report. When working with customers we tend to leverage this report as it’s easier to search and manipulate the data within Excel, especially when analyzing claims.
Field Note #7
If you are finding that you are using the application migration report and don’t understand why a certain claim has a warning, go to the AD FS Application Activity Report in Azure AD, and look at the same RPT within there. The migration report may be somewhat lacking as to why a claim has a warning, but the application activity report can help surface some points of resolution to the warning.
We don’t have a strong grasp on claim rules
Even for those of us who work with this stuff all the time, it’s always a learning experience when dealing with claim rules. The great part of migrating to Azure AD is that the trepidation of claim rules vastly diminishes with how easy it is to build claims in Azure AD. But we must get there first and getting there involves understanding existing claim rules.
Claims can contain almost any user attribute in Azure AD. You’ll see that all claims will contain the required NameID (name identifier), which represents the unique user identity to the application. Common scenarios also include sending first name, last name, display name, employee ID, email address, roles, and group membership to the application.
In AD FS, we would commonly have a couple of Transform claim rules – One that gets attributes from Active Directory that we want to send as claims, and one that would determine what attribute would be the NameID, as well as specify the NameID format.
Where things can start to feel sticky is when you have rules that are using RegEx to manipulate data or build Authorization rules that would examine the network clients are coming from.
Dealing with Warnings or Errors
Regardless of which method of analysis you go with, it’s likely to have some warnings and blockers. While we do our best to look for known migratable patterns programmatically, there are times where the rule is just unique enough that it needs a set of human eyes on it to derive what we are really trying to accomplish.
Field Note #8
At first glance, a bunch of warnings can create the sense that this is not going to be easy. When we start to dissect and analyze their claim rules, we find repetition, so if we solve for one rule we solve for many applications. An example could be how an authorization rule was defined, that was checking for network location from the client – this may show a warning, and upon further inspection find that an existing conditional access policy will cover this. If the same rule is repeated in 75 applications, you’ve now solved 75 problems at once.
Claim Rules Cheat Sheet
|
AD FS Authorization Rules/Access Control Policies |
||
|
AD FS |
→ |
Azure AD |
|
Location-based rules |
→ |
Conditional Access Policies |
|
Group-based rules |
→ |
Group-based application assignment |
|
Attribute-based rules |
→ |
Dynamic groups, group-based application assignment |
|
Device trust rules |
→ |
Conditional Access Policies |
|
MFA Requirements |
→ |
Conditional Access Policies |
|
AD FS Issuance Transform Rules |
||
|
AD FS |
→ |
Azure AD |
|
Claim condition(s) |
→ |
Dynamic groups, claim conditions |
|
Regular Expressions – Attribute modification |
→ |
Claim transformations |
|
Regular Expressions – Attribute Evaluation |
→ |
Dynamic groups, claim conditions |
|
Add statement (constant) |
→ |
Dynamic groups, claim conditions with constant |
|
Group Membership |
→ |
Group claim |
|
Role Claims |
→ |
User/group application assignment with roles defined |
For further information on all the ways you can customize claims, check out these docs articles:
Customize app SAML token claims - Microsoft identity platform | Microsoft Docs
Provide optional claims to Azure AD apps - Microsoft identity platform | Microsoft Docs
Use Azure AD schema extension attributes in claims - Microsoft identity platform | Microsoft Docs
Add app roles and get them from a token - Microsoft identity platform | Microsoft Docs
Field Note #9
This can be a good time to re-connect with your application owners and review the claims that are being sent over – as applications and business processes evolve, you may find that you have some very heavy claim rules in place, and the application doesn’t even leverage these claims. If the application supports SCIM, even better to move from claims to instead send user and group information via SCIM, as this does not rely on the user authenticating to receive updates. If delegation is something you desire, assign the application owner Configuration Owner rights to that application, and let them configure both the application side and Azure AD side of things for their app (not recommended without upskilling them first).
Field Note #10
One of the most common claim differences between a net new application in Azure AD, and an application being migrated, is the NameID emitted with the sAMAccountName attribute instead of UserPrincipalName. During the migration if you are authorized to the application but receive a 401/403 error (the error will differ for each application), one of the first things to double-check is whether you are still emitting the NameID in the same format. Also note that some applications are case sensitive, in the case you had RegEx handling it in AD FS – Azure AD can easily normalize casing with ToLowercase/ToUppercase. If the application has JIT (just-in-time) user provisioning enabled, you may also see the unmatched user created in the application.
We are worried about breaking something
That feeling of dread before flipping the switches in an application, we’ve all been there. The pressure is heightened even more when the application does not support multiple identity providers. Ensuring that when you switch things over that authorization remains seamless for our end users is imperative.
As called out in Note #5 above, whenever a lower tier environment is available to test with first, use it. Work with the application owner to understand what changes need to be made on both sides, practice the skills in coordinating the change, and make sure you document it all so you can land that production migration with little disturbance.
Note that some SaaS application vendors require that you provide them your XML metadata and they must perform the change on their end, so if this is the case triage the migration with the application owner and the vendor support team.
Field Note #11
It may seem obvious, but make sure you have a rollback plan defined. This should include documenting how the application is currently configured, being detailed, as applications can vary regarding how intuitive it may feel to make these changes. Along with that, do not disable the RPT in AD FS until you’ve verified the migration was successful. It won’t be providing valid access tokens anymore so you don’t have to worry about the application accepting them, but if you are using IdP initiated sign-on, you can also always disable the RPT so it doesn’t show up as an option for end users. If making the change off hours, let the application run through its normal business cycle after testing the migration if you are feeling more risk adverse before deleting the RPT.
Take a moment to pat yourself on the back
Now that you’ve migrated all your applications off AD FS, not only do you have one less system to worry about patching, architecting resiliency for, and monitoring, but you’ve also helped move your organization forward, enabling you to take full advantage of the entire stack of identity security features within Azure Active Directory.
Microsoft
