This sample shows how to build an MVC web application that uses Azure AD for sign-in using the OpenID Connect protocol and provides Single Sign Out across web apps.
For more information about how the OpenID Connect protocol works in this scenario, see the OpenID Connect Session Management Specfication.
About The Sample
If you would like to get started immediately, skip this section and jump to How To Run The Sample.
This MVC 5 web application allows the user to sign in to the application with an AAD account. Once signed in, if the user signs out of another application that has been authenticated using the same AAD tenant, this application will automatically sign the user out and display a message notifying the user. Similarly, when the user signs out of this application, they will be signed out of any other applications that use the same AAD tenant and that have implemented Single Sign Out.
This sample will demonstrate the Single Sign Out capability by using the Azure Management Portal as a second application that uses AAD for authentication.
How To Run The Sample
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://wwww.windowsazure.com. All of the Azure AD features used by this sample are available free of charge.
Step 1: Clone or download this repository
From your shell or command line:
git clone https://github.com/Azure-Samples/active-directory-dotnet-web-single-sign-out.git
Step 2: Create a user account in your Azure Active Directory tenant
If you already have a user account with Global Administrator rights 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 so now, and ensure it has the Global Administrator Directory Role. 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.
Step 3: Register the sample with your Azure Active Directory tenant
- Sign in to the Azure management portal.
- Click on Active Directory in the left hand nav.
- Click the default directory tenant in which you created a Global Administrator user. You will need to register your application in this tenant so that you can log into both the application and the portal with your Global Administrator user.
- 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 "SingleSignOutWebApp", 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:44308/. NOTE: It is important, due to the way Azure AD matches URLs, to ensure there is a trailing slash on the end of this URL. If you don't include the trailing slash, you will receive an error when the application attempts to redeem an authorization code.
- For the App ID URI, enter
<your_tenant_name>with the name of your Azure AD tenant and
<your_application_name>with the name you chose above. Click OK to complete the registration.
- While still in the Azure portal, click the Configure tab of your application.
- Find the Client ID value and copy it aside, you will need this later when configuring your application.
- Create a new key for the application. Save the configuration so you can view the key value. Save this aside for when you configure the project in Visual Studio.
- In the Permissions to Other Applications configuration section, ensure that "Enable sign-on and read user's profiles" is selected under "Delegated permissions." Save the configuration.
Step 4: Configure the sample to use your Azure AD tenant
- Open the solution in Visual Studio 2013.
- Open the
- Find the app key
ida:Tenantand replace the value with your AAD tenant name, i.e. "defaulttenant.onmicrosoft.com".
- Find the app key
ida:ClientIdand replace the value with the Client ID for the application from the Azure portal.
- Find the app key
ida:AppKeyand replace the value with the key for the application from the Azure portal.
- If you changed the base URL of the TodoListWebApp sample, find the app key
ida:PostLogoutRedirectUriand replace the value with the new base URL of the sample.
Step 5: Run the sample
Clean the solution, rebuild the solution, and run it. NOTE: Be sure not to run the sample in Internet Explorer, or you will get unexpected behavior. Sign into the application by clicking one of the tabs, such as "About." Be sure to sign in with a user that can also sign in to the Azure Management Portal. Once signed in, sign in to the Azure Management Portal as well. Try signing out of either application; you will be signed out of the other in a matter of seconds.
For the most part, you can simply cut and paste the code from this sample into your OWIN application in order to provide Single Sign Out functionality. But for a deeper understanding of the code and the OpenID Connect Session Managment protocol, take a look at the following five files:
This partial view is where the majority of the action takes place. In order to know when to perform Single Sign Out, the application needs a way to check the status of the user's session with Azure AD. This could be achieved by polling AAD periodically, but would incur more network cost than is necessary. Instead, the application will periodically check the value of a cookie that is set by AAD on login, as directed by the OpenID Connect Session Management specfication. Only if the value of the cookie has changed will the application then submit a request to AAD to check the status of the user's session with AAD. AAD provides a "CheckSessionIframe" to peform this check for you that is used in this sample.
AccountController.cs, there are two actions to note. The
The other action to note is
SingleSignOut, which actually signs the user out of the application and displays a message telling the user that a Single Sign Out has occurred.
Presents the Single Sign Out occurred message to the user.
OpenIDConnectAuthenticationNotifications callbacks are used to process the authorization request result from AAD. If the request fails, it can be interpreted as the user needing to reauthenticate with AAD (and that the user should be signed out of the application). OWIN triggers the
AuthenticationFailed callback, which signs the user out using the
If the authorization request succeeds, there are two possibilities. First, that the user is still authenticated with AAD and no Single Sign Out is necessary. Second, that the user is authenticated with AAD but as a different user than before. In this case, a Single Sign Out is necessary. In either case, OWIN triggers the
AuthorizationCodeRecieved callback, which handles each case individually.