lsm/openiddict-documentation
1
0
Fork 0
mirror of https://gitee.com/dcren/openiddict-documentation.git synced 2025-07-18 04:33:19 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
92e1a749d6
openiddict-documentation/configuration/token-formats.html

192 lines
11 KiB
HTML
Raw Normal View History

Update the documentation pages
2022-01-08 01:11:48 +08:00
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2021-01-26 00:29:29 +08:00
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Token formats </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Token formats ">
Update the documentation pages
2023-05-03 03:58:39 +08:00
<meta name="generator" content="docfx 2.56.7.0">
Update the documentation pages
2021-01-26 00:29:29 +08:00
<link rel="shortcut icon" href="../images/favicon.ico">
Update the documentation pages
2022-01-08 01:11:48 +08:00
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/night-owl.min.css">
<link rel="stylesheet" href="../styles/colors.css">
<link rel="stylesheet" href="../styles/discord.css">
Update the documentation pages
2021-01-26 00:29:29 +08:00
<link rel="stylesheet" href="../styles/main.css">
<meta property="docfx:navrel" content="../toc.html">
<meta property="docfx:tocrel" content="toc.html">
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
</head>
<body>
<div class="top-navbar">
<a href="javascript:void(0);" class="burger-icon" onclick="toggleMenu()">
<svg name="Hamburger" style="vertical-align: middle;" width="24" height="24" viewbox="0 0 24 24"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M20 6H4V9H20V6ZM4 10.999H20V13.999H4V10.999ZM4 15.999H20V18.999H4V15.999Z"></path></svg>
</a>
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
<a class="brand" href="../index.html">
Update the documentation pages
2022-01-08 01:58:08 +08:00
<img src="../images/logo.png" alt="OpenIddict" class="logomark">
<span class="brand-title">OpenIddict</span>
Update the documentation pages
2022-01-08 01:11:48 +08:00
</a>
</div>
<div class="body-content">
<div id="blackout" class="blackout" onclick="toggleMenu()"></div>
<nav id="sidebar" role="navigation">
<div class="sidebar">
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
<div>
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
<a class="brand" href="../index.html">
Update the documentation pages
2022-01-08 01:58:08 +08:00
<img src="../images/logo.png" alt="OpenIddict" class="logomark">
<span class="brand-title">OpenIddict</span>
Update the documentation pages
2022-01-08 01:11:48 +08:00
</a>
<div id="navbar">
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
</div>
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
</div>
<div class="sidebar-item-separator"></div>
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
<div id="sidetoggle">
<div id="sidetoc"></div>
</div>
</div>
<div class="footer">
Update the documentation pages
2023-05-03 03:58:39 +08:00
<span>Generated by <strong>DocFX</strong></span>
Update the documentation pages
2022-01-08 01:11:48 +08:00
</div>
</nav>
<main class="main-panel">
<div role="main" class="hide-when-search">
Update the documentation pages
2023-05-03 03:58:39 +08:00
Update the documentation pages
2022-01-08 01:11:48 +08:00
<div class="subnav navbar navbar-default">
<div class="container hide-when-search" id="breadcrumb">
<ul class="breadcrumb">
<li></li>
</ul>
</div>
</div>
<article class="content wrap" id="_content" data-uid="">
Update the documentation pages
2021-01-26 00:29:29 +08:00
<h1 id="token-formats">Token formats</h1>
Update the documentation pages
2023-05-03 03:58:39 +08:00
<div class="NOTE"><h5>Note</h5><p>In OpenIddict 3.0, the ability to revoke a token is not tied to the token format and doesn&#39;t require enabling reference tokens:
Update the documentation pages
2022-01-08 01:58:08 +08:00
regular JWT or ASP.NET Core Data Protection tokens can be revoked as long as token storage is not explicitly disabled in the server options.</p>
Update the documentation pages
2021-01-26 04:31:56 +08:00
<p>For more information about reference tokens, read <a href="token-storage.html">Token storage</a>.</p>
Update the documentation pages
2021-01-26 04:42:38 +08:00
</div>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<h2 id="json-web-token">JSON Web Token</h2>
Update the documentation pages
2021-01-26 00:39:38 +08:00
<p>OpenIddict 3.0 implements the <a href="https://tools.ietf.org/html/rfc7519">JSON Web Token</a>, <a href="https://tools.ietf.org/html/rfc7515">JSON Web Signature</a>
and <a href="https://tools.ietf.org/html/rfc7516">JSON Web Encryption</a> standards and relies on the
Update the documentation pages
2021-01-26 00:29:29 +08:00
<a href="https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/">Azure Active Directory IdentityModel Extensions for .NET library</a>
Update the documentation pages
2021-01-26 00:39:38 +08:00
developed and maintained by Microsoft to generate signed and encrypted tokens using the credentials registered in the server options.</p>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<h3 id="jwt-token-types">JWT token types</h3>
<p>To protect against token substitution and confused deputy attacks, <strong>OpenIddict 3.0 uses the standard <code>typ</code> JWT header to convey the actual token type</strong>.
This mechanism replaces the private <code>token_usage</code> claim used for the same purpose in previous versions of OpenIddict.</p>
Update the documentation pages
2022-01-08 00:01:25 +08:00
<p>As required by the <a href="https://datatracker.ietf.org/doc/html/rfc9068">JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens specification</a>,
Update the documentation pages
2021-01-26 00:29:29 +08:00
<strong>access tokens produced by OpenIddict 3.0 are always issued with a <code>&quot;typ&quot;: &quot;at+jwt&quot;</code> header</strong> while identity tokens still use <code>&quot;typ&quot;: &quot;JWT&quot;</code> for backward compatibility.
Update the documentation pages
2023-05-03 03:58:39 +08:00
Other types of tokens – only accepted by OpenIddict&#39;s own endpoints – use private token types prefixed by <code>oi_</code>.</p>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<h3 id="disabling-jwt-access-token-encryption">Disabling JWT access token encryption</h3>
<p>By default, <strong>OpenIddict enforces encryption for all the token types it supports</strong>. While this enforcement cannot be disabled for authorization codes,
refresh tokens and device codes for security reasons, it can be relaxed for access tokens when integration with third-party APIs/resource servers is desired.
Update the documentation pages
2023-05-03 03:58:39 +08:00
Access token encryption can also be disabled if the resource servers receiving the access tokens don&#39;t fully support JSON Web Encryption.</p>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<pre><code class="lang-csharp">services.AddOpenIddict()
.AddServer(options =&gt;
{
options.DisableAccessTokenEncryption();
});
Update the documentation pages
2023-05-03 03:58:39 +08:00
</code></pre><h2 id="aspnet-core-data-protection">ASP.NET Core Data Protection</h2>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<p>OpenIddict 3.0 can also be configured to use <a href="https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/introduction">ASP.NET Core Data Protection</a> to create
Update the documentation pages
2021-01-26 00:39:38 +08:00
Data Protection tokens instead of JWT tokens. ASP.NET Core Data Protection uses its own key ring to encrypt and protect tokens against tampering and is supported for all
types of tokens, except identity tokens, that are always JWT tokens.</p>
Update the documentation pages
2022-01-08 01:58:08 +08:00
<p>Unlike JWTs, ASP.NET Core Data Protection tokens only support symmetric encryption and rely on a binary format developed by the ASP.NET team rather than on a standard like JWT.
Update the documentation pages
2021-01-26 00:29:29 +08:00
While this prevents using such tokens in scenarios where interoperability is needed, opting for ASP.NET Core Data Protection rather than JWT has actually a few advantages:</p>
<ul>
Update the documentation pages
2023-05-03 03:58:39 +08:00
<li>ASP.NET Core Data Protection tokens don&#39;t use a JSON representation and therefore are generally a bit shorter.</li>
<li>ASP.NET Core Data Protection has been designed to achieve high throughput as it&#39;s natively used by ASP.NET Core for authentication cookies,
Update the documentation pages
2021-01-26 00:29:29 +08:00
antiforgery tokens and session cookies.</li>
</ul>
Update the documentation pages
2023-05-03 03:58:39 +08:00
<div class="WARNING"><h5>Warning</h5><p>Despite its name, ASP.NET Core Data Protection is not tied to ASP.NET Core and can be used in any .NET Standard 2.0-compatible
Update the documentation pages
2022-01-08 01:58:08 +08:00
application, including legacy ASP.NET 4.6.1 (and higher) applications using <code>Microsoft.Owin</code>.</p>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<p>To enable ASP.NET Core Data Protection support in the OpenIddict OWIN server and validation hosts, you need to
manually reference the <code>OpenIddict.Server.DataProtection</code> and <code>OpenIddict.Validation.DataProtection</code> packages.</p>
</div>
<h3 id="switching-to-data-protection-tokens">Switching to Data Protection tokens</h3>
<p>ASP.NET Core Data Protection support is provided by the <code>OpenIddict.Server.DataProtection</code> and <code>OpenIddict.Validation.DataProtection</code> packages.
Update the documentation pages
2023-05-03 03:58:39 +08:00
These packages are referenced by the <code>OpenIddict.AspNetCore</code> metapackage and therefore don&#39;t have to be referenced explicitly.</p>
Update the documentation pages
2021-01-26 00:29:29 +08:00
<p>To enable ASP.NET Core Data Protection support, call <code>options.UseDataProtection()</code> in <strong>both the server and validation options</strong>:</p>
<pre><code class="lang-csharp">services.AddOpenIddict()
.AddServer(options =&gt;
{
options.UseDataProtection();
})
.AddValidation(options =&gt;
{
options.UseDataProtection();
});
Update the documentation pages
2023-05-03 03:58:39 +08:00
</code></pre><div class="NOTE"><h5>Note</h5><p>Switching to ASP.NET Core Data Protection tokens doesn&#39;t prevent JWT tokens issued before Data Protection support was enabled from being validated:
Update the documentation pages
2021-01-26 00:29:29 +08:00
existing tokens can still be used alongside newly issued ASP.NET Core Data Protection tokens until they expire. When sending a refresh token request containing
a JWT refresh token, the application will receive an ASP.NET Core Data Protection refresh token and the previous one will be automatically marked as redeemed.</p>
</div>
Update the documentation pages
2022-01-08 01:58:08 +08:00
<p>By default, enabling ASP.NET Core Data Protection support will automatically switch the token format from JWT to Data Protection for all types of tokens, except JWT tokens.
The OpenIddict/Data Protection integration can be configured to prefer JWT when creating new tokens, <strong>which can be useful when using the ASP.NET Core Data Protection
Update the documentation pages
2021-01-26 00:29:29 +08:00
format for specific token types only</strong> (e.g for authorization codes and refresh tokens, but not for access tokens).</p>
<pre><code class="lang-csharp">services.AddOpenIddict()
.AddServer(options =&gt;
{
options.UseDataProtection()
.PreferDefaultAccessTokenFormat()
.PreferDefaultAuthorizationCodeFormat()
.PreferDefaultDeviceCodeFormat()
.PreferDefaultRefreshTokenFormat()
.PreferDefaultUserCodeFormat();
});
Update the documentation pages
2023-05-03 03:58:39 +08:00
</code></pre><div class="WARNING"><h5>Warning</h5><p>When the authorization and API/resource servers are not part of the same application, ASP.NET Core Data Protection MUST be configured to use
Update the documentation pages
2022-01-08 01:58:08 +08:00
the same application name and share the same key ring to allow the OpenIddict validation handler to read ASP.NET Core Data Protection tokens
Update the documentation pages
2021-01-26 00:29:29 +08:00
generated by an authorization server located in another project.</p>
<p>For more information, read <a href="https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview">Configure ASP.NET Core Data Protection</a>.</p>
</div>
Update the documentation pages
2022-01-08 01:11:48 +08:00
</article>
</div>
</main>
</div>
Update the documentation pages
2023-05-03 03:58:39 +08:00
<script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js"></script>
<script type="text/javascript" src="../styles/jquery.twbsPagination.js"></script>
<script type="text/javascript" src="../styles/url.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/anchor-js/anchor.min.js"></script>
<script type="text/javascript" src="../styles/docfx.js"></script>
<script type="text/javascript" src="../styles/main.js"></script>
Update the documentation pages
2022-01-08 01:11:48 +08:00
</body>
</html>
Reference in New Issue Copy Permalink