services | platforms | author |
---|---|---|
active-directory |
dotnet |
jmprieur |
This sample shows how to build a .NET MVC web app that uses OpenID Connect to sign-in users from a single Azure Active Directory (Azure AD) tenant using the ASP.NET Core OpenID Connect middleware.
For more information on how the protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.
This sample is for ASP.NET Core 2.0
- if you are interested in ASP.NET Core 1.1, please look at branch aspnet_core_1_1.
- if you are interested in ASP.NET Core 2.1, please look at active-directory-aspnetcore-webapp-openidconnect-v2 (branch aspnetcore2-2) which also features the Azure AD v2.0 endpoint (which can now be used with v1.0 and v2.0 applications)
To run this sample:
- Install .NET Core for Windows by following the instructions at .NET and C# - Get Started in 10 Minutes. In addition to developing on Windows, you can develop on Linux, Mac, or Docker.
- An Azure AD tenant. For more information on how to obtain an Azure AD tenant, see How to get an Azure AD tenant.
-
Sign in to the Azure portal.
-
On the top bar, select your account. Under the DIRECTORY list, choose the Active Directory tenant where you wish to register your app. If there isn't a DIRECTORY list in the drop down menu, skip this step, as you only have a single tenant associated with your Azure account. For more information, see How to get an Azure Active Directory tenant.
-
In the left navigation sidebar, select Azure Active Directory. If you don't see Azure Active Directory in the list, select More Services and choose Azure Active Directory in the SECURITY + IDENTITY section of the service list.
-
From the sidebar, select App registrations.
-
Select New application registration and provide a friendly name for the app, app type, and sign-on URL:
- Name: WebApp-OpenIDConnect-DotNet
- Application Type: Web app / API
- Sign-on URL:
http://localhost:5000/signin-oidc
Select Create to register the app.
-
On the Properties blade, set the Logout URL to
http://localhost:5000/signout-oidc
and select Save. -
From the Azure portal, note the following information:
The Tenant domain: See the App ID URI base URL. For example:
contoso.onmicrosoft.com
The Tenant ID: See the Endpoints blade. Record the GUID from any of the endpoint URLs. For example:
da41245a5-11b3-996c-00a8-4d99re19f292
The Application ID (Client ID): See the Properties blade. For example:
ba74781c2-53c2-442a-97c2-3d60re42f403
Note
The base address in the Sign-on URL and Logout URL settings is http://localhost:5000
. This localhost address allows the sample app to run insecurely from your local system. Port 5000 is the default port for the Kestrel server. Update these URLs if you configure the app for production use (for example, https://www.contoso.com/signin-oidc
and https://www.contoso.com/signout-oidc
).
This sample was created from the 2.0 dotnet new mvc template with SingleOrg
authentication. You can create the sample from the command line or clone/download this repository:
-
To create the sample from the command line, execute the following command:
dotnet new mvc --auth SingleOrg --client-id <CLIENT_ID_(APP_ID)> --tenant-id <TENANT_ID> --domain <TENANT_DOMAIN>
Use the values that you recorded from the Azure portal for <CLIENT_ID_(APP_ID)>, <TENANT_ID>, and <TENANT_DOMAIN>.
-
To clone/download this sample, execute the following command from your shell or command line:
git clone https://github.com/Azure-Samples/active-directory-dotnet-webapp-openidconnect-aspnetcore.git
In the *appsettings.json file, provide values for the
Domain
,TenantId
, andClientID
that you recorded earlier from the Azure portal.
Build the solution and run it.
Make a request to the app. The app immediately attempts to authenticate you via Azure AD. Sign in with the username and password of a user account that is in your Azure AD tenant. You can also use your tenant's Global Administrator account. If you wish to create a user in the tenant, select Add a user from the Quick tasks panel. The Quick tasks panel is found on the Azure AD tenant's blade in the portal.
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 app and the URL of the Azure AD tenant where the app is registered, which is read from the appsettings.json
file. The middleware 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 the claims in
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 (see the AccountController.cs
file):
return Challenge(
new AuthenticationProperties { RedirectUri = redirectUrl },
OpenIdConnectDefaults.AuthenticationScheme);
Similarly, you can send a signout request:
return SignOut(
new AuthenticationProperties { RedirectUri = callbackUrl },
CookieAuthenticationDefaults.AuthenticationScheme,
OpenIdConnectDefaults.AuthenticationScheme);
The middleware in this project is created as a part of the open source ASP.NET Security project.
- Why is the ClientSecret in Extensions/AzureAdOptions.cs not used in this sample whereas it's used in other samples like dotnet-webapp-webapi-openidconnect-aspnetcore. See discussion in question #34