Migrating a .NET MVC application using SAML protocol from AD FS to Azure Active Directory

Scenario

Here we migrate the provided ASP.NET web application that uses the SAML protocol to authenticate users and integrated with AD FS, to your Azure Active Directory tenant.

About the sample

In the previous chapter 1-1 we integrated an ASP.NET web application with an AD FS instance.

After the migration, this sample will use the App Federation Metadata Url from the Azure Active Directory tenant, for authentication.

Prerequisites

• Visual Studio
• .NET Framework 4.7.2
• An AD FS environment
• An Azure Active Directory (Azure AD) tenant. For more information on how to get an Azure Active Directory tenant, see How to get an Azure Active Directory tenant

Migrate the SAML application from ADFSto Azure Active Directory

Register the SAML application in Azure Active Directory

1. Sign in to the Azure portal using a tenant admin account.
2. Navigate to the Microsoft identity platform for developers Enterprise applications page.
3. Select New registration.
4. Select Non gallery app.
5. Choose a name for the application, for instance WebApp_SAML and select Add on the bottom.
6. Under the Manage section, select Single sign-on.
7. Select SAML and the Set up Single Sign-On with SAML page will appear.

Basic SAML configuration for your app

1. To edit the basic SAML configuration options, select the Edit icon (a pencil) in the upper-right corner of the Basic SAML Configuration section.
2. Set Identifier (Entity ID) with an unique URL that follows the pattern, http://{your-appName}.{your-domain}.com. For instance: http://webappsaml.contoso.com. Copy the Entity ID value to be used in later steps.
3. Set Reply URL with the URL that Azure AD will reply after the authentication. In this sample we are using https://localhost:44347/.
4. [Optional] Set the optional parameters if they are required in your scenario. The guide Moving application authentication from Active Directory Federation Services to Azure Active Directory is an excellent resource to learn about the various available options.

Learn more about configuring SAML-based single sign-on in Azure Active Directory.

Configure user attributes and claims

By default, the claims givenname, surname, emailaddress and name will be already configured for the application.

The web application registered on chapter 1 also uses Employee-ID claim, so we need to configure that as well. If you added extra claims on the AD FS registration of the web application, follow the steps below to register all the additional claims that should be returned by the Azure AD SAML application:

1. In the User Attributes and Claims section, select the Edit icon (a pencil) in the upper-right corner.
2. Add additional claims that you would like to use in the web app project.
3. To add a claim, select Add new claim at the top of the page.
4. Enter the Name, for instance employeeID.
5. Enter the Namespace if desired, for instance http://schemas.xmlsoap.org/ws/2005/05/identity/claims.
6. Select the appropriate Source that contains the claim value. For Employee-ID, the source is Attribute.
7. Select the appropriate Source Attribute or Transformation, depending on what you selected on the previous step. For Employee-ID, select user.employeeid.
8. Select Save. The new claim appears in the table.

SAML Signing Certificate

1. In the SAML Signing Certificate section, if you don't have a certificate yet, select the Edit icon (a pencil) in the upper-right corner.
2. Select New Certificate and then Save.
3. Close the blade, refresh the page and copy the value for App Federation Metadata Url field. We will use it on the .NET MVC project.

Customize Claims Emitted in Tokens

In Azure AD, it is possible to customize claims emitted in tokens for specific applications. Check the permitted values that can be emitted and SAML exceptions and restrictions.

In order to customize the claims emitted in tokens, you have to create a claim mapping policy and assign it to the desired application. Learn how to create and assign a claim mapping policy.

Configure the .NET MVC project (WebApp_SAML) to use your app registration

Open the project WebApp_SAML in your IDE (like Visual Studio) to configure the code.

1. Open the Web.config file.
2. Replace the value for ida:ADFSMetadata with the link that you copied from App Federation Metadata Url field.
3. Replace the value for ida:Wtrealm with the value that you set for Identifier (Entity ID). For instance, http://webappsaml.contoso.com.
4. Save, clean and build the solution.

Test the application

Clean and build the solution, then run the WebApp_SAML application and sign-in using an on-premise user (who already got synced) or a user from your Azure AD tenant only.

All the claims configured on the User Attributes and Claims steps will be listed in the page, in case the signed-in user has a value set for it.

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

Consider taking a moment to share your experience with us.

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 aadappfeedback@microsoft.com.

Next Step

• Using on-prem Active Directory security groups in an Azure AD application

Useful resources

• Moving application authentication from AD FS to Azure Active Directory
• AD FS to Azure AD App Migration Tool
• Configure SAML-based single sign-on to non-gallery applications