AD FS to Azure AD application migration playbook for developers

This set of ASP.NET code samples and accompanying tutorials will help you learn how to safely and securely migrate your applications integrated with Active Directory Federation Services (AD FS) to Azure Active Directory (Azure AD). This tutorial is focused towards developers who not only need to learn configuring apps on both AD FS and Azure AD, but also become aware and confident of changes their code base will require in this process.

These code samples are a companion to Moving application authentication from AD FS to Azure AD available on the Microsoft Docs site.

The folders in this repo are arranged as chapters, each with a README and sample code for a scenario. The chapters cover the most common types of authentication utilized by applications integrated with AD FS today, and we hope they let you learn and gain valuable experience before undertaking an app migration initiative for your applications currently running in production.


Migration steps

By following the tutorial chapters in this code sample, you progress through the following scenarios:

  • We start by integrating the provided sample web application with an AD FS instance. This web app uses the SAML protocol for it authentication setup.
  • Next, we'd migrate this application to an Azure AD tenant.
  • Finally, we also provide instructions as how to change the authentication protocol from SAML to OAuth 2.0 and OpenID Connect. This change allows you to reap the benefits of accessing rich APIs like Microsoft Graph and the Azure REST API amongst others.

We have also covered the following topics in some detail as they might play a big part in your app migration work:


Chapter 1: Integrate sample app with AD FS

1.1 Integrate app with AD FS Integrate the provided ASP.NET MVC web application with an AD FS instance.
1.2 Set up Azure AD Connect A brief look at the Azure AD Connect configuration that synchronizes on=premise data to an Azure AD tenant.
1.3 Directory Extensions Migrate Directory Extensions from on-prem Active Directory to your Azure AD tenant .

Chapter 2: Migrate the working web app from AD FS to Azure AD

2.1 Integrate app with Azure AD Migrating the SAML ASP.NET MVC web app from AD FS to Azure AD.
2.2 Using Security groups Using on-premise Active Directory security groups in applications migrated to an Azure AD tenant.
2.3 Convert from SAML to OIDC Migrate a SAML ASP.NET application to use OAuth 2.0 and OpenID Connect.

For information about Integrated Windows Authentication (IWA), see Azure-Samples/active-directory-dotnet-iwa-v2.

We'd love your feedback!

Were we successful in addressing your learning objective? Do consider taking a moment to share your experience with us.

We're always listening, and if you want to get in touch with you directly, send an email to

Community Help and Support

Use Stack Overflow to get support from the community.

If you find a bug in the sample, raise the issue on GitHub Issues.

To provide feedback on or suggest features for Azure Active Directory, visit User Voice.


This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.