{"id":21559790,"url":"https://github.com/dasiths/neasyauthmiddleware","last_synced_at":"2025-04-10T11:41:12.555Z","repository":{"id":51975952,"uuid":"182807889","full_name":"dasiths/NEasyAuthMiddleware","owner":"dasiths","description":"Azure App Service Authentication (EasyAuth) middleware for ASP.NET CORE with fully customizable components and support for local debugging","archived":false,"fork":false,"pushed_at":"2024-08-15T06:14:47.000Z","size":82,"stargazers_count":14,"open_issues_count":3,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-08T08:19:59.639Z","etag":null,"topics":["appservice","aspnetcore","authentication","azure","easyauth","middleware"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dasiths.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-22T14:44:48.000Z","updated_at":"2025-02-11T17:24:08.000Z","dependencies_parsed_at":"2024-08-15T07:54:49.987Z","dependency_job_id":null,"html_url":"https://github.com/dasiths/NEasyAuthMiddleware","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FNEasyAuthMiddleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FNEasyAuthMiddleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FNEasyAuthMiddleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasiths%2FNEasyAuthMiddleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dasiths","download_url":"https://codeload.github.com/dasiths/NEasyAuthMiddleware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248210896,"owners_count":21065634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appservice","aspnetcore","authentication","azure","easyauth","middleware"],"created_at":"2024-11-24T09:09:27.495Z","updated_at":"2025-04-10T11:41:12.534Z","avatar_url":"https://github.com/dasiths.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NEasyAuthMiddleware  [![Build status](https://ci.appveyor.com/api/projects/status/5e9kb8rd3egstvkb?svg=true)](https://ci.appveyor.com/project/dasiths/neasyauthmiddleware) [![NuGet](https://img.shields.io/nuget/v/NEasyAuthMiddleware.svg)](https://www.nuget.org/packages/NEasyAuthMiddleware) [![Downloads](https://img.shields.io/nuget/dt/NEasyAuthMiddleware.svg)](https://www.nuget.org/packages/NEasyAuthMiddleware/)\n\nAzure App Service Authentication (EasyAuth) middleware for ASP.NET CORE with fully customizable components with support for local debugging.\n\n## What is `EasyAuth`?\n\nAzure `App Service` has a feature to turn on Authentication on top of your application code. This is useful if you don't want to handle the nitty gritty of auth. It's meant to be a quick and easy way to put an authentication layer above an application hosted on an app service. More details can be found here https://docs.microsoft.com/en-us/azure/app-service/overview-authentication-authorization.\n\nThere is a how to get started tutorial [here](https://www.benday.com/2018/05/17/walkthrough-part-2-configure-app-service-authentication-for-your-azure-web-app/).\n\n## The problem\n\nAlthough we don't have to worry about things like `OAuth` or `OpenIdConnect` when we use EasyAuth, there are instances where we still need to know information about the logged in user. For example you might want to allow only users who have a certain role to access a part of your system.\n\nASP.NET applications built for the full .NET Framework have the `HttpContext.User` already populated by EasyAuth. But AspNetCore web applications don't get that due to the fact that IIS EasyAuth modules not integrating with AspNetCore.\n\nDue to this limitation, If you want to make decisions based on the current user, you have to use your own logic to construct the user principal by looking at HTTP headers in the request.\n\nTo add insult to injury, when you want to debug this on your local machine, these HTTP headers will not be present as these are added by the App Service. So you will have to use some form of mocking to populate the user principal.\n\n## Solution\n\nNEasyAuthMiddleware does all of this complicated logic for you and keeps your authentication concerns simple. It hydrates the `HttpContext.User` by registering a custom authentication handler. To make things easier when running locally, it even has the ability to use a `json` file to load mocked claims.\n\n## Using it\n\n- Version 1.X targets AspNet Core 2.x\n- Version 2.X targets AspNet Core 3.x\n- Version 3.x targets AspNet Core 8.x\n\nInstall the package using NuGet Package Manager Console\n\n```\ndotnet add package NEasyAuthMiddleware\n```\n\nJust add the following to your `Startup.cs`\n\n```csharp\n        public void ConfigureServices(IServiceCollection services)\n        {\n            services.AddEasyAuth();\n\n            // Add this if you want your app to support [automatic Challenges](#handling-unauthenticated-requests)\n            services.AddAuthorization();\n\n            if (_hostingEnvironment.IsDevelopment()) // Use the mock json file when not running in an app service\n            {\n                var mockFile = $\"{_hostingEnvironment.ContentRootPath}\\\\mock_user.json\";\n                services.UseJsonFileToMockEasyAuth(mockFile);\n            }\n        }\n\n        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.\n        public void Configure(IApplicationBuilder app, IHostingEnvironment env)\n        {\n            app.UseAuthentication(); // Indicate we are using the Authenticaiton middleware\n            app.UseRouting();\n\n            // Add this if you want your app to support [automatic Challenges](#handling-unauthenticated-requests)\n            app.UseAuthorization(); // This has to come between routing and endoints\n\n            app.UseEndpoints(endpoints =\u003e\n            {\n                // Your endpoints are defined here\n                endpoints.MapControllers();\n                endpoints.MapRazorPages();\n            });\n        }\n```\n\nIn your controller, use the `Authorize` attribute as you would with any other authentication provider.\n\n```csharp\n        [Authorize(Roles = \"Resource.Read\")]\n        public ActionResult\u003cstring\u003e Get()\n        {\n            return \"authorization worked...\";\n        }\n```\n\nSee the [sample app](https://github.com/dasiths/NEasyAuthMiddleware/tree/master/NEasyAuthMiddleware.Sample) for more.\n\n## Handling unauthenticated requests\nAzure App Services allows you to configure EasyAuth to allow unauthenticated requests to pass through to your application. This is useful when you want to handle authentication in your application code, or only enable it for certain pages or flows. \n\nThis library supports this scenario. If you've specified `AddAuthorization()` to the service collection, and added `UseAuthorization()` to the middleware pipeline, the library will automatically redirect users to login with EasyAuth on controllers attributed with `[Authorize]`.\n\nBy default the library assumes AAD/Microsoft Entra auth, but you can customize the [provider](https://learn.microsoft.com/en-us/azure/app-service/overview-authentication-authorization#identity-providers) using `EasyAuthOptions` when adding the service. The library provides a list of known providers in the `NEasyAuthMiddleware.Constants.KnownAuthProviders` static class.\n\n```csharp\n\t\tpublic void ConfigureServices(IServiceCollection services)\n\t\t{\n\t\t\tservices.AddEasyAuth(options =\u003e\n\t\t\t{\n\t\t\t\toptions.Provider = KnownAuthProviders.Google; // Use Google as the auth provider\n\t\t\t});\n\t\t}\n```\n\n## Customizing it\n\nThe library already maps most of the claims coming in the http headers. If you find a custom header that you would like to map to the claims of the current user, all you have to do is implement the `IClaimMapper` interface below and register it in your DI container.\n\n```csharp\n    public interface IClaimMapper\n    {\n        ClaimMapResult Map(IHeaderDictionary headers);\n    }\n```\n\nIf you require mutating the `IHeaderDictionary` prior to being consumed by the mappers, implement the `IHeaderDictionaryTransformer` interface and register it in your DI container.\n\n```csharp\n    public interface IHeaderDictionaryTransformer\n    {\n        IHeaderDictionary Transform(IHeaderDictionary headerDictionary);\n    }\n```\n\nIf you want to filter or mutate the mapped claims prior to being part of a `ClaimsIdentity`, implement the `IClaimsTransformer` interface and register it in your DI container.\n\n```csharp\n    public interface IClaimsTransformer\n    {\n        List\u003cClaim\u003e Transform(List\u003cClaim\u003e claims);\n    }\n```\n\nNote: The main focus is to support AzureAD as the identity provider and most of the testing has been done against it. Please raise an issue if you find any bugs. Thank you.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasiths%2Fneasyauthmiddleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdasiths%2Fneasyauthmiddleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasiths%2Fneasyauthmiddleware/lists"}