mirror of
https://gitee.com/dcren/openiddict-documentation.git
synced 2025-07-15 14:04:34 +08:00
241 lines
15 KiB
HTML
241 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<!--[if IE]><![endif]-->
|
|
<html>
|
|
|
|
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
|
<title>Encryption and signing credentials </title>
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="title" content="Encryption and signing credentials ">
|
|
<meta name="generator" content="docfx 2.56.7.0">
|
|
|
|
<link rel="shortcut icon" href="../images/favicon.ico">
|
|
<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">
|
|
<link rel="stylesheet" href="../styles/main.css">
|
|
<meta property="docfx:navrel" content="../toc.html">
|
|
<meta property="docfx:tocrel" content="toc.html">
|
|
|
|
|
|
|
|
</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>
|
|
|
|
|
|
<a class="brand" href="../index.html">
|
|
<img src="../images/logo.png" alt="OpenIddict" class="logomark">
|
|
<span class="brand-title">OpenIddict</span>
|
|
</a>
|
|
</div>
|
|
|
|
<div class="body-content">
|
|
|
|
<div id="blackout" class="blackout" onclick="toggleMenu()"></div>
|
|
|
|
<nav id="sidebar" role="navigation">
|
|
|
|
<div class="sidebar">
|
|
|
|
|
|
|
|
|
|
<div>
|
|
|
|
<a class="brand" href="../index.html">
|
|
<img src="../images/logo.png" alt="OpenIddict" class="logomark">
|
|
<span class="brand-title">OpenIddict</span>
|
|
</a>
|
|
<div id="navbar">
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
<div class="sidebar-item-separator"></div>
|
|
|
|
|
|
<div id="sidetoggle">
|
|
<div id="sidetoc"></div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class="footer">
|
|
|
|
<span>Generated by <strong>DocFX</strong></span>
|
|
</div>
|
|
</nav>
|
|
|
|
<main class="main-panel">
|
|
|
|
<div role="main" class="hide-when-search">
|
|
|
|
|
|
<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="">
|
|
<h1 id="encryption-and-signing-credentials">Encryption and signing credentials</h1>
|
|
|
|
<p>To protect the tokens it issues, OpenIddict uses 2 types of credentials:</p>
|
|
<ul>
|
|
<li><strong>Signing credentials are used to protect against tampering</strong>. They can be either asymmetric (e.g a RSA or ECDSA key) or symmetric.</li>
|
|
<li><strong>Encryption credentials are used to ensure the content of tokens cannot be read by malicious parties</strong>. They can be either asymmetric (e.g a RSA key) or symmetric.</li>
|
|
</ul>
|
|
<div class="NOTE"><h5>Note</h5><p>Tokens generated using the opt-in ASP.NET Core Data Protection integration rely on their own key ring, distinct from the credentials discussed in this documentation.</p>
|
|
<p>For more information about Data Protection, visit <a href="https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/introduction">ASP.NET Core Data Protection</a>.</p>
|
|
</div>
|
|
<h2 id="registering-credentials-in-the-authorization-server-options">Registering credentials in the authorization server options</h2>
|
|
<p>OpenIddict allows registering one or multiple keys (raw keys or embedded in X.509 certificates).</p>
|
|
<div class="NOTE"><h5>Note</h5><p>When multiple keys/certificates are registered (which can be useful to implement keys rotation), OpenIddict chooses the most appropriate key based on the following algorithm:</p>
|
|
<ul>
|
|
<li>Symmetric keys are always chosen first, except for identity tokens, that can only be signed using asymmetric keys.</li>
|
|
<li>Asymmetric keys embedded in X.509 certificates are ordered based on the <code>NotAfter</code> and <code>NotBefore</code> dates (certificates that are not yet valid
|
|
are not used by OpenIddict and certificates with the furthest expiration date are always preferred).</li>
|
|
<li>X.509 certificates are always preferred to raw RSA/ECDSA keys.</li>
|
|
</ul>
|
|
</div>
|
|
<h3 id="registering-an-ephemeral-key">Registering an ephemeral key</h3>
|
|
<p>For development purposes, an ephemeral key - that is not persisted or shared across instances - can be used to sign or encrypt tokens:</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddServer(options =>
|
|
{
|
|
options.AddEphemeralEncryptionKey()
|
|
.AddEphemeralSigningKey();
|
|
});
|
|
</code></pre><div class="NOTE"><h5>Note</h5><p><code>options.AddEphemeralEncryptionKey()</code> generates an asymmetric RSA key which is not directly used as-is to encrypt the tokens but is used to encrypt an
|
|
intermediate <em>per-token</em> symmetric key with which the token content is first encrypted using <a href="https://datatracker.ietf.org/doc/html/rfc7518#section-5.2.6">AES</a>.</p>
|
|
<p>For more information about this mechanism, read <a href="https://datatracker.ietf.org/doc/html/rfc7518#section-4.3">Key Encryption with RSAES OAEP</a>.</p>
|
|
</div>
|
|
<h3 id="registering-a-development-certificate">Registering a development certificate</h3>
|
|
<p>For development purposes, a certificate can be generated and stored by OpenIddict in the certificates store of the user account running the OpenIddict server feature.
|
|
Unlike ephemeral keys, development certificates are persisted - but not shared across instances - and will be reused when the application host is restarted.</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddServer(options =>
|
|
{
|
|
options.AddDevelopmentEncryptionCertificate()
|
|
.AddDevelopmentSigningCertificate();
|
|
});
|
|
</code></pre><div class="WARNING"><h5>Warning</h5><p>This feature is not available on .NET Framework 4.6.1: calling <code>options.AddDevelopmentEncryptionCertificate()</code> or <code>options.AddDevelopmentSigningCertificate()</code>
|
|
will result in a <code>PlatformNotSupportedException</code> being thrown at runtime if no valid development certificate can be found and a new one must be generated.</p>
|
|
</div>
|
|
<div class="CAUTION"><h5>Caution</h5><p><code>options.AddDevelopmentEncryptionCertificate()</code> or <code>options.AddDevelopmentSigningCertificate()</code> cannot be used in applications deployed on IIS or Azure App Services:
|
|
trying to use them on IIS or Azure App Services will result in an exception being thrown at runtime (unless the application pool is configured to load a user profile).
|
|
To avoid that, consider creating self-signed certificates and storing them in the X.509 certificates store of the host machine(s).</p>
|
|
</div>
|
|
<h3 id="registering-a-key">Registering a key</h3>
|
|
<p>To register a signing or encryption key, an instance of a <code>SecurityKey</code> - typically a <code>SymmetricSecurityKey</code> or a <code>RsaSecurityKey</code> -
|
|
can be provided to the <code>options.AddSigningKey()</code>/<code>options.AddEncryptionKey()</code> methods:</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddServer(options =>
|
|
{
|
|
options.AddEncryptionKey(new SymmetricSecurityKey(
|
|
Convert.FromBase64String("DRjd/GnduI3Efzen9V9BvbNUfc/VKgXltV7Kbk9sMkY=")));
|
|
});
|
|
</code></pre><div class="NOTE"><h5>Note</h5><p>While signing keys can be either symmetric or asymmetric, OpenIddict requires registering at least one asymmetric key to sign identity tokens.
|
|
If both an asymmetric and a symmetric signing key are registered, the symmetric key will always be preferred when protecting access tokens,
|
|
authorization codes or refresh tokens, while the asymmetric key will be used to sign identity tokens, that are meant to be publicly validated.</p>
|
|
</div>
|
|
<h3 id="registering-a-certificate-recommended-for-production-ready-scenarios">Registering a certificate (recommended for production-ready scenarios)</h3>
|
|
<p>To register a signing or encryption certificate, the <code>options.AddSigningCertificate()</code>/<code>options.AddEncryptionCertificate()</code> methods can be called
|
|
with an instance of <code>X509Certificate2</code>. Alternatively, a unique <code>thumbprint</code> identifying the certificate in the machine or user certificate store
|
|
of the operating system can also be provided.</p>
|
|
<p><strong>In production, it is recommended to use two RSA certificates, distinct from the certificate(s) used for HTTPS: one for encryption, one for signing</strong>.
|
|
Certificates can be generated and self-signed locally using the .NET Core <code>CertificateRequest</code> API:</p>
|
|
<pre><code class="lang-csharp">using var algorithm = RSA.Create(keySizeInBits: 2048);
|
|
|
|
var subject = new X500DistinguishedName("CN=Fabrikam Encryption Certificate");
|
|
var request = new CertificateRequest(subject, algorithm, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
|
|
request.CertificateExtensions.Add(new X509KeyUsageExtension(X509KeyUsageFlags.KeyEncipherment, critical: true));
|
|
|
|
var certificate = request.CreateSelfSigned(DateTimeOffset.UtcNow, DateTimeOffset.UtcNow.AddYears(2));
|
|
|
|
File.WriteAllBytes("encryption-certificate.pfx", certificate.Export(X509ContentType.Pfx, string.Empty));
|
|
</code></pre><pre><code class="lang-csharp">using var algorithm = RSA.Create(keySizeInBits: 2048);
|
|
|
|
var subject = new X500DistinguishedName("CN=Fabrikam Signing Certificate");
|
|
var request = new CertificateRequest(subject, algorithm, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
|
|
request.CertificateExtensions.Add(new X509KeyUsageExtension(X509KeyUsageFlags.DigitalSignature, critical: true));
|
|
|
|
var certificate = request.CreateSelfSigned(DateTimeOffset.UtcNow, DateTimeOffset.UtcNow.AddYears(2));
|
|
|
|
File.WriteAllBytes("signing-certificate.pfx", certificate.Export(X509ContentType.Pfx, string.Empty));
|
|
</code></pre><p>The best place to store your certificates will depend on your host:</p>
|
|
<ul>
|
|
<li>For IIS applications, <a href="https://www.sonicwall.com/support/knowledge-base/how-can-i-import-certificates-into-the-ms-windows-local-machine-certificate-store/170504615105398/">storing the certificates in the machine store</a> is the recommended option.</li>
|
|
<li>On Azure, certificates can be uploaded and exposed to Azure App Services applications using the special <code>WEBSITE_LOAD_CERTIFICATES</code> flag.
|
|
For more information, visit <a href="https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-certificate-in-code">Use a TLS/SSL certificate in your code in Azure App Service</a>.</li>
|
|
</ul>
|
|
<h2 id="importing-credentials-in-the-apiresource-validation-options">Importing credentials in the API/resource validation options</h2>
|
|
<h3 id="using-the-optionsuselocalserver-integration">Using the <code>options.UseLocalServer()</code> integration</h3>
|
|
<p>When the API and the authorization server are part of the same project, both the signing and
|
|
encryption credentials can be easily imported by calling <code>options.UseLocalServer()</code>:</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddValidation(options =>
|
|
{
|
|
options.UseLocalServer();
|
|
});
|
|
</code></pre><h3 id="using-openid-connect-discovery-asymmetric-signing-keys-only">Using OpenID Connect discovery (asymmetric signing keys only)</h3>
|
|
<p>When the API and the authorization server are hosted in different applications,
|
|
<a href="https://openid.net/specs/openid-connect-discovery-1_0.html">standard OpenID Connect discovery</a> can be used to automatically import asymmetric signing keys:</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddValidation(options =>
|
|
{
|
|
options.SetIssuer("https://localhost:44319/");
|
|
options.UseSystemNetHttp();
|
|
});
|
|
</code></pre><h3 id="registering-a-symmetric-signing-key-in-the-token-validation-parameters">Registering a symmetric signing key in the token validation parameters</h3>
|
|
<p>Unlike asymmetric signing keys, symmetric keys - used with HMAC-based algorithms like <a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.2">HS256</a> - cannot
|
|
be safely exposed by an OpenID Connect discovery endpoint. As such, they can't be automatically imported by the OpenIddict validation handler.
|
|
For applications that require using a symmetric signing key, the advanced configuration APIs can be used to register it in the token validation options:</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddValidation(options =>
|
|
{
|
|
options.Configure(options => options.TokenValidationParameters.IssuerSigningKey =
|
|
new SymmetricSecurityKey(
|
|
Convert.FromBase64String("DRjd/GnduI3Efzen9V9BvbNUfc/VKgXltV7Kbk9sMkY=")));
|
|
});
|
|
</code></pre><h3 id="registering-an-encryption-key-or-certificate">Registering an encryption key or certificate</h3>
|
|
<p>To import an encryption key/certificate, the same overloads as the ones exposed by the OpenIddict server feature can be used:</p>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddValidation(options =>
|
|
{
|
|
options.AddEncryptionCertificate("b82f36609cdaff9a95de60e8d5ac774b2e496c4b");
|
|
});
|
|
</code></pre></article>
|
|
|
|
</div>
|
|
</main>
|
|
</div>
|
|
|
|
|
|
<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>
|
|
|
|
</body>
|
|
|
|
</html>
|