From 5b9479b99954fc717083b3c3ceca3b9274f17a3e Mon Sep 17 00:00:00 2001 From: Galip Tolga Erdem Date: Sun, 5 Apr 2020 22:55:56 +0300 Subject: [PATCH 1/5] custom signin manager documentation update --- docs/en/How-To/Customize-SignIn-Manager.md | 93 ++++++++++++---------- 1 file changed, 53 insertions(+), 40 deletions(-) diff --git a/docs/en/How-To/Customize-SignIn-Manager.md b/docs/en/How-To/Customize-SignIn-Manager.md index 8c9733a6af..f8108c1910 100644 --- a/docs/en/How-To/Customize-SignIn-Manager.md +++ b/docs/en/How-To/Customize-SignIn-Manager.md @@ -1,84 +1,97 @@ -# Customize the SignInManager +# How to Customize the SignIn Manager for ABP Applications -## Introduction +After creating a new application using the [application startup template](../Startup-Templates/Application.md), you may want extend or change the default behavior of the SignIn Manager for your authentication and registration flow needs. ABP [Account Module](../Modules/Account) uses default [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs). To write your Custom SignIn Manager, you need to extend this class and register to the DI container. -ABP Framework uses Microsoft Identity underneath hence supports customization as much as Microsoft Identity does. +This document explains how to customize the SignIn Manager for your own application. -## Sample Code +## Create a CustomSignInManager -https://github.com/abpframework/abp-samples/blob/master/aspnet-core/BookStore-AzureAD/src/Acme.BookStore.Web/CustomSignInManager.cs +Create a new class inheriting the [SignInMager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs) of Microsoft Identity package. -## Creating CustomSignInManager - -To create your own custom SignIn Manager, you need to inherit `SignInManager`. - -````xml -public class CustomSignInManager : SignInManager +````csharp +public class CustomSignInManager : Microsoft.AspNetCore.Identity.SignInManager { - public CustomSigninManager( - UserManager userManager, - IHttpContextAccessor contextAccessor, - IUserClaimsPrincipalFactory claimsFactory, - IOptions optionsAccessor, - ILogger> logger, - IAuthenticationSchemeProvider schemes, - IUserConfirmation confirmation) - : base(userManager, contextAccessor, claimsFactory, optionsAccessor, logger, schemes, confirmation) - { - } + public CustomSignInManager( + Microsoft.AspNetCore.Identity.UserManager userManager, + Microsoft.AspNetCore.Http.IHttpContextAccessor contextAccessor, + Microsoft.AspNetCore.Identity.IUserClaimsPrincipalFactory claimsFactory, + Microsoft.Extensions.Options.IOptions optionsAccessor, + Microsoft.Extensions.Logging.ILogger> logger, + Microsoft.AspNetCore.Authentication.IAuthenticationSchemeProvider schemes, + Microsoft.AspNetCore.Identity.IUserConfirmation confirmation) + : base(userManager, contextAccessor, claimsFactory, optionsAccessor, logger, schemes, confirmation) + { + } } ```` +> It is important to use **Volo.Abp.Identity.IdentityUser** type for SignInManager to inherit, not the AppUser of your application. + +Afterwards you can override any of the SignIn Manager methods you need and add new methods and properties needed for your authentication or registration flow. +## Overriding the GetExternalLoginInfoAsync Method -## Overriding Methods +In this case we'll be overriding the `GetExternalLoginInfoAsync` method which is invoked when a third party authentication is implemented. -Afterwards you can override a method like `GetExternalLoginInfoAsync`: +A good way to override a method is copying its [source code](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Identity/Core/src/SignInManager.cs#L638-L674). In this case, we will be using a minorly modified version of the source code which explicitly shows the namespaces of the methods and properties to help better understanding of the concept. -````xml -public override async Task GetExternalLoginInfoAsync(string expectedXsrf = null) +````csharp +public override async Task GetExternalLoginInfoAsync(string expectedXsrf = null) { - var auth = await Context.AuthenticateAsync(IdentityConstants.ExternalScheme); + var auth = await Context.AuthenticateAsync(Microsoft.AspNetCore.Identity.IdentityConstants.ExternalScheme); var items = auth?.Properties?.Items; - if (auth?.Principal == null || items == null || !items.ContainsKey("LoginProvider")) + if (auth?.Principal == null || items == null || !items.ContainsKey("LoginProviderKey")) { - return null; + return null; } if (expectedXsrf != null) { - if (!items.ContainsKey("XsrfId")) + if (!items.ContainsKey("XsrfKey")) { - return null; + return null; } var userId = items[XsrfKey] as string; if (userId != expectedXsrf) { - return null; + return null; + } } + var providerKey = auth.Principal.FindFirstValue(ClaimTypes.NameIdentifier); var provider = items[LoginProviderKey] as string; if (providerKey == null || provider == null) { - return null; + return null; } - var providerDisplayName = (await GetExternalAuthenticationSchemesAsync()).FirstOrDefault(p => p.Name == provider)?.DisplayName ?? provider; - return new ExternalLoginInfo(auth.Principal, provider, providerKey, providerDisplayName) + var providerDisplayName = (await GetExternalAuthenticationSchemesAsync()).FirstOrDefault(p => p.Name == provider)?.DisplayName + ?? provider; + return new Microsoft.AspNetCore.Identity.ExternalLoginInfo(auth.Principal, provider, providerKey, providerDisplayName) { - AuthenticationTokens = auth.Properties.GetTokens() + AuthenticationTokens = auth.Properties.GetTokens() }; } ```` +To get your overridden method invoked and your customized SignIn Manager class to work, you need to register your class to the [Dependency Injection System](../Dependency-Injection.md). +## Register to Dependency Injection -## Registering to DI +Registering `CustomSignInManager` should be done with adding **AddSignInManager** extension method of the [IdentityBuilderExtensions](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/IdentityBuilderExtensions.cs) of the [IdentityBuilder](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Extensions.Core/src/IdentityBuilder.cs). -You need to register your Custom SignIn Manager to DI to activate it. Inside the `.Web` project, locate the `ApplicationNameWebModule` and add the following under `ConfigureServices` method: +Inside your `.Web` project, locate the `ApplicationNameWebModule` and add the following under `ConfigureServices` method to replace the old SignInManager with your customized one. -````xml +````csharp context.Services .GetObject() .AddSignInManager(); -```` \ No newline at end of file +```` + +## The Source Code + +You can find the source code of the completed example [here](https://github.com/abpframework/abp-samples/tree/master/aspnet-core/Authentication-Customization). + +## See Also + +* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC). \ No newline at end of file From 086cd25a8f57fe4df33a8223fe933f521a11cc37 Mon Sep 17 00:00:00 2001 From: Galip Tolga Erdem Date: Mon, 6 Apr 2020 02:51:46 +0300 Subject: [PATCH 2/5] updated signin manager and azure active directory documentation --- ...ure-Active-Directory-Authentication-MVC.md | 107 +++++++++++------- docs/en/How-To/Customize-SignIn-Manager.md | 9 +- 2 files changed, 72 insertions(+), 44 deletions(-) diff --git a/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md b/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md index 1d650f46b1..8e82e37e73 100644 --- a/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md +++ b/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md @@ -1,29 +1,30 @@ # How to Use the Azure Active Directory Authentication for MVC / Razor Page Applications -## Introduction - -This post demonstrates how to integrate AzureAD to an ABP application that enables users to sign in using OAuth 2.0 with credentials from Azure Active Directory. +This guide demonstrates how to integrate AzureAD to an ABP application that enables users to sign in using OAuth 2.0 with credentials from **Azure Active Directory**. Adding Azure Active Directory is pretty straightforward in ABP framework. Couple of configurations needs to be done correctly. -There will be two samples of connections for better coverage; - -- **AddAzureAD** (Microsoft.AspNetCore.Authentication.AzureAD.UI package) -- **AddOpenIdConnect** (Default Microsoft.AspNetCore.Authentication.OpenIdConnect package) +Two different **alternative approaches** for AzureAD integration will be demonstrated for better coverage. +1. **AddAzureAD**: This approach uses Microsoft [AzureAD UI nuget package](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.AzureAD.UI/) which is very popular when users search the web about how to integrate AzureAD to their web application. +2. **AddOpenIdConnect**: This approach uses default [OpenIdConnect](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect/) which can be used for not only AzureAD but for all OpenId connections. -## Sample Code +> There is **no difference** in functionality between these approaches. AddAzureAD is an abstracted way of OpenIdConnection ([source](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADAuthenticationBuilderExtensions.cs#L122)). +> +> However there are key differences in integration to ABP applications because of defaultly configurated signin schemes which will be explained below. -https://github.com/abpframework/abp-samples/tree/master/aspnet-core/BookStore-AzureAD +## 1. AddAzureAD +This approach uses the most common way to integrate AzureAD by using the [Microsoft AzureAD UI nuget package](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.AzureAD.UI/). +If you choose this approach, you will need to install `Microsoft.AspNetCore.Authentication.AzureAD.UI` package to your **.Web** project. Also, since AddAzureAD extension uses [configuration binding](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1#default-configuration), you need to update your appsettings.json file located in your **.Web** project. -## Setup +#### **Updating `appsettings.json`** -Update your `appsettings.json` in your **.Web** application and add the following section filled with your AzureAD application settings. +You need to add a new section to your appsettings which will be binded to configuration when configuring the OpenIdConnectOptions: -````xml +````json "AzureAd": { "Instance": "https://login.microsoftonline.com/", "TenantId": " Important configuration here is the CallbackPath. This value must be the same with one of your Azure AD-> app registrations-> Authentication -> RedirectUri. +Then, you need to configure the OpenIdConnectOptions to complete the integration. -## AddAzureAD - -#### **Update your `appsettings.json`** +#### Configuring OpenIdConnectOptions -Install `Microsoft.AspNetCore.Authentication.AzureAD.UI` package to your **.Web** application. +In your **.Web** project, locate your **ApplicationWebModule** and modify `ConfigureAuthentication` method with the following: -In your **.Web** application, add the following section filled with your AzureAD application settings. Modify `ConfigureAuthentication` method of your **BookStoreWebModule** with the following: - -````xml +````csharp private void ConfigureAuthentication(ServiceConfigurationContext context, IConfiguration configuration) { JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); @@ -75,13 +74,37 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi } ```` +> **Don't forget to:** +> +> * Add `.AddAzureAD(options => configuration.Bind("AzureAd", options))` after `.AddAuthentication()`. This binds your AzureAD appsettings and easy to miss out. +> * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear()`. This will disable the default Microsoft claim type mapping. +> * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier)`. Mapping this to [ClaimTypes.NameIdentifier](https://github.com/dotnet/runtime/blob/6d395de48ac718a913e567ae80961050f2a9a4fa/src/libraries/System.Security.Claims/src/System/Security/Claims/ClaimTypes.cs#L59) is important since default SignIn Manager behavior uses this claim type for external login information. You can also use `oid` claim instead of `sub` claim since AzureAD objectID is also unique. +> * Add `options.SignInScheme = IdentityConstants.ExternalScheme` since [default signin scheme is `AzureADOpenID`](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADDefaults.cs#L16). +> * Add `options.Scope.Add("email")` if you are using **v2.0** endpoint of AzureAD since v2.0 endpoint doesn't return the `email` claim as default. The [Account Module](../Modules/Account) uses `email` claim to [register external users](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/account/src/Volo.Abp.Account.Web/Pages/Account/Login.cshtml.cs#L215). + +You are done and integration is completed. + +## 2. Alternative Approach: AddOpenIdConnect +If you don't want to use an extra nuget package in your application, you can use the straight default [OpenIdConnect](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect/) which can be used for all OpenId connections including AzureAD external authentication. -## AddOpenIdConnect +You don't have to use appsettings configuration but it is a good practice to set AzureAD information in the appsettings. + +To get the AzureAD information from appsettings, which will be used in OpenIdConnectOptions configuration, simple add a new section appsettings.json located in your **.Web** project: + +````json + "AzureAd": { + "Instance": "https://login.microsoftonline.com/", + "TenantId": "", + "Domain": "domain.onmicrosoft.com", + "CallbackPath": "/signin-azuread-oidc" + } +```` -Modify `ConfigureAuthentication` method of your **BookStoreWebModule** with the following: +Then, In your **.Web** project; you can modify the `ConfigureAuthentication` method located in your **ApplicationWebModule** with the following: -````xml +````csharp private void ConfigureAuthentication(ServiceConfigurationContext context, IConfiguration configuration) { JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); @@ -96,18 +119,26 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi }) .AddOpenIdConnect("AzureOpenId", "AzureAD", options => { - options.Authority = "https://login.microsoftonline.com/" + configuration["AzureAd:TenantId"]; + options.Authority = "https://login.microsoftonline.com/" + configuration["AzureAd:TenantId"] + "/v2.0/"; options.ClientId = configuration["AzureAd:ClientId"]; options.ResponseType = OpenIdConnectResponseType.CodeIdToken; options.CallbackPath = configuration["AzureAd:CallbackPath"]; options.RequireHttpsMetadata = false; options.SaveTokens = true; options.GetClaimsFromUserInfoEndpoint = true; + + options.Scope.Add("email"); }); } ```` +> You can change the display name of your external authentication under your login screen by changing the second parameter of the .AddOpenIdConnect ("*AzureAD*" used in this sample). + +And thats it. +## The Source Code + +You can find the source code of the completed example [here](https://github.com/abpframework/abp-samples/tree/master/aspnet-core/Authentication-Customization). # FAQ @@ -117,13 +148,13 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi 1. You are trying to authenticate against wrong scheme. Check if you set **SignInScheme** to `IdentityConstants.ExternalScheme`: - ````xml + ````csharp options.SignInScheme = IdentityConstants.ExternalScheme; ```` 2. Your `ClaimTypes.NameIdentifier` is `null`. Check if you added claim mapping: - ````xml + ````csharp JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier); ```` @@ -133,7 +164,7 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi * If you set your **CallbackPath** in appsettings as: - ````xml + ````csharp "AzureAd": { ... "CallbackPath": "/signin-azuread-oidc" @@ -145,19 +176,19 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi * Help! I am getting ***System.ArgumentNullException: Value cannot be null. (Parameter 'userName')*** error! - * This occurs when you use Azure Authority **v2.0 endpoint** without requesting `email` scope. [Abp checks unique email to create user](https://github.com/abpframework/abp/blob/037ef9abe024c03c1f89ab6c933710bcfe3f5c93/modules/account/src/Volo.Abp.Account.Web/Pages/Account/Login.cshtml.cs#L208). Simply add + * This occurs when you use Azure Authority **v2.0 endpoint** without requesting `email` scope. [Abp checks unique email to create user](https://github.com/abpframework/abp/blob/037ef9abe024c03c1f89ab6c933710bcfe3f5c93/modules/account/src/Volo.Abp.Account.Web/Pages/Account/Login.cshtml.cs#L208). Simply add - ````xml - options.Scope.Add("email"); - ```` + ````csharp + options.Scope.Add("email"); + ```` - to your openid configuration. + to your openid configuration. * How can I **debug/watch** which claims I get before they get mapped? * You can add a simple event under openid configuration to debug before mapping like: - ````xml + ````csharp options.Events.OnTokenValidated = (async context => { var claimsFromOidcProvider = context.Principal.Claims.ToList(); @@ -165,14 +196,8 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi }); ```` -* I want to debug further, how can I implement my custom **SignInManager**? - - * You can check [Customizing SignInManager in Abp Framework](link here) post. - -* I want to add extra properties to user while they are being created. How can I do that? - - * You can check [Customizing Login Page in Abp Framework]() post. -* Why can't I see **External Register Page** after I sign in from external provider for the first time? +## See Also - * ABP framework automatically registers your user with supported email claim from your external authentication provider. You can change this behavior by [Customizing Login Page in Abp Framework](will be link here). +* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC). +* [How to Customize the SignIn Manager for ABP Applications](Customize-SignIn-Manager). \ No newline at end of file diff --git a/docs/en/How-To/Customize-SignIn-Manager.md b/docs/en/How-To/Customize-SignIn-Manager.md index f8108c1910..0a6c47cb13 100644 --- a/docs/en/How-To/Customize-SignIn-Manager.md +++ b/docs/en/How-To/Customize-SignIn-Manager.md @@ -1,6 +1,8 @@ # How to Customize the SignIn Manager for ABP Applications -After creating a new application using the [application startup template](../Startup-Templates/Application.md), you may want extend or change the default behavior of the SignIn Manager for your authentication and registration flow needs. ABP [Account Module](../Modules/Account) uses default [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs). To write your Custom SignIn Manager, you need to extend this class and register to the DI container. +After creating a new application using the [application startup template](../Startup-Templates/Application.md), you may want extend or change the default behavior of the SignIn Manager for your authentication and registration flow needs. ABP [Account Module](../Modules/Account) uses the [Identity Management Module](../Modules/Identity) for SignIn Manager and the [Identity Management Module](../Modules/Identity) uses default [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs) ([see here](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/identity/src/Volo.Abp.Identity.AspNetCore/Volo/Abp/Identity/AspNetCore/AbpIdentityAspNetCoreModule.cs#L17)). + +To write your Custom SignIn Manager, you need to extend [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs) class and register it to the DI container. This document explains how to customize the SignIn Manager for your own application. @@ -85,7 +87,7 @@ Inside your `.Web` project, locate the `ApplicationNameWebModule` and add the fo ````csharp context.Services .GetObject() - .AddSignInManager(); + .AddSignInManager(); ```` ## The Source Code @@ -94,4 +96,5 @@ You can find the source code of the completed example [here](https://github.com/ ## See Also -* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC). \ No newline at end of file +* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC). +* [Identity Management Module](../Modules/Identity). \ No newline at end of file From 3ee8756ed06ea780bc260753b93b41330ec72a42 Mon Sep 17 00:00:00 2001 From: Galip Tolga Erdem Date: Mon, 6 Apr 2020 02:53:27 +0300 Subject: [PATCH 3/5] updated index --- docs/en/How-To/Index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/How-To/Index.md b/docs/en/How-To/Index.md index d6b31fa7ed..da209d4bcb 100644 --- a/docs/en/How-To/Index.md +++ b/docs/en/How-To/Index.md @@ -6,4 +6,4 @@ This section contains "how to" guides for some specific questions frequently ask * [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC.md) * [How to Use the Azure Active Directory Authentication for MVC / Razor Page Applications](Azure-Active-Directory-Authentication-MVC.md) -* [Customize the SignInManager](Customize-SignIn-Manager.md) (as an example of customization) \ No newline at end of file +* [How to Customize the SignIn Manager for ABP Applications](Customize-SignIn-Manager.md) \ No newline at end of file From 0b2dd2e2e4e0068ee561e7b538644ba99be57596 Mon Sep 17 00:00:00 2001 From: Galip Tolga Erdem Date: Mon, 6 Apr 2020 03:05:58 +0300 Subject: [PATCH 4/5] added missing hyperlink .md extensions --- docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md | 6 +++--- docs/en/How-To/Customize-Login-Page-MVC.md | 4 ++-- docs/en/How-To/Customize-SignIn-Manager.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md b/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md index 8e82e37e73..264da68901 100644 --- a/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md +++ b/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md @@ -80,7 +80,7 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi > * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear()`. This will disable the default Microsoft claim type mapping. > * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier)`. Mapping this to [ClaimTypes.NameIdentifier](https://github.com/dotnet/runtime/blob/6d395de48ac718a913e567ae80961050f2a9a4fa/src/libraries/System.Security.Claims/src/System/Security/Claims/ClaimTypes.cs#L59) is important since default SignIn Manager behavior uses this claim type for external login information. You can also use `oid` claim instead of `sub` claim since AzureAD objectID is also unique. > * Add `options.SignInScheme = IdentityConstants.ExternalScheme` since [default signin scheme is `AzureADOpenID`](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADDefaults.cs#L16). -> * Add `options.Scope.Add("email")` if you are using **v2.0** endpoint of AzureAD since v2.0 endpoint doesn't return the `email` claim as default. The [Account Module](../Modules/Account) uses `email` claim to [register external users](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/account/src/Volo.Abp.Account.Web/Pages/Account/Login.cshtml.cs#L215). +> * Add `options.Scope.Add("email")` if you are using **v2.0** endpoint of AzureAD since v2.0 endpoint doesn't return the `email` claim as default. The [Account Module](../Modules/Account.md) uses `email` claim to [register external users](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/account/src/Volo.Abp.Account.Web/Pages/Account/Login.cshtml.cs#L215). You are done and integration is completed. @@ -199,5 +199,5 @@ You can find the source code of the completed example [here](https://github.com/ ## See Also -* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC). -* [How to Customize the SignIn Manager for ABP Applications](Customize-SignIn-Manager). \ No newline at end of file +* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC.md). +* [How to Customize the SignIn Manager for ABP Applications](Customize-SignIn-Manager.md). \ No newline at end of file diff --git a/docs/en/How-To/Customize-Login-Page-MVC.md b/docs/en/How-To/Customize-Login-Page-MVC.md index 49b4b4c39e..33261709bc 100644 --- a/docs/en/How-To/Customize-Login-Page-MVC.md +++ b/docs/en/How-To/Customize-Login-Page-MVC.md @@ -1,6 +1,6 @@ # How to Customize the Login Page for MVC / Razor Page Applications -When you create a new application using the [application startup template](../Startup-Templates/Application.md), source code of the login page will not be inside your solution, so you can not directly change it. The login page comes from the [Account Module](../Modules/Account) that is used a [NuGet package](https://www.nuget.org/packages/Volo.Abp.Account.Web) reference. +When you create a new application using the [application startup template](../Startup-Templates/Application.md), source code of the login page will not be inside your solution, so you can not directly change it. The login page comes from the [Account Module.md](../Modules/Account) that is used a [NuGet package](https://www.nuget.org/packages/Volo.Abp.Account.Web) reference. This document explains how to customize the login page for your own application. @@ -110,4 +110,4 @@ You can find the source code of the completed example [here](https://github.com/ ## See Also -* [ASP.NET Core (MVC / Razor Pages) User Interface Customization Guide](../UI/AspNetCore/Customization-User-Interface). \ No newline at end of file +* [ASP.NET Core (MVC / Razor Pages) User Interface Customization Guide](../UI/AspNetCore/Customization-User-Interface.md). \ No newline at end of file diff --git a/docs/en/How-To/Customize-SignIn-Manager.md b/docs/en/How-To/Customize-SignIn-Manager.md index 0a6c47cb13..510e8146aa 100644 --- a/docs/en/How-To/Customize-SignIn-Manager.md +++ b/docs/en/How-To/Customize-SignIn-Manager.md @@ -1,6 +1,6 @@ # How to Customize the SignIn Manager for ABP Applications -After creating a new application using the [application startup template](../Startup-Templates/Application.md), you may want extend or change the default behavior of the SignIn Manager for your authentication and registration flow needs. ABP [Account Module](../Modules/Account) uses the [Identity Management Module](../Modules/Identity) for SignIn Manager and the [Identity Management Module](../Modules/Identity) uses default [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs) ([see here](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/identity/src/Volo.Abp.Identity.AspNetCore/Volo/Abp/Identity/AspNetCore/AbpIdentityAspNetCoreModule.cs#L17)). +After creating a new application using the [application startup template](../Startup-Templates/Application.md), you may want extend or change the default behavior of the SignIn Manager for your authentication and registration flow needs. ABP [Account Module](../Modules/Account.md) uses the [Identity Management Module](../Modules/Identity.md) for SignIn Manager and the [Identity Management Module](../Modules/Identity.md) uses default [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs) ([see here](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/identity/src/Volo.Abp.Identity.AspNetCore/Volo/Abp/Identity/AspNetCore/AbpIdentityAspNetCoreModule.cs#L17)). To write your Custom SignIn Manager, you need to extend [Microsoft Identity SignIn Manager](https://github.com/dotnet/aspnetcore/blob/master/src/Identity/Core/src/SignInManager.cs) class and register it to the DI container. @@ -96,5 +96,5 @@ You can find the source code of the completed example [here](https://github.com/ ## See Also -* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC). -* [Identity Management Module](../Modules/Identity). \ No newline at end of file +* [How to Customize the Login Page for MVC / Razor Page Applications](Customize-Login-Page-MVC.md). +* [Identity Management Module](../Modules/Identity.md). \ No newline at end of file From 989e317076ffc30bcf66a6f1d92e93d9388ea7df Mon Sep 17 00:00:00 2001 From: Galip Tolga Erdem Date: Mon, 6 Apr 2020 04:01:40 +0300 Subject: [PATCH 5/5] fixed typos. --- ...ure-Active-Directory-Authentication-MVC.md | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md b/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md index 264da68901..6eb9c594c6 100644 --- a/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md +++ b/docs/en/How-To/Azure-Active-Directory-Authentication-MVC.md @@ -10,7 +10,7 @@ Two different **alternative approaches** for AzureAD integration will be demonst 2. **AddOpenIdConnect**: This approach uses default [OpenIdConnect](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect/) which can be used for not only AzureAD but for all OpenId connections. -> There is **no difference** in functionality between these approaches. AddAzureAD is an abstracted way of OpenIdConnection ([source](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADAuthenticationBuilderExtensions.cs#L122)). +> There is **no difference** in functionality between these approaches. AddAzureAD is an abstracted way of OpenIdConnection ([source](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADAuthenticationBuilderExtensions.cs#L122)) with predefined cookie settings. > > However there are key differences in integration to ABP applications because of defaultly configurated signin schemes which will be explained below. @@ -27,7 +27,7 @@ You need to add a new section to your appsettings which will be binded to config ````json "AzureAd": { "Instance": "https://login.microsoftonline.com/", - "TenantId": "", "ClientId": "", "Domain": "domain.onmicrosoft.com", "CallbackPath": "/signin-azuread-oidc" @@ -61,7 +61,7 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi options.Authority = options.Authority + "/v2.0/"; options.ClientId = configuration["AzureAd:ClientId"]; options.CallbackPath = configuration["AzureAd:CallbackPath"]; - options.ResponseType = OpenIdConnectResponseType.IdToken; + options.ResponseType = OpenIdConnectResponseType.CodeIdToken; options.RequireHttpsMetadata = false; options.TokenValidationParameters.ValidateIssuer = false; @@ -78,8 +78,8 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi > > * Add `.AddAzureAD(options => configuration.Bind("AzureAd", options))` after `.AddAuthentication()`. This binds your AzureAD appsettings and easy to miss out. > * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear()`. This will disable the default Microsoft claim type mapping. -> * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier)`. Mapping this to [ClaimTypes.NameIdentifier](https://github.com/dotnet/runtime/blob/6d395de48ac718a913e567ae80961050f2a9a4fa/src/libraries/System.Security.Claims/src/System/Security/Claims/ClaimTypes.cs#L59) is important since default SignIn Manager behavior uses this claim type for external login information. You can also use `oid` claim instead of `sub` claim since AzureAD objectID is also unique. -> * Add `options.SignInScheme = IdentityConstants.ExternalScheme` since [default signin scheme is `AzureADOpenID`](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADDefaults.cs#L16). +> * Add `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier)`. Mapping this to [ClaimTypes.NameIdentifier](https://github.com/dotnet/runtime/blob/6d395de48ac718a913e567ae80961050f2a9a4fa/src/libraries/System.Security.Claims/src/System/Security/Claims/ClaimTypes.cs#L59) is important since default SignIn Manager behavior uses this claim type for external login information. +> * Add `options.SignInScheme = IdentityConstants.ExternalScheme` since [default signin scheme is `AzureADOpenID`](https://github.com/dotnet/aspnetcore/blob/c56aa320c32ee5429d60647782c91d53ac765865/src/Azure/AzureAD/Authentication.AzureAD.UI/src/AzureADOpenIdConnectOptionsConfiguration.cs#L35). > * Add `options.Scope.Add("email")` if you are using **v2.0** endpoint of AzureAD since v2.0 endpoint doesn't return the `email` claim as default. The [Account Module](../Modules/Account.md) uses `email` claim to [register external users](https://github.com/abpframework/abp/blob/be32a55449e270d2d456df3dabdc91f3ffdd4fa9/modules/account/src/Volo.Abp.Account.Web/Pages/Account/Login.cshtml.cs#L215). You are done and integration is completed. @@ -90,12 +90,12 @@ If you don't want to use an extra nuget package in your application, you can use You don't have to use appsettings configuration but it is a good practice to set AzureAD information in the appsettings. -To get the AzureAD information from appsettings, which will be used in OpenIdConnectOptions configuration, simple add a new section appsettings.json located in your **.Web** project: +To get the AzureAD information from appsettings, which will be used in OpenIdConnectOptions configuration, simply add a new section to appsettings.json located in your **.Web** project: ````json "AzureAd": { "Instance": "https://login.microsoftonline.com/", - "TenantId": "", "ClientId": "", "Domain": "domain.onmicrosoft.com", "CallbackPath": "/signin-azuread-oidc" @@ -117,7 +117,7 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi options.RequireHttpsMetadata = false; options.ApiName = "BookStore"; }) - .AddOpenIdConnect("AzureOpenId", "AzureAD", options => + .AddOpenIdConnect("AzureOpenId", "Azure Active Directory OpenId", options => { options.Authority = "https://login.microsoftonline.com/" + configuration["AzureAd:TenantId"] + "/v2.0/"; options.ClientId = configuration["AzureAd:ClientId"]; @@ -132,9 +132,7 @@ private void ConfigureAuthentication(ServiceConfigurationContext context, IConfi } ```` -> You can change the display name of your external authentication under your login screen by changing the second parameter of the .AddOpenIdConnect ("*AzureAD*" used in this sample). - -And thats it. +And thats it, integration is completed. Keep on mind that you can connect any other external authentication providers. ## The Source Code