{"id":26666435,"url":"https://github.com/codez-one/cz.aspnetcore.easyauthauthentication","last_synced_at":"2025-04-11T22:41:36.147Z","repository":{"id":37873463,"uuid":"285904926","full_name":"codez-one/CZ.AspNetCore.EasyAuthAuthentication","owner":"codez-one","description":"This helps getting azure appservice authentication working with asp.net core. The history of this project starts  here: https://github.com/kirkone/KK.AspNetCore.EasyAuthAuthentication","archived":false,"fork":false,"pushed_at":"2023-09-01T08:58:33.000Z","size":5433,"stargazers_count":2,"open_issues_count":21,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T18:42:58.783Z","etag":null,"topics":["asp-net-core","authentication","azure-active-directory","azure-app-service","azure-app-services","core","dotnet"],"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/codez-one.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2020-08-07T19:21:58.000Z","updated_at":"2024-03-05T19:15:19.000Z","dependencies_parsed_at":"2025-03-25T18:46:18.392Z","dependency_job_id":null,"html_url":"https://github.com/codez-one/CZ.AspNetCore.EasyAuthAuthentication","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/codez-one%2FCZ.AspNetCore.EasyAuthAuthentication","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codez-one%2FCZ.AspNetCore.EasyAuthAuthentication/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codez-one%2FCZ.AspNetCore.EasyAuthAuthentication/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codez-one%2FCZ.AspNetCore.EasyAuthAuthentication/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codez-one","download_url":"https://codeload.github.com/codez-one/CZ.AspNetCore.EasyAuthAuthentication/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248493022,"owners_count":21113159,"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":["asp-net-core","authentication","azure-active-directory","azure-app-service","azure-app-services","core","dotnet"],"created_at":"2025-03-25T18:35:08.086Z","updated_at":"2025-04-11T22:41:36.126Z","avatar_url":"https://github.com/codez-one.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CZ.AspNetCore.EasyAuthAuthentication\n\nThis helps getting azure appservice authentication working with asp.net core.\n\n## NuGet\n\nThe EasyAuth handler is provided as a nuget package and can be found on nuget.org.\n\n| Name                                 | Status                                                                                                                                                          |\n| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| CZ.AspNetCore.EasyAuthAuthentication | [![Nuget Badge](https://img.shields.io/nuget/v/CZ.AspNetCore.EasyAuthAuthentication.svg)](https://www.nuget.org/packages/CZ.AspNetCore.EasyAuthAuthentication/) |\n\nYou can add the package for example with the following `dotnet` command:\n\n```bash\ndotnet add package CZ.AspNetCore.EasyAuthAuthentication\n```\n\nPre-releases of this Package are pushed to an internal \u003ca href=\"https://dev.azure.com/czon/CZ.AspNetCore.EasyAuthAuthentication/_artifacts/feed/CZ.AspNetCore.EasyAuthAuthentication\" target=\"_blank\"\u003efeed on Azure DevOps\u003c/a\u003e.\n\n\u003e Note: For internal team members, there are also access to packages from pull requests in another \u003ca href=\"https://dev.azure.com/czon/CZ.AspNetCore.EasyAuthAuthentication/_artifacts/feed/czon-pr\" target=\"_blank\"\u003eAzure DevOps feed\u003c/a\u003e. All Packages in this feed has a name like this: `PR-{pull request number}-CZ.AspNetCore.EasyAuthAuthentication`. So you must only pick the package of your PR to check your changes in a test project. All changes of the pull request are tracked in the pull request package version history.\n\n## Build\n\nThe build environment for this project is on Azure DevOps and can be found here [dev.azure.com/czon/CZ.AspNetCore.EasyAuthAuthentication](https://dev.azure.com/kirkone/CZ.AspNetCore.EasyAuthAuthentication/_build).\n\n### Nuget package build\n\n| Name                                    | Status                                                                                                                                                                                                                                             |\n| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| CZ.AspNetCore.EasyAuthAuthentication-CI | [[![Build Status](https://dev.azure.com/czon/CZ.AspNetCore.EasyAuthAuthentication/_apis/build/status/codez-one.CZ.AspNetCore.EasyAuthAuthentication?branchName=master)](https://dev.azure.com/czon/CZ.AspNetCore.EasyAuthAuthentication/_build/latest?definitionId=7\u0026branchName=master) |\n| Alpha                                   | [![Alpha](https://vsrm.dev.azure.com/czon/_apis/public/Release/badge/bc4d5ed4-f7f8-4b67-9212-2dadeae79439/2/2)](https://dev.azure.com/kirkone/CZ.AspNetCore.EasyAuthAuthentication/_releases2?definitionId=2\u0026_a=releases)                       |\n| Beta                                    | [![Beta](https://vsrm.dev.azure.com/czon/_apis/public/Release/badge/bc4d5ed4-f7f8-4b67-9212-2dadeae79439/2/3)](https://dev.azure.com/kirkone/CZ.AspNetCore.EasyAuthAuthentication/_releases2?definitionId=2\u0026_a=releases)                        |\n| Release                                 | [![Release](https://vsrm.dev.azure.com/czon/_apis/public/Release/badge/bc4d5ed4-f7f8-4b67-9212-2dadeae79439/2/4)](https://dev.azure.com/kirkone/CZ.AspNetCore.EasyAuthAuthentication/_releases2?definitionId=2\u0026_a=releases)                     |\n\n## Quickstart\n\nIn your Startup of your WebApp you must configure your authentication schemes and add easy auth to you dependency injection. The easiest way is to use the configuration of your web app. This can be done in the `ConfigureServices` method in your `Startup`.\n\n```csharp\nservices.AddAuthentication(\n    options =\u003e\n    {\n        options.DefaultAuthenticateScheme = EasyAuthAuthenticationDefaults.AuthenticationScheme;\n        options.DefaultChallengeScheme = EasyAuthAuthenticationDefaults.AuthenticationScheme;\n    }\n).AddEasyAuth(this.Configuration);\n```\n\nThe next you must add the easy auth middleware to the ASP.NET pipeline. This can be enabled by the folling section in your `Configure`method in the `Startup`:\n\n```csharp\napp.UseAuthentication();\n```\n\n\u003e Warning: make sure you add the `UseAuthentication` in the right order for your use case.\n\nThe last thing is to add the following section in the `appsettings.json` to enabled the basic providers:\n\n```json\n\"easyAuthOptions\": {\n  \"providerOptions\": [\n      {\n        \"ProviderName\": \"EasyAuthForAuthorizationTokenService\",\n        \"Enabled\": true\n      },\n      {\n        \"ProviderName\": \"EasyAuthAzureAdService\",\n        \"Enabled\": true\n      }\n  ]\n}\n```\n\nAfter this you can use your app can translate the claims of easy auth for azure AD by it's own.\n\n### Configure Azure App Service\n\nIn general you need a windows based App Service Plan to get this working. There is no Easy Auth implementation in the linux based app service plans!\n\n\u003e Information: for current documentation about this azure feature see [here](https://docs.microsoft.com/en-us/azure/app-service/overview-authentication-authorization).\n\nThe first step is enable the authentication feature in azure. It is important to disabled anonymous requests!\n\n![basic auth settings](docs/assets/easyauth-config.png)\n\nThen you need the connection to your azure active directory. (other providers currently not implemented)\n\n![azure AD configuration](docs/assets/aad-app-config.png)\n\nSave all and publish your app. This allows you to use the user claim in you app like:\n\n```csharp\n[Authorize]\npublic string UserName()\n{\n    _ = User.HasClaim(ClaimTypes.Name, \"user@somecloud.onmicrosoft.com\");\n    _ = User.HasClaim(ClaimTypes.Role, \"SystemAdmin\");\n    _ = HttpContext.User.IsInRole(\"SystemAdmin\");\n    _ = User.IsInRole(\"SystemAdmin\");\n    return HttpContext.User.Identity.Name;\n}\n```\n\n### Local Debugging\n\n\u003e Information: for this step it is required to have an configured app service!\n\nThis library give you an easy way to do local debugging enabled while your app is 100% cloud native. To do this you must only do a request to the following azure url:\n\n`https://yourAzureAppServiceUrl/.auth/me`\n\nThe result of the request is a json with the authentication information of your current user. Put this json simply in the file `wwwroot/.auth/me.json`, and you are these user in your next debugging session. You also don't need a connection to the internet.\n\n\u003e Important: You must enable `UseStaticFiles` in your `Startup`. This is the case in the default ASP.NET frontend project.\n\n## Details of the implementation\n\n### Adding custom roles\n\nIf you want to add roles to the `User` property you can have a look in `Transformers/ClaimsTransformer.cs` in the Sample project. There you can see an example how to get started with this.\n\n### Configure options via configuration (recommended)\n\nYou can use the default behavior of asp.net core to configure EasyAuth. You must only change in your `Startup.cs` the `.AddEasyAuth()` to `.AddEasyAuth(this.Configuration)`.\n\n\u003e To get the property `this.Configuration` in your `Startup.cs` you must add `IConfiguration configuration` to your constructor parameters and create a property.\n\nTo configure you providers you simple add the following to your `appsettings.json`. (or to your environment variables, or other [configuration sources](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/).)\n\n```json\n\"easyAuthOptions\": {\n    \"AuthEndpoint\": \".auth/me\",\n    \"providerOptions\": [\n      {\n        \"ProviderName\": \"EasyAuthForAuthorizationTokenService\",\n        \"Enabled\": true,\n        \"NameClaimType\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn\", // optional\n        \"RoleClaimType\": \"roles\" // optional\n      },\n      {\n        \"ProviderName\": \"EasyAuthAzureAdService\",\n        \"Enabled\": true,\n        \"NameClaimType\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\", //optional\n        \"RoleClaimType\": \"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\" //optional\n      }\n    ]\n  }\n```\n\nHere are some notes to the JSON above:\n\n-   each provider is disabled by default so you must enabled it\n-   you can create own providers but there must implement `IEasyAuthAuthentificationService`. But you must also activate them here. (Don't put them in the DI. This package will do this by it's own.)\n-   The `ProviderName` is the class name of the provider. that must be unique in your application.\n-   The xClaimType property only define the property in the token that provide the required information. Internally that will always mapped to **name** and **role** claims.\n\n\u003e A list of all providers can be found in the headline `Auth Provider`\n\n### Configure options via code (not recommended)\n\n#### Custom options\n\nYou can provide additional options for the middleware:\n\n```csharp\n).AddEasyAuth(\n   options =\u003e {\n      // Add the EasyAuthForApplicationService auth provider and enabled it. Also Change the NameClaimType\n      options.AddProviderOptions(new ProviderOptions(\"EasyAuthForApplicationsService\"){Enabled = true, NameClaimType = \"Test\"})\n   }\n);\n```\n\nThe `NameClaimType` is the ClaimType of the value which one will be used to fill the `User.Identity.Name` field.\n\n#### Local Debugging advance\n\nFor debugging your application you can place a `me.json` in the `wwwroot/.auth` folder of your web app and add some configuration to the `AddEasyAuth` call.\nFor example:\n\n```json\n\"localProviderOption\": {\n   \"AuthEndpoint\": \".auth/me.json\",\n   \"NameClaimType\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\",\n   \"RoleClaimType\": \"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\"\n}\n```\n\nThis provider automatically deactivate it self in azure, to avoid anonymous access!\n\n\u003e **Info**: You can obtain the content for this file from an Azure Web App with EasyAuth configured by requesting the `/.auth/me` endpoint.\n\n\u003e **Info**: Make sure you added static file handling to your pipeline by adding `app.UseStaticFiles();` to your `public void Configure` method in the `Startup.cs`, e.g. just after `app.UseHttpsRedirection();` entry. Otherwise the static file can not be found at runtime.\n\n\u003e **Info**: Using a `wwwroot` sub-folder name that starts with `'.'`, like the suggested `.auth` folder name, is useful for content relevant only for localhost debugging as these are treated as hidden folders and are not included in publish output.\n\n## Auth Provider\n\nThere are some predefined providers in this package. If you need your own or want contribute to our existing providers you must implement the `IEasyAuthAuthentificationService`.\n\nAll providers can be configured with the following section in the `appsettings.json`\n\n```json\n\"easyAuthOptions\": {\n    \"providerOptions\": [\n      {\n        \"ProviderName\": \"EasyAuthForAuthorizationTokenService\", // type name of the provider\n        \"Enabled\": true,\n        \"NameClaimType\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn\", // optional\n        \"RoleClaimType\": \"roles\" // optional\n      },\n      {\n        \"ProviderName\": \"EasyAuthForAuthorizationTokenService\",\n        \"Enabled\": true\n      },\n      {\n        \"ProviderName\": \"EasyAuthAzureAdService\",\n        \"Enabled\": true\n      },\n      {\n        \"ProviderName\": \"EasyAuthMicrosoftService\",\n        \"Enabled\": true\n      },\n      {\n        \"ProviderName\": \"EasyAuthFacebookService\",\n        \"Enabled\": true\n      },\n      {\n        \"ProviderName\": \"EasyAuthTwitterService\",\n        \"Enabled\": true\n      },\n      {\n        \"ProviderName\": \"EasyAuthGoogleService\",\n        \"Enabled\": true\n      }\n    ],\n    // the following is optional\n    \"localProviderOption\": {\n      \"AuthEndpoint\": \".auth/me.json\",\n      \"NameClaimType\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\",\n      \"RoleClaimType\": \"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\"\n    }\n  }\n```\n\n### `LocalAuthMeService`\n\nThis is a slightly special provider. It does **not** implement the 'IEasyAuthAuthentificationService'. This provider is for development only!\nIt automatic disable it self, if you has configured azure easy auth feature.\nA developer can create a JSON with the content of the `/.auth/me` endpoint of an EasyAuth protected Azure Web App. So you don't need a connection to the internet or azure for development and just use your local things.\nYou must only configure an Azure Web App with Authentication and browse the path:\n\n`https://hostnameOfYourWebSite/.auth/me`\n\nThis endpoint returns a json after the authentication. Put the content in a new file in your `wwwroot` folder. (for example create a path like in the `wwwroot` folder: `.auth/me.json`)\n\nIf you must customize the settings of that provider you can add the section `localProviderOption` to your `appsettings.json`:\n\n```json\n\"localProviderOption\": {\n   \"AuthEndpoint\": \".auth/me\",\n   \"NameClaimType\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\",\n   \"RoleClaimType\": \"http://schemas.microsoft.com/ws/2008/06/identity/claims/role\"\n}\n```\n\n### `EasyAuthForAuthorizationTokenService`\n\nUse this provider if you have a Azure Web App, that is not only be used by humans. For instance if you want to access your app with a Service Principal (SPN).\n\nTo create a Service Principal (SPN), which get access to your EasyAuth protected Application. You have to change the app manifest for you application in your Azure AD. Thanks to [Suzuko123](https://github.com/Suzuko123) for the following sample:\n\n```json\n\"appRoles\": [\n\t{\n\t    \"allowedMemberTypes\": [\n\t\t\t\"Application\"\n\t\t],\n\t    \"description\": \"allow a call as system admin.\",\n\t\t\"displayName\": \"SystemAdmin\",\n\t\t\"id\": \"dd6d2784-5fa1-4c97-9f9b-8376a85b4163\",\n\t\t\"isEnabled\": true,\n\t\t\"lang\": null,\n\t\t\"origin\": \"Application\",\n\t\t\"value\": \"SystemAdmin\"\n\t}\n]\n```\n\nThis will allow a spn to get the role `SystemAdmin` in your protected application. The default `User.Identity.Name` of an SPN is the SPN Guid.\n\n### `EasyAuthAzureAdService`\n\nThis is the most common auth provider. You can use it to work with Azure Active Directory Users in your easy auth application.\n\n### EasyAuthMicrosoftService\n\nIf your users only has personal accounts because your app isn't a bushiness application, use this provider.\n\n### EasyAuthFacebookService\n\nIf your users are primary come from facebook use this provider.\n\n### EasyAuthTwitterService\n\nIf your users are primary come from twitter use this provider.\n\n### EasyAuthGoogleService\n\nIf your users are primary come from twitter use this provider.\n\n## Authors\n\n-   **Kirsten Kluge** - _Initial work_ - [kirkone](https://github.com/kirkone)\n-   **paule96** - _Refactoring / implementing the new stuff_ - [paule96](https://github.com/paule96)\n-   **Christoph Sonntag** - _Made things even more uber_ - [Compufreak345](https://github.com/Compufreak345)\n-   **myusrn** - _Dropped some knowledge about making IsInRoles work_ - [myusrn](https://github.com/myusrn)\n-   **Suzuko123** - _Dropped some knowledge about Service Principals with easy auth_ - [Suzuko123](https://github.com/Suzuko123)\n- **MaximRouiller** - _Dropped the idea to check if the app service is configured right. .[MaximRouiller](https://github.com/MaximRouiller)\n\nSee also the list of [contributors](https://github.com/kirkone/CZ.AspNetCore.EasyAuthAuthentication/graphs/contributors) who participated in this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\n\n## Acknowledgments\n\n-   Inspired by this [StackOverflow post](https://stackoverflow.com/a/42402163/6526640) and this [GitHub](https://github.com/lpunderscore/azureappservice-authentication-middleware) repo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodez-one%2Fcz.aspnetcore.easyauthauthentication","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodez-one%2Fcz.aspnetcore.easyauthauthentication","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodez-one%2Fcz.aspnetcore.easyauthauthentication/lists"}