From 9ea01758ac8027eee5e6fee9341a80997216e5d5 Mon Sep 17 00:00:00 2001 From: OpenIddict Bot <32257313+openiddict-bot@users.noreply.github.com> Date: Fri, 7 Sep 2018 12:19:09 +0000 Subject: [PATCH] Update the documentation pages --- .../application-permissions.html | 24 +- .../token-setup-and-validation.html | 456 ++++++++++++++++++ {guide => docs/guide}/getting-started.html | 24 +- {guide => docs/guide}/index.html | 24 +- {guide => docs/guide}/migration.html | 26 +- {guide => docs/guide}/samples.html | 24 +- docs/guide/token-formats.html | 175 +++++++ {features => docs}/toc.html | 37 +- features/index.html | 119 ----- guide/toc.html | 125 ----- index.html | 8 +- manifest.json | 152 +++--- toc.html | 8 +- 13 files changed, 805 insertions(+), 397 deletions(-) rename {features => docs/configuration}/application-permissions.html (92%) create mode 100644 docs/configuration/token-setup-and-validation.html rename {guide => docs/guide}/getting-started.html (92%) rename {guide => docs/guide}/index.html (85%) rename {guide => docs/guide}/migration.html (95%) rename {guide => docs/guide}/samples.html (82%) create mode 100644 docs/guide/token-formats.html rename {features => docs}/toc.html (69%) delete mode 100644 features/index.html delete mode 100644 guide/toc.html diff --git a/features/application-permissions.html b/docs/configuration/application-permissions.html similarity index 92% rename from features/application-permissions.html rename to docs/configuration/application-permissions.html index a9bad10..58348d2 100644 --- a/features/application-permissions.html +++ b/docs/configuration/application-permissions.html @@ -10,12 +10,12 @@ - - - - - - + + + + + + @@ -34,8 +34,8 @@ - - + + - - - + + + diff --git a/docs/configuration/token-setup-and-validation.html b/docs/configuration/token-setup-and-validation.html new file mode 100644 index 0000000..ff1288b --- /dev/null +++ b/docs/configuration/token-setup-and-validation.html @@ -0,0 +1,456 @@ + + + + + + + + Token setup and validation + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+ +
+ +
+
+
+
+
+
+
+

Token setup and validation

+ +

For an overview of the different token formats, see: here

+

In OpenID Connect there are three types of tokens: access tokens, id tokens, and refresh tokens See spec. When this guide refers to tokens it is referring to access tokens.

+

Authorization servers are responsible for token generation. Clients (server app or web app) request tokens and then use tokens to request resources. For example, a javascript web application may make API calls that require authorization, so the token is sent along in the header of every request.

+

Token validation needs to be configured for servers that have API endpoints that require authorization. This could be authorization servers or standalone servers, called resource servers. An example authorization server API endpoint may be '/api/User' that returns the current user. A resource server API endpoint for a note-taking app may be '/notes' that returns the user's notes.

+

Below shows code snippets for token generation and token validation for each token format.

+

Default configuration: Opaque tokens

+

Default token generation

+

Authorization server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    //If tokens need to be validated in a separate resource server, configure a shared ASP.NET Core DataProtection with shared key store and application name
+    //See https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-2.1&tabs=aspnetcore2x#setapplicationname
+    services.AddDataProtection()
+        .PersistKeysToFileSystem(new System.IO.DirectoryInfo(@"[UNC PATH]"))
+        .SetApplicationName("[APP NAME]");
+
+    // Register the OpenIddict services.
+    // Additional configuration is only needed if using Introspection on resource servers
+    services.AddOpenIddict()
+        .AddCore(...)
+
+        .AddServer(options => 
+        {
+            //...
+            //This is required if using introspection on resource servers
+            //This is not needed if resource servers will use shared ASP.NET Core DataProtection
+            //options.EnableIntrospectionEndpoint("/connect/introspect");
+        })
+}
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+
+    //must come before using MVC
+    app.UseAuthentication();
+
+    //...
+}
+

Default token validation

+

Authorization server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddOpenIddict()
+        .AddCore(...)
+
+        .AddServer(...)
+
+        .AddValidation();
+}
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Resource server shared ASP.NET Core DataProtection

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    //If tokens need to be validated in a separate resource server, configure a shared ASP.NET Core DataProtection with shared key store and application name
+    //See https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-2.1&tabs=aspnetcore2x#setapplicationname
+    services.AddDataProtection()
+        .PersistKeysToFileSystem(new System.IO.DirectoryInfo(@"[UNC PATH]"))
+        .SetApplicationName("[APP NAME]");
+
+    services.AddOpenIddict()
+        //This adds a "Bearer" authentication scheme
+        .AddValidation();
+
+    //Optionally set Bearer token authentication as default
+    //services.AddAuthentication(options =>
+    //{
+    //    options.DefaultAuthenticateScheme = OpenIddictValidationDefaults.AuthenticationScheme;
+    //    options.DefaultChallengeScheme = OpenIddictValidationDefaults.AuthenticationScheme;
+    //});
+}
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Resource server - introspection

+
// Introspection requires a request to auth server for every token so shared ASP.NET Core DataProtection is preferred.
+// To use introspection, you need to create a new client application and grant it the introspection endpoint permission.
+// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddAuthentication(options =>
+    {
+        options.DefaultScheme = OAuthIntrospectionDefaults.AuthenticationScheme;
+    })
+    .AddOAuthIntrospection(options =>
+    {
+        //example settings
+        options.Authority = new Uri("http://localhost:12345/");
+        options.Audiences.Add("resource-server-1");
+        options.ClientId = "resource-server-1";
+        options.ClientSecret = "846B62D0-DEF9-4215-A99D-86E6B8DAB342";
+        options.RequireHttpsMetadata = false;
+
+        // Note: you can override the default name and role claims:
+        // options.NameClaimType = "custom_name_claim";
+        // options.RoleClaimType = "custom_role_claim";
+    });
+
+    //Optionally set Bearer token authentication as default
+    //services.AddAuthentication(options =>
+    //{
+    //    options.DefaultAuthenticateScheme = OAuthIntrospectionDefaults.AuthenticationScheme;
+    //    options.DefaultChallengeScheme = OAuthIntrospectionDefaults.AuthenticationScheme;
+    //});
+}
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Api controller

+
//specify "Bearer" authentication scheme if it's not set as default
+[Authorize(AuthenticationSchemes = OpenIddictValidationDefaults.AuthenticationScheme)]
+//or if using introspection on resource server: 
+// [Authorize(AuthenticationSchemes = OAuthIntrospectionDefaults.AuthenticationScheme)]
+public class MyController : Controller
+

Reference token format

+

Reference token generation

+

Authorization server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    // Register OpenIddict stores
+    services.AddDbContext<ApplicationDbContext>(options =>
+    {
+        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"));
+        options.UseOpenIddict();
+    });
+
+    // Register the OpenIddict services.
+    services.AddOpenIddict()
+    .AddCore(options =>
+    {
+        options.UseEntityFrameworkCore()
+            .UseDbContext<ApplicationDbContext>();
+    })
+
+    .AddServer(options => 
+    {
+        //...
+        options.UseReferenceTokens();
+    });
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Reference token validation

+

Authorization server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddOpenIddict()
+        .AddCore(...) //see above
+
+        .AddServer(...) // see above
+
+        .AddValidation(options => 
+        {
+            options.UseReferenceTokens();
+        });
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Resource server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    // Register OpenIddict stores
+    services.AddDbContext<AuthServerDbContext>(options =>
+    {
+        options.UseSqlServer(Configuration.GetConnectionString("AuthServerConnection"));
+        options.UseOpenIddict();
+    });
+
+
+    services.AddOpenIddict()
+    .AddCore(options =>
+    {
+        // Register the Entity Framework entities and stores.
+        options.UseEntityFrameworkCore()
+               .UseDbContext<AuthServerDbContext>();
+    })
+
+    //This adds a "Bearer" authentication scheme
+    .AddValidation(options => 
+    {
+        options.UseReferenceTokens();
+    });
+
+    //Optionally set Bearer token authentication as default
+    //services.AddAuthentication(options =>
+    //{
+    //    options.DefaultAuthenticateScheme = OpenIddictValidationDefaults.AuthenticationScheme;
+    //    options.DefaultChallengeScheme = OpenIddictValidationDefaults.AuthenticationScheme;
+    //});
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Api controller

+
// Note: both OpenIddictValidationDefaults.AuthenticationScheme and JwtBearerDefaults.AuthenticationScheme are "Bearer"
+//If you did not set the default authentication scheme then specify it here.
+//If you get a 302 redirect to login page instead of a 401 Unauthorized then Cookie authentication is handling the request
+//so scheme must be specified
+[Authorize(AuthenticationSchemes = OpenIddictValidationDefaults.AuthenticationScheme)]
+public class MyController : Controller
+

JWTs

+

JWT generation

+

Authorization server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddOpenIddict()
+        .AddCore(...)
+
+        .AddServer(options =>
+        {
+            //...
+            options.UseJsonWebTokens();
+            //JWTs must be signed by a self-signing certificate or a symmetric key
+            //Here a certificate is used. I used IIS to create a self-signed certificate
+            //and saved it in /FolderName folder. See below for .csproj configuration
+            options.AddSigningCertificate(
+                    assembly: typeof(Startup).GetTypeInfo().Assembly,
+                    resource: "AppName.FolderName.certname.pfx",
+                    password: "anypassword");
+
+        });
+}
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+
+// .csproj
+// if using a certificate and its stored in your app's Resources then make sure it's published
+//<ItemGroup>
+//    <EmbeddedResource Include="FolderName\certname.pfx" />
+//  </ItemGroup>
+

JWT validation

+

Authorization server

+
Warning

Remember, this is only needed if you have API endpoints that require token authorization. If your authorization server generates tokens that are only used by separate resource servers, then this is not needed.

+
+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    //this must come after registering ASP.NET Core Identity
+    JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
+    JwtSecurityTokenHandler.DefaultOutboundClaimTypeMap.Clear();
+    services.AddAuthentication()
+        .AddJwtBearer(options =>
+        {
+            //Authority must be a url. It does not have a default value.
+            options.Authority = "this server's url, e.g. http://localhost:5051/ or https://auth.example.com/";
+            options.Audience = "example: auth_server_api"; //This must be included in ticket creation
+            options.RequireHttpsMetadata = false;
+            options.IncludeErrorDetails = true; //
+            options.TokenValidationParameters = new TokenValidationParameters()
+            {
+                NameClaimType = OpenIdConnectConstants.Claims.Subject,
+                RoleClaimType = OpenIdConnectConstants.Claims.Role,
+            };
+        });
+}
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    //...
+    //must come before using MVC
+    app.UseAuthentication();
+    //...
+}
+

Resource server

+
// Startup.cs
+
+public void ConfigureServices(IServiceCollection services)
+{
+    JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
+    JwtSecurityTokenHandler.DefaultOutboundClaimTypeMap.Clear();
+    //Add authentication and set default authentication scheme
+    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) //same as "Bearer"
+        .AddJwtBearer(options =>
+        {
+            //Authority must be a url. It does not have a default value.
+            options.Authority = "auth server's url, e.g. http://localhost:5051/ or https://auth.example.com/";
+            options.Audience = "example: api_server_1"; //This must be included in ticket creation
+            options.RequireHttpsMetadata = false;
+            options.IncludeErrorDetails = true; //
+            options.TokenValidationParameters = new TokenValidationParameters()
+            {
+                NameClaimType = OpenIdConnectConstants.Claims.Subject,
+                RoleClaimType = OpenIdConnectConstants.Claims.Role,
+            };
+        });
+}
+

Api controller

+
// Note: both OpenIddictValidationDefaults.AuthenticationScheme and JwtBearerDefaults.AuthenticationScheme are "Bearer"
+//If you didn't set the default authentication scheme then specify it here.
+//If you get a 302 redirect to login page instead of a 401 Unauthorized then Cookie authentication is handling the request
+//so scheme must be specified
+[Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
+public class MyController : Controller
+
+
+ + +
+
+ + +
+ + + + + + diff --git a/guide/getting-started.html b/docs/guide/getting-started.html similarity index 92% rename from guide/getting-started.html rename to docs/guide/getting-started.html index 31456fe..c8410c8 100644 --- a/guide/getting-started.html +++ b/docs/guide/getting-started.html @@ -10,12 +10,12 @@ - - - - - - + + + + + + @@ -34,8 +34,8 @@ - - + + - - - + + + diff --git a/guide/index.html b/docs/guide/index.html similarity index 85% rename from guide/index.html rename to docs/guide/index.html index 11af666..9b903db 100644 --- a/guide/index.html +++ b/docs/guide/index.html @@ -10,12 +10,12 @@ - - - - - - + + + + + + @@ -34,8 +34,8 @@ - - + + - - - + + + diff --git a/guide/migration.html b/docs/guide/migration.html similarity index 95% rename from guide/migration.html rename to docs/guide/migration.html index 0241c9a..560ecdd 100644 --- a/guide/migration.html +++ b/docs/guide/migration.html @@ -10,12 +10,12 @@ - - - - - - + + + + + + @@ -34,8 +34,8 @@ - - + +