This sample shows how to build a .Net MVC web application that uses WS-Federation to sign-in users from a single Azure Active Directory tenant, using the ASP.Net WS-Federation OWIN middleware.
The use of WS-Federation is appropriate when you want to maintain a single app codebase that can be deployed either against Azure AD or an on-premises provider such as an Active Directory Federation Services (ADFS) instance. For scenarios in which the app targets exclusively Azure AD (or an OpenID Connect compliant provider) please refer to the WebApp-OpenIdConnect-DotNet sample.
For more information about how the protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.
Getting started is simple! To run this sample you will need:
- Visual Studio 2013
- An Internet connection
- An Azure subscription (a free trial is sufficient)
Every Azure subscription has an associated Azure Active Directory tenant. If you don't already have an Azure subscription, you can get a free subscription by signing up at http://www.windowsazure.com. All of the Azure AD features used by this sample are available free of charge.
From your shell or command line:
git clone https://github.com/AzureADSamples/WebApp-WSFederation-DotNet.git
If you already have a user account in your Azure Active Directory tenant, you can skip to the next step. This sample will not work with a Microsoft account, so if you signed in to the Azure portal with a Microsoft account and have never created a user account in your directory before, you need to do that now. If you create an account and want to use it to sign-in to the Azure portal, don't forget to add the user account as a co-administrator of your Azure subscription.
-
Sign in to the Azure management portal.
-
Click on Active Directory in the left hand nav.
-
Click the directory tenant where you wish to register the sample application.
-
Click the Applications tab.
-
In the drawer, click Add.
-
Click "Add an application my organization is developing".
-
Enter a friendly name for the application, for example "WebApp-WSFederation-DotNet", select "Web Application and/or Web API", and click next.
-
For the sign-on URL, enter the base URL for the sample, which is by default
https://localhost:44320
. -
For the App ID URI, enter
https://<your_tenant_name>/WebApp-WSFederation-DotNet
, replacing<your_tenant_name>
with the name of your Azure AD tenant. Make sure to remember this value, as you will need it later on when configuring your app in Visual Studio. -
While still in the Azure portal, click the Configure tab of your application.
-
Find the Client ID value and copy it to the clipboard.
- Open the solution in Visual Studio 2013.
- Open the
web.config
file. - Find the app key
ida:Tenant
and replace the value with your AAD tenant name. - Find the app key
ida:Wtrealm
and replace the value with the App ID URI from the Azure portal.
You know what to do!
Click the sign-in link on the homepage of the application to sign-in. On the Azure AD sign-in page, enter the name and password of a user account that is in your Azure AD tenant.
Coming soon.
This sample shows how to use the WS-Federation ASP.Net OWIN middleware to sign-in users from a single Azure AD tenant. The middleware is initialized in the Startup.Auth.cs
file, by passing it the App ID URI of the application and the URL of the Azure AD tenant where the application is registered. The middleware then takes care of:
- Downloading the Azure AD metadata, finding the signing keys, and finding the issuer name for the tenant.
- Processing WS-Federation sign-in responses by validating the signature and issuer in an incoming SAML token, extracting the user's claims, and putting them on ClaimsPrincipal.Current.
- Integrating with the session cookie ASP.Net OWIN middleware to establish a session for the user.
You can trigger the middleware to send a WS-Federation sign-in request by decorating a class or method with the [Authorize]
attribute, or by issuing a challenge,
HttpContext.GetOwinContext().Authentication.Challenge(
new AuthenticationProperties { RedirectUri = "/" },
WSFederationAuthenticationDefaults.AuthenticationType);
Similarly you can send a signout request,
HttpContext.GetOwinContext().Authentication.SignOut(
WSFederationAuthenticationDefaults.AuthenticationType,
CookieAuthenticationDefaults.AuthenticationType);
All of the OWIN middleware in this project is created as a part of the open source Katana project. You can read more about OWIN here.
- In Visual Studio 2013, create a new ASP.Net MVC web application with Authentication set to No Authentication.
- Set SSL Enabled to be True. Note the SSL URL.
- In the project properties, Web properties, set the Project Url to be the SSL URL.
- Add the following ASP.Net OWIN middleware NuGets: Microsoft.IdentityModel.Protocol.Extensions, System.IdentityModel.Tokens.Jwt, Microsoft.Owin.Security.WSFederation, Microsoft.Owin.Security.Cookies, Microsoft.Owin.Host.SystemWeb.
- In the
App_Start
folder, create a classStartup.Auth.cs
. You will need to remove.App_Start
from the namespace name. Replace the code for theStartup
class with the code from the same file of the sample app. Be sure to take the whole class definition! The definition changes frompublic class Startup
topublic partial class Startup
. - In
Startup.Auth.cs
resolve missing references by addingusing
statements forOwin
,Microsoft.Owin.Security
,Microsoft.Owin.Security.Cookies
,Microsoft.Owin.Security.WSFederation
,System.Configuration
, andSystem.Globalization
. - Right-click on the project, select Add, select "OWIN Startup class", and name the class "Startup". If "OWIN Startup Class" doesn't appear in the menu, instead select "Class", and in the search box enter "OWIN". "OWIN Startup class" will appear as a selection; select it, and name the class
Startup.cs
. - In
Startup.cs
, replace the code for theStartup
class with the code from the same file of the sample app. Again, note the definition changes frompublic class Startup
topublic partial class Startup
. - In the
Views
-->Shared
folder, create a new partial view_LoginPartial.cshtml
. Replace the contents of the file with the contents of the file of same name from the sample. - In the
Views
-->Shared
folder, replace the contents of_Layout.cshtml
with the contents of the file of same name from the sample. Effectively, all this will do is add a single line,@Html.Partial("_LoginPartial")
, that lights up the previously added_LoginPartial
view. - Create a new empty controller called
AccountController
. Replace the implementation with the contents of the file of same name from the sample. - If you want the user to be required to sign-in before they can see any page of the app, then in the
HomeController
, decorate theHomeController
class with the[Authorize]
attribute. If you leave this out, the user will be able to see the home page of the app without having to sign-in first, and can click the sign-in link on that page to get signed in. - Almost done! Follow the steps in "Running This Sample" to register the application in your AAD tenant.
- In
web.config
, in<appSettings>
, create keys forida:Wtrealm
,ida:AADInstance
, andida:Tenant
and set the values accordingly. For the public Azure AD, the value ofida:AADInstance
ishttps://login.windows.net
.