You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> **INFO**: For detailed usage information please have a look in the `samples` folder.
39
-
40
-
### Startup.cs
41
-
42
-
Add something like this in the `public void ConfigureServices` method:
38
+
In 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`.
and this to the `public void Configure`method before `app.UseMvc...`:
50
+
The 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`:
55
51
56
52
```csharp
57
53
app.UseAuthentication();
58
54
```
59
55
60
-
This will enable the `EasyAuthAuthenticationHandler` in your app.
56
+
> Warning: make sure you add the `UseAuthentication` in the right order for your use case.
57
+
58
+
The last thing is to add the following section in the `appsettings.json` to enabled the basic providers:
After this you can use your app can translate the claims of easy auth for azure AD by it's own.
61
76
62
-
### Controller.cs
77
+
### Configure Azure App Service
63
78
64
-
In your controllers you can access the `User` property as usual:
79
+
In 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!
80
+
81
+
> Information: for current documentation about this azure feature see [here](https://docs.microsoft.com/en-us/azure/app-service/overview-authentication-authorization).
82
+
83
+
The first step is enable the authentication feature in azure. It is important to disabled anonymous requests!
Then you need the connection to your azure active directory. (other providers currently not implemented)
88
+
89
+
90
+
91
+
Save all and publish your app. This allows you to use the user claim in you app like:
65
92
66
93
```csharp
67
94
[Authorize]
@@ -75,6 +102,20 @@ public string UserName()
75
102
}
76
103
```
77
104
105
+
### Local Debugging
106
+
107
+
> Information: for this step it is required to have an configured app service!
108
+
109
+
This 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:
110
+
111
+
`https://yourAzureAppServiceUrl/.auth/me`
112
+
113
+
The 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.
114
+
115
+
> Important: You must enable `UseStaticFiles` in your `Startup`. This is the case in the default ASP.NET frontend project.
116
+
117
+
## Details of the implementation
118
+
78
119
### Adding custom roles
79
120
80
121
If 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.
@@ -85,7 +126,7 @@ You can use the default behavior of asp.net core to configure EasyAuth. You must
85
126
86
127
> To get the property `this.Configuration` in your `Startup.cs` you must add `IConfiguration configuration` to your constructor parameters and create a property.
87
128
88
-
To 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/).)
129
+
To 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/).)
89
130
90
131
```json
91
132
"easyAuthOptions": {
@@ -112,7 +153,7 @@ Here are some notes to the JSON above:
112
153
- each provider is disabled by default so you must enabled it
113
154
- 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.)
114
155
- The `ProviderName` is the class name of the provider. that must be unique in your application.
115
-
- The xClaimType property only define the property in the token that provide the requiered informations. Internaly that will always mapped to **name** and **role** claims.
156
+
- 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.
116
157
117
158
> A list of all providers can be found in the headline `Auth Provider`
118
159
@@ -125,8 +166,6 @@ You can provide additional options for the middleware:
125
166
```csharp
126
167
).AddEasyAuth(
127
168
options=> {
128
-
// Override the auth endpoint
129
-
options.AuthEndpoint=ClaimTypes.Email;
130
169
// Add the EasyAuthForApplicationService auth provider and enabled it. Also Change the NameClaimType
@@ -135,47 +174,82 @@ You can provide additional options for the middleware:
135
174
136
175
The `NameClaimType` is the ClaimType of the value which one will be used to fill the `User.Identity.Name` field.
137
176
138
-
#### Local Debugging
177
+
#### Local Debugging advance
139
178
140
179
For 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.
This provider automatically deactivate it self in azure, to avoid anonymous access!
191
+
155
192
> **Info**: You can obtain the content for this file from an Azure Web App with EasyAuth configured by requesting the `/.auth/me` endpoint.
156
193
157
194
> **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.
158
195
159
-
> **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.
196
+
> **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.
160
197
161
198
## Auth Provider
162
199
163
200
There are some predefined providers in this package. If you need your own or want contribute to our existing providers you must implement the `IEasyAuthAuthentificationService`.
164
201
165
-
### `EasyAuthWithAuthMeService`
202
+
All providers can be configured with the following section in the `appsettings.json`
203
+
204
+
```json
205
+
"easyAuthOptions": {
206
+
"providerOptions": [
207
+
{
208
+
"ProviderName": "EasyAuthForAuthorizationTokenService", // type name of the provider
This is a slightly special provider. This provider cannot be configured. You can only turn it on or off. It also does **not** implement the 'IEasyAuthAuthentificationService'. This provider is for development.
168
-
It automatic disable it selfes, if you has configured azure easy auth feature.
169
-
A developer can create a JSON with the content of the `/.auth/me` endpoint of an EasyAuth Azure Web App. So you don't need a connection to the internet or azure for development and just use your local things.
170
-
You must only configure an Azure Web App with Authentification and browse the path:
231
+
This is a slightly special provider. It does **not** implement the 'IEasyAuthAuthentificationService'. This provider is for development only!
232
+
It automatic disable it self, if you has configured azure easy auth feature.
233
+
A 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.
234
+
You must only configure an Azure Web App with Authentication and browse the path:
171
235
172
236
`https://hostnameOfYourWebSite/.auth/me`
173
237
174
-
This endpoint return a json after the authentication. Put the content in a new file in your `wwwroot`folder. (create the same path like: `.auth/me.json`)
238
+
This 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`)
239
+
240
+
If you must customize the settings of that provider you can add the section `localProviderOption` to your `appsettings.json`:
Use 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).
252
+
Use 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).
179
253
180
254
To 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:
181
255
@@ -205,7 +279,7 @@ This is the most common auth provider. You can use it to work with Azure Active
0 commit comments