mirror of https://github.com/golang-jwt/jwt.git
Deployed 12f1b31 with MkDocs version 1.4.2 (9.1.4)
This commit is contained in:
github-actions[bot]
parent
cdb6c1717d
commit
ed8f38723a
15
index.html
15
index.html
|
|
@ -338,6 +338,13 @@
|
||||||
Installation Guidelines
|
Installation Guidelines
|
||||||
</a>
|
</a>
|
||||||
|
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li class="md-nav__item">
|
||||||
|
<a href="#jwt-and-oauth-20" class="md-nav__link">
|
||||||
|
JWT and OAuth 2.0
|
||||||
|
</a>
|
||||||
|
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
</ul>
|
</ul>
|
||||||
|
|
@ -462,6 +469,14 @@ vulnerabilities which will not be fixed.</p>
|
||||||
<p>Then import it in your code:</p>
|
<p>Then import it in your code:</p>
|
||||||
<div class="language-go highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">import</span><span class="w"> </span><span class="s">"github.com/golang-jwt/jwt/v5"</span>
|
<div class="language-go highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">import</span><span class="w"> </span><span class="s">"github.com/golang-jwt/jwt/v5"</span>
|
||||||
</span></code></pre></div>
|
</span></code></pre></div>
|
||||||
|
<h2 id="jwt-and-oauth-20">JWT and OAuth 2.0</h2>
|
||||||
|
<p>It's worth mentioning that OAuth and JWT are not the same thing. A JWT token is simply a signed JSON object. It can be used anywhere such a thing is useful. There is some confusion, though, as JWT is the most common type of bearer token used in OAuth2 authentication.</p>
|
||||||
|
<p>Without going too far down the rabbit hole, here's a description of the interaction of these technologies:</p>
|
||||||
|
<ul>
|
||||||
|
<li>OAuth is a protocol for allowing an identity provider to be separate from the service a user is logging in to. For example, whenever you use Facebook to log into a different service (Yelp, Spotify, etc), you are using OAuth.</li>
|
||||||
|
<li>OAuth defines several options for passing around authentication data. One popular method is called a "bearer token". A bearer token is simply a string that should only be held by an authenticated user. Thus, simply presenting this token proves your identity. You can probably derive from here why a JWT might make a good bearer token. This is also specified in the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens, detailed in <a href="https://datatracker.ietf.org/doc/html/rfc9068">RFC 9068</a>.</li>
|
||||||
|
<li>Because bearer tokens are used for authentication, it's important they're kept secret. This is why transactions that use bearer tokens typically happen over TLS.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
File diff suppressed because one or more lines are too long
BIN
sitemap.xml.gz
BIN
sitemap.xml.gz
Binary file not shown.
|
|
@ -382,6 +382,20 @@
|
||||||
</label>
|
</label>
|
||||||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||||
|
|
||||||
|
<li class="md-nav__item">
|
||||||
|
<a href="#signing-vs-encryption" class="md-nav__link">
|
||||||
|
Signing vs Encryption
|
||||||
|
</a>
|
||||||
|
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li class="md-nav__item">
|
||||||
|
<a href="#choosing-a-signing-method" class="md-nav__link">
|
||||||
|
Choosing a Signing Method
|
||||||
|
</a>
|
||||||
|
|
||||||
|
</li>
|
||||||
|
|
||||||
<li class="md-nav__item">
|
<li class="md-nav__item">
|
||||||
<a href="#signing-methods-and-key-types" class="md-nav__link">
|
<a href="#signing-methods-and-key-types" class="md-nav__link">
|
||||||
Signing Methods and Key Types
|
Signing Methods and Key Types
|
||||||
|
|
@ -420,6 +434,14 @@
|
||||||
|
|
||||||
|
|
||||||
<h1 id="signing-methods">Signing Methods</h1>
|
<h1 id="signing-methods">Signing Methods</h1>
|
||||||
|
<h2 id="signing-vs-encryption">Signing vs Encryption</h2>
|
||||||
|
<p>A token is simply a JSON object that is signed by its author. this tells you exactly two things about the data:</p>
|
||||||
|
<ul>
|
||||||
|
<li>The author of the token was in the possession of the signing secret</li>
|
||||||
|
<li>The data has not been modified since it was signed</li>
|
||||||
|
</ul>
|
||||||
|
<p>It's important to know that JWT does not provide encryption, which means anyone who has access to the token can read its contents. If you need to protect (encrypt) the data, there is a companion spec, JSON Web Encryption (JWT)<sup id="fnref:jwe"><a class="footnote-ref" href="#fn:jwe">1</a></sup>, that provides this functionality. The companion project <a href="https://github.com/golang-jwt/jwe">https://github.com/golang-jwt/jwe</a> aims at a (very) experimental implementation of the JWE standard.</p>
|
||||||
|
<h2 id="choosing-a-signing-method">Choosing a Signing Method</h2>
|
||||||
<p>There are several signing methods available, and you should probably take the time to learn about the various options before choosing one. The principal design decision is most likely going to be <strong>symmetric</strong> vs <strong>asymmetric</strong>.</p>
|
<p>There are several signing methods available, and you should probably take the time to learn about the various options before choosing one. The principal design decision is most likely going to be <strong>symmetric</strong> vs <strong>asymmetric</strong>.</p>
|
||||||
<p>Symmetric signing methods, such as HMAC, use only a single secret. This is probably the simplest signing method to use since any <code>[]byte</code> can be used as a valid secret. They are also slightly computationally faster to use, though this rarely is enough to matter. Symmetric signing methods work the best when both producers and consumers of tokens are trusted, or even the same system. Since the same secret is used to both sign and validate tokens, you can't easily distribute the key for validation.</p>
|
<p>Symmetric signing methods, such as HMAC, use only a single secret. This is probably the simplest signing method to use since any <code>[]byte</code> can be used as a valid secret. They are also slightly computationally faster to use, though this rarely is enough to matter. Symmetric signing methods work the best when both producers and consumers of tokens are trusted, or even the same system. Since the same secret is used to both sign and validate tokens, you can't easily distribute the key for validation.</p>
|
||||||
<p>Asymmetric signing methods, such as RSA, use different keys for signing and verifying tokens. This makes it possible to produce tokens with a private key, and allow any consumer to access the public key for verification.</p>
|
<p>Asymmetric signing methods, such as RSA, use different keys for signing and verifying tokens. This makes it possible to produce tokens with a private key, and allow any consumer to access the public key for verification.</p>
|
||||||
|
|
@ -436,31 +458,31 @@
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
<tr>
|
<tr>
|
||||||
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodHMAC">HMAC signing method</a><sup id="fnref:hmac"><a class="footnote-ref" href="#fn:hmac">1</a></sup></td>
|
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodHMAC">HMAC signing method</a><sup id="fnref:hmac"><a class="footnote-ref" href="#fn:hmac">2</a></sup></td>
|
||||||
<td><code>HS256</code>,<code>HS384</code>,<code>HS512</code></td>
|
<td><code>HS256</code>,<code>HS384</code>,<code>HS512</code></td>
|
||||||
<td><code>[]byte</code></td>
|
<td><code>[]byte</code></td>
|
||||||
<td><code>[]byte</code></td>
|
<td><code>[]byte</code></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodRSA">RSA signing method</a><sup id="fnref:rsa"><a class="footnote-ref" href="#fn:rsa">2</a></sup></td>
|
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodRSA">RSA signing method</a><sup id="fnref:rsa"><a class="footnote-ref" href="#fn:rsa">3</a></sup></td>
|
||||||
<td><code>RS256</code>,<code>RS384</code>,<code>RS512</code></td>
|
<td><code>RS256</code>,<code>RS384</code>,<code>RS512</code></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/rsa#PrivateKey"><code>*rsa.PrivateKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/rsa#PrivateKey"><code>*rsa.PrivateKey</code></a></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/rsa#PublicKey"><code>*rsa.PublicKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/rsa#PublicKey"><code>*rsa.PublicKey</code></a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodECDSA">ECDSA signing method</a><sup id="fnref:ecdsa"><a class="footnote-ref" href="#fn:ecdsa">3</a></sup></td>
|
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodECDSA">ECDSA signing method</a><sup id="fnref:ecdsa"><a class="footnote-ref" href="#fn:ecdsa">4</a></sup></td>
|
||||||
<td><code>ES256</code>,<code>ES384</code>,<code>ES512</code></td>
|
<td><code>ES256</code>,<code>ES384</code>,<code>ES512</code></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/ecdsa#PrivateKey"><code>*ecdsa.PrivateKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/ecdsa#PrivateKey"><code>*ecdsa.PrivateKey</code></a></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/ecdsa#PublicKey"><code>*ecdsa.PublicKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/ecdsa#PublicKey"><code>*ecdsa.PublicKey</code></a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodRSAPSS">RSA-PSS signing method</a><sup id="fnref:rsapss"><a class="footnote-ref" href="#fn:rsapss">4</a></sup></td>
|
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodRSAPSS">RSA-PSS signing method</a><sup id="fnref:rsapss"><a class="footnote-ref" href="#fn:rsapss">5</a></sup></td>
|
||||||
<td><code>PS256</code>,<code>PS384</code>,<code>PS512</code></td>
|
<td><code>PS256</code>,<code>PS384</code>,<code>PS512</code></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/rsa#PrivateKey"><code>*rsa.PrivateKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/rsa#PrivateKey"><code>*rsa.PrivateKey</code></a></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/rsa#PublicKey"><code>*rsa.PublicKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/rsa#PublicKey"><code>*rsa.PublicKey</code></a></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodEd25519">EdDSA signing method</a><sup id="fnref:eddsa"><a class="footnote-ref" href="#fn:eddsa">5</a></sup></td>
|
<td><a href="https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodEd25519">EdDSA signing method</a><sup id="fnref:eddsa"><a class="footnote-ref" href="#fn:eddsa">6</a></sup></td>
|
||||||
<td><code>Ed25519</code></td>
|
<td><code>Ed25519</code></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/ed25519#PrivateKey"><code>ed25519.PrivateKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/ed25519#PrivateKey"><code>ed25519.PrivateKey</code></a></td>
|
||||||
<td><a href="https://pkg.go.dev/crypto/ed25519#PublicKey"><code>ed25519.PublicKey</code></a></td>
|
<td><a href="https://pkg.go.dev/crypto/ed25519#PublicKey"><code>ed25519.PublicKey</code></a></td>
|
||||||
|
|
@ -470,20 +492,23 @@
|
||||||
<div class="footnote">
|
<div class="footnote">
|
||||||
<hr />
|
<hr />
|
||||||
<ol>
|
<ol>
|
||||||
|
<li id="fn:jwe">
|
||||||
|
<p><a href="https://datatracker.ietf.org/doc/html/rfc7516">RFC 7516</a> <a class="footnote-backref" href="#fnref:jwe" title="Jump back to footnote 1 in the text">↩</a></p>
|
||||||
|
</li>
|
||||||
<li id="fn:hmac">
|
<li id="fn:hmac">
|
||||||
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.2">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:hmac" title="Jump back to footnote 1 in the text">↩</a></p>
|
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.2">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:hmac" title="Jump back to footnote 2 in the text">↩</a></p>
|
||||||
</li>
|
</li>
|
||||||
<li id="fn:rsa">
|
<li id="fn:rsa">
|
||||||
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.3">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:rsa" title="Jump back to footnote 2 in the text">↩</a></p>
|
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.3">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:rsa" title="Jump back to footnote 3 in the text">↩</a></p>
|
||||||
</li>
|
</li>
|
||||||
<li id="fn:ecdsa">
|
<li id="fn:ecdsa">
|
||||||
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.4">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:ecdsa" title="Jump back to footnote 3 in the text">↩</a></p>
|
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.4">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:ecdsa" title="Jump back to footnote 4 in the text">↩</a></p>
|
||||||
</li>
|
</li>
|
||||||
<li id="fn:rsapss">
|
<li id="fn:rsapss">
|
||||||
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.5">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:rsapss" title="Jump back to footnote 4 in the text">↩</a></p>
|
<p><a href="https://datatracker.ietf.org/doc/html/rfc7518#section-3.5">Section 3.2 of RFC 7518</a> <a class="footnote-backref" href="#fnref:rsapss" title="Jump back to footnote 5 in the text">↩</a></p>
|
||||||
</li>
|
</li>
|
||||||
<li id="fn:eddsa">
|
<li id="fn:eddsa">
|
||||||
<p><a href="https://datatracker.ietf.org/doc/html/rfc8037#section-3.1">Section 3.1 of RFC 8037</a> <a class="footnote-backref" href="#fnref:eddsa" title="Jump back to footnote 5 in the text">↩</a></p>
|
<p><a href="https://datatracker.ietf.org/doc/html/rfc8037#section-3.1">Section 3.1 of RFC 8037</a> <a class="footnote-backref" href="#fnref:eddsa" title="Jump back to footnote 6 in the text">↩</a></p>
|
||||||
</li>
|
</li>
|
||||||
</ol>
|
</ol>
|
||||||
</div>
|
</div>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue