Skip to content
This repository was archived by the owner on Dec 24, 2020. It is now read-only.

Commit a32988f

Browse files
kevinchaletkevinchalet
committed
Update README.md
1 parent 58dba97 commit a32988f

File tree

1 file changed

+100
-94
lines changed

1 file changed

+100
-94
lines changed

‎README.md

+100-94
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
AspNet.Security.OpenIdConnect.Server
22
==================================
33

4-
**AspNet.Security.OpenIdConnect.Server** is an **advanced OAuth2/OpenID Connect server framework** for both ASP.NET Core 1.0 (previously known as ASP.NET 5) and OWIN/Katana, designed to offer a low-level, protocol-first approach.
4+
**AspNet.Security.OpenIdConnect.Server** is an **advanced OAuth2/OpenID Connect server framework** for both ASP.NET Core 1.x/2.x and OWIN/Katana 3.x/4.x, designed to offer a low-level, protocol-first approach.
55

66
**The latest official release can be found on [NuGet](https://www.nuget.org/packages/AspNet.Security.OpenIdConnect.Server) and the nightly builds on [MyGet](https://www.myget.org/gallery/aspnet-contrib)**.
77

@@ -10,113 +10,119 @@ AspNet.Security.OpenIdConnect.Server
1010

1111
## Get started
1212

13-
Based on `OAuthAuthorizationServerMiddleware` from **Katana 3**, **AspNet.Security.OpenIdConnect.Server** exposes similar primitives and can be directly registered in **Startup.cs** using the `UseOpenIdConnectServer` extension method:
13+
Based on `OAuthAuthorizationServerMiddleware` from **Katana**, **AspNet.Security.OpenIdConnect.Server** exposes similar primitives and can be directly registered in **Startup.cs** using the `UseOpenIdConnectServer` extension method:
1414

1515
```csharp
16-
app.UseOpenIdConnectServer(options =>
16+
public void ConfigureServices(IServiceCollection services)
1717
{
18-
// Enable the token endpoint.
19-
options.TokenEndpointPath = "/connect/token";
20-
21-
// Implement OnValidateTokenRequest to support flows using the token endpoint.
22-
options.Provider.OnValidateTokenRequest = context =>
18+
services.AddAuthentication().AddOpenIdConnectServer(options =>
2319
{
24-
// Reject token requests that don't use grant_type=password or grant_type=refresh_token.
25-
if (!context.Request.IsPasswordGrantType() && !context.Request.IsRefreshTokenGrantType())
26-
{
27-
context.Reject(
28-
error: OpenIdConnectConstants.Errors.UnsupportedGrantType,
29-
description: "Only grant_type=password and refresh_token " +
30-
"requests are accepted by this server.");
31-
32-
return Task.FromResult(0);
33-
}
34-
35-
// Note: you can skip the request validation when the client_id
36-
// parameter is missing to support unauthenticated token requests.
37-
// if (string.IsNullOrEmpty(context.ClientId))
38-
// {
39-
// context.Skip();
40-
//
41-
// return Task.FromResult(0);
42-
// }
43-
44-
// Note: to mitigate brute force attacks, you SHOULD strongly consider applying
45-
// a key derivation function like PBKDF2 to slow down the secret validation process.
46-
// You SHOULD also consider using a time-constant comparer to prevent timing attacks.
47-
if (string.Equals(context.ClientId, "client_id", StringComparison.Ordinal) &&
48-
string.Equals(context.ClientSecret, "client_secret", StringComparison.Ordinal))
20+
// Enable the token endpoint.
21+
options.TokenEndpointPath = "/connect/token";
22+
23+
// Implement OnValidateTokenRequest to support flows using the token endpoint.
24+
options.Provider.OnValidateTokenRequest = context =>
4925
{
50-
context.Validate();
51-
}
52-
53-
// Note: if Validate() is not explicitly called,
54-
// the request is automatically rejected.
55-
return Task.FromResult(0);
56-
};
57-
58-
// Implement OnHandleTokenRequest to support token requests.
59-
options.Provider.OnHandleTokenRequest = context =>
60-
{
61-
// Only handle grant_type=password token requests and let the
62-
// OpenID Connect server middleware handle the other grant types.
63-
if (context.Request.IsPasswordGrantType())
64-
{
65-
// Implement context.Request.Username/context.Request.Password validation here.
66-
// Note: you can call context Reject() to indicate that authentication failed.
67-
// Using password derivation and time-constant comparer is STRONGLY recommended.
68-
if (!string.Equals(context.Request.Username, "Bob", StringComparison.Ordinal) ||
69-
!string.Equals(context.Request.Password, "P@ssw0rd", StringComparison.Ordinal))
26+
// Reject token requests that don't use grant_type=password or grant_type=refresh_token.
27+
if (!context.Request.IsPasswordGrantType() && !context.Request.IsRefreshTokenGrantType())
7028
{
7129
context.Reject(
72-
error: OpenIdConnectConstants.Errors.InvalidGrant,
73-
description: "Invalid user credentials.");
74-
75-
return Task.FromResult(0);
30+
error: OpenIdConnectConstants.Errors.UnsupportedGrantType,
31+
description: "Only grant_type=password and refresh_token " +
32+
"requests are accepted by this server.");
33+
34+
return Task.CompletedTask;
7635
}
77-
78-
var identity = new ClaimsIdentity(context.Options.AuthenticationScheme,
79-
OpenIdConnectConstants.Claims.Name,
80-
OpenIdConnectConstants.Claims.Role);
81-
82-
// Add the mandatory subject/user identifier claim.
83-
identity.AddClaim(OpenIdConnectConstants.Claims.Subject, "[unique id]");
84-
85-
// By default, claims are not serialized in the access/identity tokens.
86-
// Use the overload taking a "destinations" parameter to make sure
87-
// your claims are correctly inserted in the appropriate tokens.
88-
identity.AddClaim("urn:customclaim", "value",
89-
OpenIdConnectConstants.Destinations.AccessToken,
90-
OpenIdConnectConstants.Destinations.IdentityToken);
91-
92-
var ticket = new AuthenticationTicket(
93-
new ClaimsPrincipal(identity),
94-
new AuthenticationProperties(),
95-
context.Options.AuthenticationScheme);
96-
97-
// Call SetScopes with the list of scopes you want to grant
98-
// (specify offline_access to issue a refresh token).
99-
ticket.SetScopes(
100-
OpenIdConnectConstants.Scopes.Profile,
101-
OpenIdConnectConstants.Scopes.OfflineAccess);
102-
103-
context.Validate(ticket);
104-
}
105-
106-
return Task.FromResult(0);
107-
};
108-
});
36+
37+
// Note: you can skip the request validation when the client_id
38+
// parameter is missing to support unauthenticated token requests.
39+
// if (string.IsNullOrEmpty(context.ClientId))
40+
// {
41+
// context.Skip();
42+
//
43+
// return Task.CompletedTask;
44+
// }
45+
46+
// Note: to mitigate brute force attacks, you SHOULD strongly consider applying
47+
// a key derivation function like PBKDF2 to slow down the secret validation process.
48+
// You SHOULD also consider using a time-constant comparer to prevent timing attacks.
49+
if (string.Equals(context.ClientId, "client_id", StringComparison.Ordinal) &&
50+
string.Equals(context.ClientSecret, "client_secret", StringComparison.Ordinal))
51+
{
52+
context.Validate();
53+
}
54+
55+
// Note: if Validate() is not explicitly called,
56+
// the request is automatically rejected.
57+
return Task.CompletedTask;
58+
};
59+
60+
// Implement OnHandleTokenRequest to support token requests.
61+
options.Provider.OnHandleTokenRequest = context =>
62+
{
63+
// Only handle grant_type=password token requests and let
64+
// the OpenID Connect server handle the other grant types.
65+
if (context.Request.IsPasswordGrantType())
66+
{
67+
// Implement context.Request.Username/context.Request.Password validation here.
68+
// Note: you can call context Reject() to indicate that authentication failed.
69+
// Using password derivation and time-constant comparer is STRONGLY recommended.
70+
if (!string.Equals(context.Request.Username, "Bob", StringComparison.Ordinal) ||
71+
!string.Equals(context.Request.Password, "P@ssw0rd", StringComparison.Ordinal))
72+
{
73+
context.Reject(
74+
error: OpenIdConnectConstants.Errors.InvalidGrant,
75+
description: "Invalid user credentials.");
76+
77+
return Task.CompletedTask;
78+
}
79+
80+
var identity = new ClaimsIdentity(context.Scheme.Name,
81+
OpenIdConnectConstants.Claims.Name,
82+
OpenIdConnectConstants.Claims.Role);
83+
84+
// Add the mandatory subject/user identifier claim.
85+
identity.AddClaim(OpenIdConnectConstants.Claims.Subject, "[unique id]");
86+
87+
// By default, claims are not serialized in the access/identity tokens.
88+
// Use the overload taking a "destinations" parameter to make sure
89+
// your claims are correctly inserted in the appropriate tokens.
90+
identity.AddClaim("urn:customclaim", "value",
91+
OpenIdConnectConstants.Destinations.AccessToken,
92+
OpenIdConnectConstants.Destinations.IdentityToken);
93+
94+
var ticket = new AuthenticationTicket(
95+
new ClaimsPrincipal(identity),
96+
new AuthenticationProperties(),
97+
context.Scheme.Name);
98+
99+
// Call SetScopes with the list of scopes you want to grant
100+
// (specify offline_access to issue a refresh token).
101+
ticket.SetScopes(
102+
OpenIdConnectConstants.Scopes.Profile,
103+
OpenIdConnectConstants.Scopes.OfflineAccess);
104+
105+
context.Validate(ticket);
106+
}
107+
108+
return Task.CompletedTask;
109+
};
110+
});
111+
}
109112
```
110113

111-
> Note: in order for the OpenID Connect server middleware to work properly, **the authentication services must be registered in the DI container**:
114+
> Note: in order for the OpenID Connect server to work properly, **the authentication middleware must be registered in the ASP.NET Core 2.0 pipeline**:
112115
113116
```csharp
114-
public void ConfigureServices(IServiceCollection services)
117+
public void Configure(IApplicationBuilder app)
115118
{
116-
services.AddAuthentication();
119+
app.UseAuthentication();
117120
}
118121
```
119122

123+
> Note: **the AspNet.Security.OpenIdConnect.Server 2.x packages are only compatible with ASP.NET Core 2.x**.
124+
> If your application targets ASP.NET Core 1.x, use the AspNet.Security.OpenIdConnect.Server 1.x packages.
125+
120126
## Resources
121127

122128
**Looking for additional resources to help you get started?** Don't miss these interesting blog posts:
@@ -127,9 +133,9 @@ public void ConfigureServices(IServiceCollection services)
127133

128134
The samples found [in the current project](./samples/) directory always target the latest ASP.NET Core releases and are mainly meant to ease its testing.
129135

130-
**Official samples targetting ASP.NET Core 1.0 RTM** can be found on [aspnet-contrib/AspNet.Security.OpenIdConnect.Samples](https://github.com/aspnet-contrib/AspNet.Security.OpenIdConnect.Samples).
136+
**Official samples targetting ASP.NET Core** can be found on [aspnet-contrib/AspNet.Security.OpenIdConnect.Samples](https://github.com/aspnet-contrib/AspNet.Security.OpenIdConnect.Samples).
131137

132-
**Looking for something simpler?** Don't miss **[OpenIddict](https://github.com/openiddict/core)**, the **simple and easy-to-use OpenID Connect server for ASP.NET Core 1.0** based on AspNet.Security.OpenIdConnect.Server and ASP.NET Core Identity.
138+
**Looking for something simpler?** Don't miss **[OpenIddict](https://github.com/openiddict/core)**, the **simple and easy-to-use OpenID Connect server for ASP.NET Core 1.x and 2.0** based on AspNet.Security.OpenIdConnect.Server.
133139

134140
## Support
135141

0 commit comments

Comments
 (0)