services	platforms	author
active-directory	dotnet	dstrockis

Integrating Azure AD into an ASP.NET Core web app

This sample shows how to build a .Net MVC web application that uses OpenID Connect to sign-in users from a single Azure Active Directory tenant, using the ASP.Net Core OpenID Connect middleware.

For more information about how the protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.

This sample has been updated to ASP.NET Core 1.0. Looking for previous versions of this code sample? Check out the tags on the releases GitHub page.

How To Run This Sample

Getting started is simple! To run this sample you will need:

Install .NET Core for Windows by following the instructions at dot.net/core, which will include Visual Studio 2015 Update 3.
An Internet connection
An Azure Active Directory (Azure AD) tenant. For more information on how to get an Azure AD tenant, please see How to get an Azure AD tenant
A user account in your Azure AD tenant. 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.

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/active-directory-dotnet-webapp-openidconnect-aspnetcore.git

Step 2: Register the sample with your Azure Active Directory tenant

Sign in to the Azure portal.
On the top bar, click on your account and under the Directory list, choose the Active Directory tenant where you wish to register your application.
Click on More Services in the left hand nav, and choose Azure Active Directory.
Click on App registrations and choose Add.
Enter a friendly name for the application, for example 'WebApp-OpenIDConnect-DotNet' and select 'Web Application and/or Web API' as the Application Type. For the sign-on URL, enter the redirect URI for the sample, which is by default https://localhost:44353/signin-oidc. Click on Create to create the application.
While still in the Azure portal, choose your application, click on Settings and choose Properties.
Find the Application ID value and copy it to the clipboard.
In the same page, change the logoutUrl property to https://localhost:44353/Account/EndSession. This is the default single sign out URL for this sample.
For the App ID URI, enter https://<your_tenant_name>/WebApp-OpenIDConnect-DotNet, replacing <your_tenant_name> with the name of your Azure AD tenant.

Step 3: Configure the sample to use your Azure Active Directory tenant

Open the solution in VS Code.
Copy the config.json file to config.user.json and edit config.user.json.
Find the Tenant property and replace the value with your AAD tenant name.
Find the ClientId and replace the value with the Application ID from the Azure portal.
If you changed the base URL of the sample, find the app key ida:PostLogoutRedirectUri and replace the value with the new base URL of the sample.

Step 4: Run the sample

Clean the solution, rebuild the solution, and run it - the config.user.json file should be in the output directory.

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.

About The Code

This sample shows how to use the OpenID Connect ASP.Net Core middleware to sign-in users from a single Azure AD tenant. The middleware is initialized in the Startup.cs file, by passing it the Client ID 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 OpenID Connect sign-in responses by validating the signature and issuer in an incoming JWT, extracting the user's claims, and putting them on ClaimsPrincipal.Current.
Integrating with the session cookie ASP.Net Core middleware to establish a session for the user.

You can trigger the middleware to send an OpenID Connect sign-in request by decorating a class or method with the [Authorize] attribute, or by issuing a challenge,

await HttpContext.Authentication.ChallengeAsync(OpenIdConnectDefaults.AuthenticationScheme, new AuthenticationProperties { RedirectUri = "/" });

Similarly you can send a signout request,

await HttpContext.Authentication.SignOutAsync(OpenIdConnectDefaults.AuthenticationScheme);
await HttpContext.Authentication.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

When a user is signed out, they will be redirected to the Post_Logout_Redirect_Uri specified when the OpenID Connect middleware is initialized.

All of the middleware in this project is created as a part of the open source Asp.Net Security project.

joemcbride / azure-ad