lsm/openiddict-documentation
1
0
Fork 0
mirror of https://gitee.com/dcren/openiddict-documentation.git synced 2025-09-18 17:48:00 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update the documentation pages

Browse Source
This commit is contained in:
OpenIddict Bot
2021-01-13 04:27:45 +00:00
parent cdb746b17d
commit a17cb26a4b
7 changed files with 8 additions and 787 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
SECURITY.html
View File

@@ -1,106 +0,0 @@
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Security policy </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Security policy ">
<meta name="generator" content="docfx 2.56.6.0">
<link rel="shortcut icon" href="images/favicon.ico">
<link rel="stylesheet" href="styles/docfx.vendor.css">
<link rel="stylesheet" href="styles/docfx.css">
<link rel="stylesheet" href="styles/main.css">
<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
<meta property="docfx:navrel" content="toc.html">
<meta property="docfx:tocrel" content="toc.html">
</head> <body data-spy="scroll" data-target="#affix" data-offset="120">
<div id="wrapper">
<header>
<nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">
<img id="logo" class="svg" src="images/logo.png" alt="">
</a> </div>
<div class="collapse navbar-collapse" id="navbar">
<form class="navbar-form navbar-right" role="search" id="search">
<div class="form-group">
<input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
</div>
</form>
</div>
</div>
</nav>
<div class="subnav navbar navbar-default">
<div class="container hide-when-search" id="breadcrumb">
<ul class="breadcrumb">
<li></li>
</ul>
</div>
</div>
</header>
<div role="main" class="container body-content hide-when-search">
<div class="article row grid">
<div class="col-md-10">
<article class="content wrap" id="_content" data-uid="">
<h1 id="security-policy">Security policy</h1>
<p>Security issues and bugs should be reported privately by emailing security@openiddict.com.
You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message.</p>
<p>Please do not open GitHub issues for anything you think might have a security implication.</p>
</article>
</div>
<div class="hidden-sm col-md-2" role="complementary">
<div class="sideaffix">
<div class="contribution">
<ul class="nav">
<li>
<a href="https://github.com/openiddict/openiddict-documentation/blob/dev/SECURITY.md/#L1" class="contribution-link">Improve this Doc</a>
</li>
</ul>
</div>
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
<h5>In This Article</h5>
<div></div>
</nav>
</div>
</div>
</div>
</div>
<footer>
<div class="grad-bottom"></div>
<div class="footer">
<div class="container">
<span class="pull-right">
<a href="#top">Back to top</a>
</span>
<span>Generated by <strong>DocFX</strong></span>
</div>
</div>
</footer>
</div>
<script type="text/javascript" src="styles/docfx.vendor.js"></script>
<script type="text/javascript" src="styles/docfx.js"></script>
<script type="text/javascript" src="styles/main.js"></script>
</body>
</html>

2
configuration/index.html
View File

@@ -80,7 +80,7 @@
<div class="col-md-4">
<div class="panel panel-default" style="min-height: 120px;">
<div class="panel-body">
<p><strong><a href="token-setup-and-validation.html">Token setup and API validation</a></strong></p>
<p><strong><a href="token-setup-and-validation.md">Token setup and API validation</a></strong></p>
<p>Learn how to change the default token format and register the API token validation components.</p>
</div>
</div>

3
configuration/toc.html
View File

@@ -15,9 +15,6 @@
<li>
<a href="index.html" name="" title="Introduction">Introduction</a>
</li>
<li>
<a href="token-setup-and-validation.html" name="" title="Token setup and API validation">Token setup and API validation</a>
</li>
<li>
<a href="application-permissions.html" name="" title="Application permissions">Application permissions</a>
</li>

456
configuration/token-setup-and-validation.html
View File

@@ -1,456 +0,0 @@
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Token setup and validation </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Token setup and validation ">
<meta name="generator" content="docfx 2.56.6.0">
<link rel="shortcut icon" href="../images/favicon.ico">
<link rel="stylesheet" href="../styles/docfx.vendor.css">
<link rel="stylesheet" href="../styles/docfx.css">
<link rel="stylesheet" href="../styles/main.css">
<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
<meta property="docfx:navrel" content="../toc.html">
<meta property="docfx:tocrel" content="toc.html">
</head> <body data-spy="scroll" data-target="#affix" data-offset="120">
<div id="wrapper">
<header>
<nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../index.html">
<img id="logo" class="svg" src="../images/logo.png" alt="">
</a> </div>
<div class="collapse navbar-collapse" id="navbar">
<form class="navbar-form navbar-right" role="search" id="search">
<div class="form-group">
<input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
</div>
</form>
</div>
</div>
</nav>
<div class="subnav navbar navbar-default">
<div class="container hide-when-search" id="breadcrumb">
<ul class="breadcrumb">
<li></li>
</ul>
</div>
</div>
</header>
<div role="main" class="container body-content hide-when-search">
<div class="sidenav hide-when-search">
<a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
<div class="sidetoggle collapse" id="sidetoggle">
<div id="sidetoc"></div>
</div>
</div>
<div class="article row grid-right">
<div class="col-md-10">
<article class="content wrap" id="_content" data-uid="">
<h1 id="token-setup-and-validation">Token setup and validation</h1>
<p>For an overview of the different token formats, see: <a href="../guide/token-formats.html">here</a></p>
<p>In OpenID Connect there are three types of tokens: access tokens, id tokens, and refresh tokens <a href="https://openid.net/specs/openid-connect-core-1_0.html#Introduction">See spec</a>. When this guide refers to <em>tokens</em> it is referring to access tokens.</p>
<p>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.</p>
<p>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 &#39;/api/User&#39; that returns the current user. A resource server API endpoint for a note-taking app may be &#39;/notes&#39; that returns the user&#39;s notes.</p>
<p>Below shows code snippets for token generation and token validation for each token format.</p>
<h1 id="default-configuration-opaque-tokens">Default configuration: Opaque tokens</h1>
<h2 id="default-token-generation">Default token generation</h2>
<h3 id="authorization-server">Authorization server</h3>
<pre><code class="lang-csharp">// 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&amp;tabs=aspnetcore2x#setapplicationname
services.AddDataProtection()
.PersistKeysToFileSystem(new System.IO.DirectoryInfo(@&quot;[UNC PATH]&quot;))
.SetApplicationName(&quot;[APP NAME]&quot;);
// Register the OpenIddict services.
// Additional configuration is only needed if using Introspection on resource servers
services.AddOpenIddict()
.AddCore(...)
.AddServer(options =&gt;
{
//...
//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(&quot;/connect/introspect&quot;);
})
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//...
//must come before using MVC
app.UseAuthentication();
//...
}
</code></pre><h2 id="default-token-validation">Default token validation</h2>
<h3 id="authorization-server-1">Authorization server</h3>
<pre><code class="lang-csharp">// 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();
//...
}
</code></pre><h3 id="resource-server-shared-aspnet-core-dataprotection">Resource server shared ASP.NET Core DataProtection</h3>
<pre><code class="lang-csharp">// 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&amp;tabs=aspnetcore2x#setapplicationname
services.AddDataProtection()
.PersistKeysToFileSystem(new System.IO.DirectoryInfo(@&quot;[UNC PATH]&quot;))
.SetApplicationName(&quot;[APP NAME]&quot;);
services.AddOpenIddict()
//This adds a &quot;Bearer&quot; authentication scheme
.AddValidation();
//Optionally set Bearer token authentication as default
//services.AddAuthentication(options =&gt;
//{
// options.DefaultAuthenticateScheme = OpenIddictValidationDefaults.AuthenticationScheme;
// options.DefaultChallengeScheme = OpenIddictValidationDefaults.AuthenticationScheme;
//});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//...
//must come before using MVC
app.UseAuthentication();
//...
}
</code></pre><h3 id="resource-server---introspection">Resource server - introspection</h3>
<pre><code class="lang-csharp">// 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 =&gt;
{
options.DefaultScheme = OAuthIntrospectionDefaults.AuthenticationScheme;
})
.AddOAuthIntrospection(options =&gt;
{
//example settings
options.Authority = new Uri(&quot;http://localhost:12345/&quot;);
options.Audiences.Add(&quot;resource-server-1&quot;);
options.ClientId = &quot;resource-server-1&quot;;
options.ClientSecret = &quot;846B62D0-DEF9-4215-A99D-86E6B8DAB342&quot;;
options.RequireHttpsMetadata = false;
// Note: you can override the default name and role claims:
// options.NameClaimType = &quot;custom_name_claim&quot;;
// options.RoleClaimType = &quot;custom_role_claim&quot;;
});
//Optionally set Bearer token authentication as default
//services.AddAuthentication(options =&gt;
//{
// options.DefaultAuthenticateScheme = OAuthIntrospectionDefaults.AuthenticationScheme;
// options.DefaultChallengeScheme = OAuthIntrospectionDefaults.AuthenticationScheme;
//});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//...
//must come before using MVC
app.UseAuthentication();
//...
}
</code></pre><h3 id="api-controller">Api controller</h3>
<pre><code class="lang-csharp">//specify &quot;Bearer&quot; authentication scheme if it&#39;s not set as default
[Authorize(AuthenticationSchemes = OpenIddictValidationDefaults.AuthenticationScheme)]
//or if using introspection on resource server:
// [Authorize(AuthenticationSchemes = OAuthIntrospectionDefaults.AuthenticationScheme)]
public class MyController : Controller
</code></pre><h1 id="reference-token-format">Reference token format</h1>
<h2 id="reference-token-generation">Reference token generation</h2>
<h3 id="authorization-server-2">Authorization server</h3>
<pre><code class="lang-c#">// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
// Register OpenIddict stores
services.AddDbContext&lt;ApplicationDbContext&gt;(options =&gt;
{
options.UseSqlServer(Configuration.GetConnectionString(&quot;DefaultConnection&quot;));
options.UseOpenIddict();
});
// Register the OpenIddict services.
services.AddOpenIddict()
.AddCore(options =&gt;
{
options.UseEntityFrameworkCore()
.UseDbContext&lt;ApplicationDbContext&gt;();
})
.AddServer(options =&gt;
{
//...
options.UseReferenceTokens();
});
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//...
//must come before using MVC
app.UseAuthentication();
//...
}
</code></pre><h2 id="reference-token-validation">Reference token validation</h2>
<h3 id="authorization-server-3">Authorization server</h3>
<pre><code class="lang-c#">// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddOpenIddict()
.AddCore(...) //see above
.AddServer(...) // see above
.AddValidation(options =&gt;
{
options.UseReferenceTokens();
});
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//...
//must come before using MVC
app.UseAuthentication();
//...
}
</code></pre><h3 id="resource-server">Resource server</h3>
<pre><code class="lang-c#">// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
// Register OpenIddict stores
services.AddDbContext&lt;AuthServerDbContext&gt;(options =&gt;
{
options.UseSqlServer(Configuration.GetConnectionString(&quot;AuthServerConnection&quot;));
options.UseOpenIddict();
});
services.AddOpenIddict()
.AddCore(options =&gt;
{
// Register the Entity Framework entities and stores.
options.UseEntityFrameworkCore()
.UseDbContext&lt;AuthServerDbContext&gt;();
})
//This adds a &quot;Bearer&quot; authentication scheme
.AddValidation(options =&gt;
{
options.UseReferenceTokens();
});
//Optionally set Bearer token authentication as default
//services.AddAuthentication(options =&gt;
//{
// options.DefaultAuthenticateScheme = OpenIddictValidationDefaults.AuthenticationScheme;
// options.DefaultChallengeScheme = OpenIddictValidationDefaults.AuthenticationScheme;
//});
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
//...
//must come before using MVC
app.UseAuthentication();
//...
}
</code></pre><h3 id="api-controller-1">Api controller</h3>
<pre><code class="lang-c#">// Note: both OpenIddictValidationDefaults.AuthenticationScheme and JwtBearerDefaults.AuthenticationScheme are &quot;Bearer&quot;
//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
</code></pre><h1 id="jwts">JWTs</h1>
<h2 id="jwt-generation">JWT generation</h2>
<h3 id="authorization-server-4">Authorization server</h3>
<pre><code class="lang-c#">// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddOpenIddict()
.AddCore(...)
.AddServer(options =&gt;
{
//...
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: &quot;AppName.FolderName.certname.pfx&quot;,
password: &quot;anypassword&quot;);
});
}
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&#39;s Resources then make sure it&#39;s published
//&lt;ItemGroup&gt;
// &lt;EmbeddedResource Include=&quot;FolderName\certname.pfx&quot; /&gt;
// &lt;/ItemGroup&gt;
</code></pre><h2 id="jwt-validation">JWT validation</h2>
<h3 id="authorization-server-5">Authorization server</h3>
<div class="WARNING"><h5>Warning</h5><p>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.</p>
</div>
<pre><code class="lang-c#">// 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 =&gt;
{
//Authority must be a url. It does not have a default value.
options.Authority = &quot;this server&#39;s url, e.g. http://localhost:5051/ or https://auth.example.com/&quot;;
options.Audience = &quot;example: auth_server_api&quot;; //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();
//...
}
</code></pre><h3 id="resource-server-1">Resource server</h3>
<pre><code class="lang-c#">// 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 &quot;Bearer&quot;
.AddJwtBearer(options =&gt;
{
//Authority must be a url. It does not have a default value.
options.Authority = &quot;auth server&#39;s url, e.g. http://localhost:5051/ or https://auth.example.com/&quot;;
options.Audience = &quot;example: api_server_1&quot;; //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,
};
});
}
</code></pre><h3 id="api-controller-2">Api controller</h3>
<pre><code class="lang-c#">// Note: both OpenIddictValidationDefaults.AuthenticationScheme and JwtBearerDefaults.AuthenticationScheme are &quot;Bearer&quot;
//If you didn&#39;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
</code></pre></article>
</div>
<div class="hidden-sm col-md-2" role="complementary">
<div class="sideaffix">
<div class="contribution">
<ul class="nav">
<li>
<a href="https://github.com/openiddict/openiddict-documentation/blob/dev/configuration/token-setup-and-validation.md/#L1" class="contribution-link">Improve this Doc</a>
</li>
</ul>
</div>
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
<h5>In This Article</h5>
<div></div>
</nav>
</div>
</div>
</div>
</div>
<footer>
<div class="grad-bottom"></div>
<div class="footer">
<div class="container">
<span class="pull-right">
<a href="#top">Back to top</a>
</span>
<span>Generated by <strong>DocFX</strong></span>
</div>
</div>
</footer>
</div>
<script type="text/javascript" src="../styles/docfx.vendor.js"></script>
<script type="text/javascript" src="../styles/docfx.js"></script>
<script type="text/javascript" src="../styles/main.js"></script>
</body>
</html>

3
guide/toc.html
View File

@@ -24,9 +24,6 @@
<li>
<a href="migration.html" name="" title="Migration guide">Migration guide</a>
</li>
<li>
<a href="token-formats.html" name="" title="Understanding the different token formats">Understanding the different token formats</a>
</li>
</ul>
</div>
</div>

175
guide/token-formats.html
View File

@@ -1,175 +0,0 @@
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Understanding the different token formats </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Understanding the different token formats ">
<meta name="generator" content="docfx 2.56.6.0">
<link rel="shortcut icon" href="../images/favicon.ico">
<link rel="stylesheet" href="../styles/docfx.vendor.css">
<link rel="stylesheet" href="../styles/docfx.css">
<link rel="stylesheet" href="../styles/main.css">
<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
<meta property="docfx:navrel" content="../toc.html">
<meta property="docfx:tocrel" content="toc.html">
</head> <body data-spy="scroll" data-target="#affix" data-offset="120">
<div id="wrapper">
<header>
<nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../index.html">
<img id="logo" class="svg" src="../images/logo.png" alt="">
</a> </div>
<div class="collapse navbar-collapse" id="navbar">
<form class="navbar-form navbar-right" role="search" id="search">
<div class="form-group">
<input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
</div>
</form>
</div>
</div>
</nav>
<div class="subnav navbar navbar-default">
<div class="container hide-when-search" id="breadcrumb">
<ul class="breadcrumb">
<li></li>
</ul>
</div>
</div>
</header>
<div role="main" class="container body-content hide-when-search">
<div class="sidenav hide-when-search">
<a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
<div class="sidetoggle collapse" id="sidetoggle">
<div id="sidetoc"></div>
</div>
</div>
<div class="article row grid-right">
<div class="col-md-10">
<article class="content wrap" id="_content" data-uid="">
<h1 id="understanding-the-different-token-formats">Understanding the different token formats</h1>
<p>OpenIddict can be configured to use three access token formats:</p>
<ul>
<li>opaque tokens (default)</li>
<li>reference tokens</li>
<li>JWTs (Json Web Tokens)</li>
</ul>
<p>Tokens differ in what they look like and how they are validated. The default tokens will work fine in most use cases. There are times, however, where the other token formats would be preferred or required.</p>
<blockquote><p><strong>Note: Identity tokens are always JWTs, according to spec.</strong></p>
</blockquote>
<h2 id="opaque-tokens-default">Opaque tokens (default)</h2>
<p>The default access tokens are opaque tokens. They are encrypted and signed by the authorization server using the ASP.NET Core Data Protection stack. Their contents can only be inspected by the authorization server or another server sharing the same ASP.NET Core Data Protection configuration.</p>
<p>These are &quot;proprietary&quot; tokens that are not meant to be read or verified by a third-party, as the token format is not standard and necessarily relies on symmetric signing and encryption.</p>
<p>We use this format for authorization codes and refresh tokens. They are only meant to be consumed by OpenIddict itself.</p>
<h3 id="benefits">Benefits</h3>
<ul>
<li>No additional configuration required</li>
<li>Uses OpenIddict&#39;s built-in validation</li>
<li>Resource servers can validate tokens without having to contact authorization server if using shared ASP.NET Core DataProtection</li>
<li>Tokens are encrypted so no one can inspect the token, e.g. if tokens somehow end up in your logs somewhere or are intercepted somehow</li>
</ul>
<h3 id="drawbacks">Drawbacks</h3>
<ul>
<li>Proprietary format, so if you add non .NET Core resource servers in the future you need to switch to JWTs for direct validation or use introspection for indirect validation</li>
<li>Claims are stored within the token, which is convenient but token size could get large if there are a lot of claims (probably not an issue in real-world scenarios)</li>
<li>Token expiration is in the token itself, so even if users sign out their tokens will still be valid until they reach their expiration</li>
</ul>
<h3 id="setup-and-api-validation-configuration">Setup and API validation configuration</h3>
<p><a href="../configuration/token-setup-and-validation.html#default-configuration-opaque-tokens">Here</a></p>
<hr>
<h2 id="reference-tokens">Reference tokens</h2>
<p>When using reference token format, authorization codes, access tokens and refresh tokens are stored as ciphertext in the database and a crypto-secure random identifier is returned to the client application.</p>
<h3 id="benefits-1">Benefits</h3>
<ul>
<li>Minimal configuration required</li>
<li>Uses OpenIddict&#39;s built-in validation</li>
<li>Resource servers can validate tokens without having to contact authorization server</li>
<li>Token sizes are very small regardless of number of claims because they only contain ids</li>
<li>Issued tokens are tracked in data store</li>
<li>Can immediately be revoked</li>
</ul>
<h3 id="drawbacks-1">Drawbacks</h3>
<ul>
<li>.NET Core validation only (although someone could write it for other platforms)</li>
<li>Requires a connection to OpenIddict&#39;s data store, e.g. Entity Framework DataContext. Resource servers may not want to have to reference OpenIddict&#39;s database</li>
<li>Because only ids are in the access tokens, a call to the database is required for every request</li>
</ul>
<h3 id="setup-and-api-validation-configuration-1">Setup and API validation configuration</h3>
<p><a href="../configuration/token-setup-and-validation.html#reference-token-format">Here</a></p>
<hr>
<h2 id="jwts-json-web-tokens">JWTs (JSON Web Tokens)</h2>
<p>These are standard tokens verifiable by third parties, used by Azure Active Directory, Auth0, and other valid OAuth 2.0 service. They are signed by the authorization server but their contents are not encrypted so they can be read by anyone.</p>
<h3 id="benefits-2">Benefits</h3>
<ul>
<li>Good to be familiar with JWTs because they are a commonly used access token type in OAuth 2.0 and are also <code>id token</code> type</li>
<li>Plenty of platforms include JWT validation libraries (.NET, PHP, Node, Python, etc)</li>
<li>Future proof</li>
</ul>
<h3 id="drawbacks-2">Drawbacks</h3>
<ul>
<li>Anyone can inspect contents (see <a href="https://jwt.io/">https://jwt.io/</a>), so if token is hanging around in a log somewhere or intercepted somehow all claims or other information in the token can be read, even if token is expired</li>
<li>Claims are stored within the token, which is convenient but token size could get large if there are a lot of claims (probably not an issue in real-world scenarios)</li>
<li>Token expiration is in the token itself, so even if users sign out their tokens will still be valid until they reach their expiration</li>
</ul>
<h3 id="setup-and-api-validation-configuration-2">Setup and API validation configuration</h3>
<p><a href="../configuration/token-setup-and-validation.html#jwts">Here</a></p>
</article>
</div>
<div class="hidden-sm col-md-2" role="complementary">
<div class="sideaffix">
<div class="contribution">
<ul class="nav">
<li>
<a href="https://github.com/openiddict/openiddict-documentation/blob/dev/guide/token-formats.md/#L1" class="contribution-link">Improve this Doc</a>
</li>
</ul>
</div>
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
<h5>In This Article</h5>
<div></div>
</nav>
</div>
</div>
</div>
</div>
<footer>
<div class="grad-bottom"></div>
<div class="footer">
<div class="container">
<span class="pull-right">
<a href="#top">Back to top</a>
</span>
<span>Generated by <strong>DocFX</strong></span>
</div>
</div>
</footer>
</div>
<script type="text/javascript" src="../styles/docfx.vendor.js"></script>
<script type="text/javascript" src="../styles/docfx.js"></script>
<script type="text/javascript" src="../styles/main.js"></script>
</body>
</html>

50
manifest.json
View File

@@ -3,18 +3,6 @@
"source_base_path": "/github/workspace",
"xrefmap": "xrefmap.yml",
"files": [
{
"type": "Conceptual",
"source_relative_path": "SECURITY.md",
"output": {
".html": {
"relative_path": "SECURITY.html",
"hash": "EywQDi/SIKw91YK4YdLOpQ=="
}
},
"is_incremental": false,
"version": ""
},
{
"type": "Conceptual",
"source_relative_path": "configuration/application-permissions.md",
@@ -28,12 +16,15 @@
"version": ""
},
{
"log_codes": [
"InvalidFileLink"
],
"type": "Conceptual",
"source_relative_path": "configuration/index.md",
"output": {
".html": {
"relative_path": "configuration/index.html",
"hash": "phS22gLEe1qVY8bWJfqu+g=="
"hash": "wOymSthH3qputrjOn7ZyNg=="
}
},
"is_incremental": false,
@@ -45,19 +36,7 @@
"output": {
".html": {
"relative_path": "configuration/toc.html",
"hash": "q5VWqYzUY0T5ZU4V2FsTqQ=="
}
},
"is_incremental": false,
"version": ""
},
{
"type": "Conceptual",
"source_relative_path": "configuration/token-setup-and-validation.md",
"output": {
".html": {
"relative_path": "configuration/token-setup-and-validation.html",
"hash": "V/u4BWZZsAbcJ229Atd8Ww=="
"hash": "wN//5mFhXCdCcxKCvR3Wzg=="
}
},
"is_incremental": false,
@@ -117,22 +96,7 @@
"output": {
".html": {
"relative_path": "guide/toc.html",
"hash": "rt8VgwDfiE4itNGfiTxHjA=="
}
},
"is_incremental": false,
"version": ""
},
{
"log_codes": [
"InvalidYamlHeader"
],
"type": "Conceptual",
"source_relative_path": "guide/token-formats.md",
"output": {
".html": {
"relative_path": "guide/token-formats.html",
"hash": "1mdV3WuTa4mzM9yvM6s1Wg=="
"hash": "epsbDuVdI5yEtqtUWQIS9g=="
}
},
"is_incremental": false,
@@ -199,7 +163,7 @@
"ConceptualDocumentProcessor": {
"can_incremental": false,
"incrementalPhase": "build",
"total_file_count": 10,
"total_file_count": 7,
"skipped_file_count": 0
},
"ResourceDocumentProcessor": {