File: rfc8725.html

package info (click to toggle)
doc-rfc 20230121-1
links: PTS, VCS
area: non-free
in suites: bookworm, forky, sid, trixie
size: 1,609,944 kB
file content (2013 lines) | stat: -rw-r--r-- 89,311 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html>
<html lang="en" class="RFC BCP">
<head>
<meta charset="utf-8">
<meta content="Common,Latin" name="scripts">
<meta content="initial-scale=1.0" name="viewport">
<title>RFC 8725: JSON Web Token Best Current Practices</title>
<meta content="Yaron Sheffer" name="author">
<meta content="Dick Hardt" name="author">
<meta content="Michael B. Jones" name="author">
<meta content="
       JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security
      tokens that contain a set of claims that can be signed and/or encrypted.
      JWTs are being widely used and deployed as a simple security token
      format in numerous protocols and applications, both in the area of
      digital identity and in other application areas.  This Best Current
      Practices document updates RFC 7519 to provide actionable guidance
      leading to secure implementation and deployment of JWTs. 
    " name="description">
<meta content="xml2rfc 2.40.0" name="generator">
<meta content="JSON Web Token" name="keyword">
<meta content="JWT" name="keyword">
<meta content="JSON Object Signing and Encryption" name="keyword">
<meta content="JOSE" name="keyword">
<meta content="JSON Web Signature" name="keyword">
<meta content="JWS" name="keyword">
<meta content="JSON Web Encryption" name="keyword">
<meta content="JWE" name="keyword">
<meta content="attacks" name="keyword">
<meta content="Claims" name="keyword">
<meta content="Security" name="keyword">
<meta content="Cryptography" name="keyword">
<meta content="8725" name="rfc.number">
<link href="rfc8725.xml" rel="alternate" type="application/rfc+xml">
<link href="#copyright" rel="license">
<style type="text/css">/*

  NOTE: Changes at the bottom of this file overrides some earlier settings.

  Once the style has stabilized and has been adopted as an official RFC style,
  this can be consolidated so that style settings occur only in one place, but
  for now the contents of this file consists first of the initial CSS work as
  provided to the RFC Formatter (xml2rfc) work, followed by itemized and
  commented changes found necssary during the development of the v3
  formatters.

*/

/* fonts */
@import url('https://fonts.googleapis.com/css?family=Noto+Sans'); /* Sans-serif */
@import url('https://fonts.googleapis.com/css?family=Noto+Serif'); /* Serif (print) */
@import url('https://fonts.googleapis.com/css?family=Roboto+Mono'); /* Monospace */

@viewport {
  zoom: 1.0;
  width: extend-to-zoom;
}
@-ms-viewport {
  width: extend-to-zoom;
  zoom: 1.0;
}
/* general and mobile first */
html {
}
body {
  max-width: 90%;
  margin: 1.5em auto;
  color: #222;
  background-color: #fff;
  font-size: 14px;
  font-family: 'Noto Sans', Arial, Helvetica, sans-serif;
  line-height: 1.6;
  scroll-behavior: smooth;
}
.ears {
  display: none;
}

/* headings */
#title, h1, h2, h3, h4, h5, h6 {
  margin: 1em 0 0.5em;
  font-weight: bold;
  line-height: 1.3;
}
#title {
  clear: both;
  border-bottom: 1px solid #ddd;
  margin: 0 0 0.5em 0;
  padding: 1em 0 0.5em;
}
.author {
  padding-bottom: 4px;
}
h1 {
  font-size: 26px;
  margin: 1em 0;
}
h2 {
  font-size: 22px;
  margin-top: -20px;  /* provide offset for in-page anchors */
  padding-top: 33px;
}
h3 {
  font-size: 18px;
  margin-top: -36px;  /* provide offset for in-page anchors */
  padding-top: 42px;
}
h4 {
  font-size: 16px;
  margin-top: -36px;  /* provide offset for in-page anchors */
  padding-top: 42px;
}
h5, h6 {
  font-size: 14px;
}
#n-copyright-notice {
  border-bottom: 1px solid #ddd;
  padding-bottom: 1em;
  margin-bottom: 1em;
}
/* general structure */
p {
  padding: 0;
  margin: 0 0 1em 0;
  text-align: left;
}
div, span {
  position: relative;
}
div {
  margin: 0;
}
.alignRight.art-text {
  background-color: #f9f9f9;
  border: 1px solid #eee;
  border-radius: 3px;
  padding: 1em 1em 0;
  margin-bottom: 1.5em;
}
.alignRight.art-text pre {
  padding: 0;
}
.alignRight {
  margin: 1em 0;
}
.alignRight > *:first-child {
  border: none;
  margin: 0;
  float: right;
  clear: both;
}
.alignRight > *:nth-child(2) {
  clear: both;
  display: block;
  border: none;
}
svg {
  display: block;
}
.alignCenter.art-text {
  background-color: #f9f9f9;
  border: 1px solid #eee;
  border-radius: 3px;
  padding: 1em 1em 0;
  margin-bottom: 1.5em;
}
.alignCenter.art-text pre {
  padding: 0;
}
.alignCenter {
  margin: 1em 0;
}
.alignCenter > *:first-child {
  border: none;
  /* this isn't optimal, but it's an existence proof.  PrinceXML doesn't
     support flexbox yet.
  */
  display: table;
  margin: 0 auto;
}

/* lists */
ol, ul {
  padding: 0;
  margin: 0 0 1em 2em;
}
ol ol, ul ul, ol ul, ul ol {
  margin-left: 1em;
}
li {
  margin: 0 0 0.25em 0;
}
.ulCompact li {
  margin: 0;
}
ul.empty, .ulEmpty {
  list-style-type: none;
}
ul.empty li, .ulEmpty li {
  margin-top: 0.5em;
}
ul.compact, .ulCompact,
ol.compact, .olCompact {
  line-height: 100%;
  margin: 0 0 0 2em;
}

/* definition lists */
dl {
}
dl > dt {
  float: left;
  margin-right: 1em;
}
/* 
dl.nohang > dt {
  float: none;
}
*/
dl > dd {
  margin-bottom: .8em;
  min-height: 1.3em;
}
dl.compact > dd, .dlCompact > dd {
  margin-bottom: 0em;
}
dl > dd > dl {
  margin-top: 0.5em;
  margin-bottom: 0em;
}

/* links */
a {
  text-decoration: none;
}
a[href] {
  color: #22e; /* Arlen: WCAG 2019 */
}
a[href]:hover {
  background-color: #f2f2f2;
}
figcaption a[href],
a[href].selfRef {
  color: #222;
}
/* XXX probably not this:
a.selfRef:hover {
  background-color: transparent;
  cursor: default;
} */

/* Figures */
tt, code, pre, code {
  background-color: #f9f9f9;
  font-family: 'Roboto Mono', monospace;
}
pre {
  border: 1px solid #eee;
  margin: 0;
  padding: 1em;
}
img {
  max-width: 100%;
}
figure {
  margin: 0;
}
figure blockquote {
  margin: 0.8em 0.4em 0.4em;
}
figcaption {
  font-style: italic;
  margin: 0 0 1em 0;
}
@media screen {
  pre {
    overflow-x: auto;
    max-width: 100%;
    max-width: calc(100% - 22px);
  }
}

/* aside, blockquote */
aside, blockquote {
  margin-left: 0;
  padding: 1.2em 2em;
}
blockquote {
  background-color: #f9f9f9;
  color: #111; /* Arlen: WCAG 2019 */
  border: 1px solid #ddd;
  border-radius: 3px;
  margin: 1em 0;
}
cite {
  display: block;
  text-align: right;
  font-style: italic;
}

/* tables */
table {
  width: 100%;
  margin: 0 0 1em;
  border-collapse: collapse;
  border: 1px solid #eee;
}
th, td {
  text-align: left;
  vertical-align: top;
  padding: 0.5em 0.75em;
}
th {
  text-align: left;
  background-color: #e9e9e9;
}
tr:nth-child(2n+1) > td {
  background-color: #f5f5f5;
}
table caption {
  font-style: italic;
  margin: 0;
  padding: 0;
  text-align: left;
}
table p {
  /* XXX to avoid bottom margin on table row signifiers. If paragraphs should
     be allowed within tables more generally, it would be far better to select on a class. */
  margin: 0;
}

/* pilcrow */
a.pilcrow {
  color: #666; /* Arlen: AHDJ 2019 */
  text-decoration: none;
  visibility: hidden;
  user-select: none;
  -ms-user-select: none;
  -o-user-select:none;
  -moz-user-select: none;
  -khtml-user-select: none;
  -webkit-user-select: none;
  -webkit-touch-callout: none;
}
@media screen {
  aside:hover > a.pilcrow,
  p:hover > a.pilcrow,
  blockquote:hover > a.pilcrow,
  div:hover > a.pilcrow,
  li:hover > a.pilcrow,
  pre:hover > a.pilcrow {
    visibility: visible;
  }
  a.pilcrow:hover {
    background-color: transparent;
  }
}

/* misc */
hr {
  border: 0;
  border-top: 1px solid #eee;
}
.bcp14 {
  font-variant: small-caps;
}

.role {
  font-variant: all-small-caps;
}

/* info block */
#identifiers {
  margin: 0;
  font-size: 0.9em;
}
#identifiers dt {
  width: 3em;
  clear: left;
}
#identifiers dd {
  float: left;
  margin-bottom: 0;
}
#identifiers .authors .author {
  display: inline-block;
  margin-right: 1.5em;
}
#identifiers .authors .org {
  font-style: italic;
}

/* The prepared/rendered info at the very bottom of the page */
.docInfo {
  color: #666; /* Arlen: WCAG 2019 */
  font-size: 0.9em;
  font-style: italic;
  margin-top: 2em;
}
.docInfo .prepared {
  float: left;
}
.docInfo .prepared {
  float: right;
}

/* table of contents */
#toc  {
  padding: 0.75em 0 2em 0;
  margin-bottom: 1em;
}
nav.toc ul {
  margin: 0 0.5em 0 0;
  padding: 0;
  list-style: none;
}
nav.toc li {
  line-height: 1.3em;
  margin: 0.75em 0;
  padding-left: 1.2em;
  text-indent: -1.2em;
}
/* references */
.references dt {
  text-align: right;
  font-weight: bold;
  min-width: 7em;
}
.references dd {
  margin-left: 8em;
  overflow: auto;
}

.refInstance {
  margin-bottom: 1.25em;
}

.references .ascii {
  margin-bottom: 0.25em;
}

/* index */
.index ul {
  margin: 0 0 0 1em;
  padding: 0;
  list-style: none;
}
.index ul ul {
  margin: 0;
}
.index li {
  margin: 0;
  text-indent: -2em;
  padding-left: 2em;
  padding-bottom: 5px;
}
.indexIndex {
  margin: 0.5em 0 1em;
}
.index a {
  font-weight: 700;
}
/* make the index two-column on all but the smallest screens */
@media (min-width: 600px) {
  .index ul {
    -moz-column-count: 2;
    -moz-column-gap: 20px;
  }
  .index ul ul {
    -moz-column-count: 1;
    -moz-column-gap: 0;
  }
}

/* authors */
address.vcard {
  font-style: normal;
  margin: 1em 0;
}

address.vcard .nameRole {
  font-weight: 700;
  margin-left: 0;
}
address.vcard .label {
  font-family: "Noto Sans",Arial,Helvetica,sans-serif;
  margin: 0.5em 0;
}
address.vcard .type {
  display: none;
}
.alternative-contact {
  margin: 1.5em 0 1em;
}
hr.addr {
  border-top: 1px dashed;
  margin: 0;
  color: #ddd;
  max-width: calc(100% - 16px);
}

/* temporary notes */
.rfcEditorRemove::before {
  position: absolute;
  top: 0.2em;
  right: 0.2em;
  padding: 0.2em;
  content: "The RFC Editor will remove this note";
  color: #9e2a00; /* Arlen: WCAG 2019 */
  background-color: #ffd; /* Arlen: WCAG 2019 */
}
.rfcEditorRemove {
  position: relative;
  padding-top: 1.8em;
  background-color: #ffd; /* Arlen: WCAG 2019 */
  border-radius: 3px;
}
.cref {
  background-color: #ffd; /* Arlen: WCAG 2019 */
  padding: 2px 4px;
}
.crefSource {
  font-style: italic;
}
/* alternative layout for smaller screens */
@media screen and (max-width: 1023px) {
  body {
    padding-top: 2em;
  }
  #title {
    padding: 1em 0;
  }
  h1 {
    font-size: 24px;
  }
  h2 {
    font-size: 20px;
    margin-top: -18px;  /* provide offset for in-page anchors */
    padding-top: 38px;
  }
  #identifiers dd {
    max-width: 60%;
  }
  #toc {
    position: fixed;
    z-index: 2;
    top: 0;
    right: 0;
    padding: 0;
    margin: 0;
    background-color: inherit;
    border-bottom: 1px solid #ccc;
  }
  #toc h2 {
    margin: -1px 0 0 0;
    padding: 4px 0 4px 6px;
    padding-right: 1em;
    min-width: 190px;
    font-size: 1.1em;
    text-align: right;
    background-color: #444;
    color: white;
    cursor: pointer;
  }
  #toc h2::before { /* css hamburger */
    float: right;
    position: relative;
    width: 1em;
    height: 1px;
    left: -164px;
    margin: 6px 0 0 0;
    background: white none repeat scroll 0 0;
    box-shadow: 0 4px 0 0 white, 0 8px 0 0 white;
    content: "";
  }
  #toc nav {
    display: none;
    padding: 0.5em 1em 1em;
    overflow: auto;
    height: calc(100vh - 48px);
    border-left: 1px solid #ddd;
  }
}

/* alternative layout for wide screens */
@media screen and (min-width: 1024px) {
  body {
    max-width: 724px;
    margin: 42px auto;
    padding-left: 1.5em;
    padding-right: 29em;
  }
  #toc {
    position: fixed;
    top: 42px;
    right: 42px;
    width: 25%;
    margin: 0;
    padding: 0 1em;
    z-index: 1;
  }
  #toc h2 {
    border-top: none;
    border-bottom: 1px solid #ddd;
    font-size: 1em;
    font-weight: normal;
    margin: 0;
    padding: 0.25em 1em 1em 0;
  }
  #toc nav {
    display: block;
    height: calc(90vh - 84px);
    bottom: 0;
    padding: 0.5em 0 0;
    overflow: auto;
  }
  img { /* future proofing */
    max-width: 100%;
    height: auto;
  }
}

/* pagination */
@media print {
  body {

    width: 100%;
  }
  p {
    orphans: 3;
    widows: 3;
  }
  #n-copyright-notice {
    border-bottom: none;
  }
  #toc, #n-introduction {
    page-break-before: always;
  }
  #toc {
    border-top: none;
    padding-top: 0;
  }
  figure, pre {
    page-break-inside: avoid;
  }
  figure {
    overflow: scroll;
  }
  h1, h2, h3, h4, h5, h6 {
    page-break-after: avoid;
  }
  h2+*, h3+*, h4+*, h5+*, h6+* {
    page-break-before: avoid;
  }
  pre {
    white-space: pre-wrap;
    word-wrap: break-word;
    font-size: 10pt;
  }
  table {
    border: 1px solid #ddd;
  }
  td {
    border-top: 1px solid #ddd;
  }
}

/* This is commented out here, as the string-set: doesn't
   pass W3C validation currently */
/*
.ears thead .left {
  string-set: ears-top-left content();
}

.ears thead .center {
  string-set: ears-top-center content();
}

.ears thead .right {
  string-set: ears-top-right content();
}

.ears tfoot .left {
  string-set: ears-bottom-left content();
}

.ears tfoot .center {
  string-set: ears-bottom-center content();
}

.ears tfoot .right {
  string-set: ears-bottom-right content();
}
*/

@page :first {
  padding-top: 0;
  @top-left {
    content: normal;
    border: none;
  }
  @top-center {
    content: normal;
    border: none;
  }
  @top-right {
    content: normal;
    border: none;
  }
}

@page {
  size: A4;
  margin-bottom: 45mm;
  padding-top: 20px;
  /* The follwing is commented out here, but set appropriately by in code, as
     the content depends on the document */
  /*
  @top-left {
    content: 'Internet-Draft';
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @top-left {
    content: string(ears-top-left);
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @top-center {
    content: string(ears-top-center);
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @top-right {
    content: string(ears-top-right);
    vertical-align: bottom;
    border-bottom: solid 1px #ccc;
  }
  @bottom-left {
    content: string(ears-bottom-left);
    vertical-align: top;
    border-top: solid 1px #ccc;
  }
  @bottom-center {
    content: string(ears-bottom-center);
    vertical-align: top;
    border-top: solid 1px #ccc;
  }
  @bottom-right {
      content: '[Page ' counter(page) ']';
      vertical-align: top;
      border-top: solid 1px #ccc;
  }
  */

}

/* Changes introduced to fix issues found during implementation */
/* Make sure links are clickable even if overlapped by following H* */
a {
  z-index: 2;
}
/* Separate body from document info even without intervening H1 */
section {
  clear: both;
}


/* Top align author divs, to avoid names without organization dropping level with org names */
.author {
  vertical-align: top;
}

/* Leave room in document info to show Internet-Draft on one line */
#identifiers dt {
  width: 8em;
}

/* Don't waste quite as much whitespace between label and value in doc info */
#identifiers dd {
  margin-left: 1em;
}

/* Give floating toc a background color (needed when it's a div inside section */
#toc {
  background-color: white;
}

/* Make the collapsed ToC header render white on gray also when it's a link */
@media screen and (max-width: 1023px) {
  #toc h2 a,
  #toc h2 a:link,
  #toc h2 a:focus,
  #toc h2 a:hover,
  #toc a.toplink,
  #toc a.toplink:hover {
    color: white;
    background-color: #444;
    text-decoration: none;
  }
}

/* Give the bottom of the ToC some whitespace */
@media screen and (min-width: 1024px) {
  #toc {
    padding: 0 0 1em 1em;
  }
}

/* Style section numbers with more space between number and title */
.section-number {
  padding-right: 0.5em;
}

/* prevent monospace from becoming overly large */
tt, code, pre, code {
  font-size: 95%;
}

/* Fix the height/width aspect for ascii art*/
pre.sourcecode,
.art-text pre {
  line-height: 1.12;
}


/* Add styling for a link in the ToC that points to the top of the document */
a.toplink {
  float: right;
  margin-right: 0.5em;
}

/* Fix the dl styling to match the RFC 7992 attributes */
dl > dt,
dl.dlParallel > dt {
  float: left;
  margin-right: 1em;
}
dl.dlNewline > dt {
  float: none;
}

/* Provide styling for table cell text alignment */
table td.text-left,
table th.text-left {
  text-align: left;
}
table td.text-center,
table th.text-center {
  text-align: center;
}
table td.text-right,
table th.text-right {
  text-align: right;
}

/* Make the alternative author contact informatio look less like just another
   author, and group it closer with the primary author contact information */
.alternative-contact {
  margin: 0.5em 0 0.25em 0;
}
address .non-ascii {
  margin: 0 0 0 2em;
}

/* With it being possible to set tables with alignment
  left, center, and right, { width: 100%; } does not make sense */
table {
  width: auto;
}

/* Avoid reference text that sits in a block with very wide left margin,
   because of a long floating dt label.*/
.references dd {
  overflow: visible;
}

/* Control caption placement */
caption {
  caption-side: bottom;
}

/* Limit the width of the author address vcard, so names in right-to-left
   script don't end up on the other side of the page. */

address.vcard {
  max-width: 30em;
  margin-right: auto;
}

/* For address alignment dependent on LTR or RTL scripts */
address div.left {
  text-align: left;
}
address div.right {
  text-align: right;
}

/* Provide table alignment support.  We can't use the alignX classes above
   since they do unwanted things with caption and other styling. */
table.right {
 margin-left: auto;
 margin-right: 0;
}
table.center {
 margin-left: auto;
 margin-right: auto;
}
table.left {
 margin-left: 0;
 margin-right: auto;
}

/* Give the table caption label the same styling as the figcaption */
caption a[href] {
  color: #222;
}

@media print {
  .toplink {
    display: none;
  }

  /* avoid overwriting the top border line with the ToC header */
  #toc {
    padding-top: 1px;
  }

  /* Avoid page breaks inside dl and author address entries */
  .vcard {
    page-break-inside: avoid;
  }

}
/* Avoid wrapping of URLs in references */
@media screen {
  .references a {
    white-space: nowrap;
  }
}
/* Tweak the bcp14 keyword presentation */
.bcp14 {
  font-variant: small-caps;
  font-weight: bold;
  font-size: 0.9em;
}
/* Tweak the invisible space above H* in order not to overlay links in text above */
 h2 {
  margin-top: -18px;  /* provide offset for in-page anchors */
  padding-top: 31px;
 }
 h3 {
  margin-top: -18px;  /* provide offset for in-page anchors */
  padding-top: 24px;
 }
 h4 {
  margin-top: -18px;  /* provide offset for in-page anchors */
  padding-top: 24px;
 }
/* Float artwork pilcrow to the right */
@media screen {
  .artwork a.pilcrow {
    display: block;
    line-height: 0.7;
    margin-top: 0.15em;
  }
}
/* Make pilcrows on dd visible */
@media screen {
  dd:hover > a.pilcrow {
    visibility: visible;
  }
}
/* Make the placement of figcaption match that of a table's caption
   by removing the figure's added bottom margin */
.alignLeft.art-text,
.alignCenter.art-text,
.alignRight.art-text {
   margin-bottom: 0;
}
.alignLeft,
.alignCenter,
.alignRight {
  margin: 1em 0 0 0;
}
/* In print, the pilcrow won't show on hover, so prevent it from taking up space,
   possibly even requiring a new line */
@media print {
  a.pilcrow {
    display: none;
  }
}
/* Styling for the external metadata */
div#external-metadata {
  background-color: #eee;
  padding: 0.5em;
  margin-bottom: 0.5em;
  display: none;
}
div#internal-metadata {
  padding: 0.5em;                       /* to match the external-metadata padding */
}
/* Styling for title RFC Number */
h1#rfcnum {
  clear: both;
  margin: 0 0 -1em;
  padding: 1em 0 0 0;
}
/* Make .olPercent look the same as <ol><li> */
dl.olPercent > dd {
  margin: 0 0 0.25em 0;
  min-height: initial;
}
/* Give aside some styling to set it apart */
aside {
  border-left: 1px solid #ddd;
  margin: 1em 0 1em 2em;
  padding: 0.2em 2em;
}
aside > dl,
aside > ol,
aside > ul,
aside > table,
aside > p {
  margin-bottom: 0.5em;
}
/* Additional page break settings */
@media print {
  figcaption, table caption {
    page-break-before: avoid;
  }
}
/* Font size adjustments for print */
@media print {
  body  { font-size: 10pt;      line-height: normal; max-width: 96%; }
  h1    { font-size: 1.72em;    padding-top: 1.5em; } /* 1*1.2*1.2*1.2 */
  h2    { font-size: 1.44em;    padding-top: 1.5em; } /* 1*1.2*1.2 */
  h3    { font-size: 1.2em;     padding-top: 1.5em; } /* 1*1.2 */
  h4    { font-size: 1em;       padding-top: 1.5em; }
  h5, h6 { font-size: 1em;      margin: initial; padding: 0.5em 0 0.3em; }
}
/* Sourcecode margin in print, when there's no pilcrow */
@media print {
  .artwork,
  .sourcecode {
    margin-bottom: 1em;
  }
}
/*
  The margin-left: 0 on <dd> removes all distinction
  between levels from nested <dl>s.  Undo that.
*/
dl.olPercent > dd,
dd {
  margin-left: revert;
}
/* Avoid narrow tables forcing too narrow table captions, which may render badly */
table {
  min-width: 20em;
}
/* ol type a */
ol.type-a { list-style-type: lower-alpha; }
ol.type-A { list-style-type: upper-alpha; }
ol.type-i { list-style-type: lower-roman; }
ol.type-I { list-style-type: lower-roman; }
</style>
<link href="rfc-local.css" rel="stylesheet" type="text/css">
<link href="https://dx.doi.org/10.17487/rfc8725" rel="alternate">
  <link href="urn:issn:2070-1721" rel="alternate">
  <link href="https://datatracker.ietf.org/doc/draft-ietf-oauth-jwt-bcp-07" rel="prev">
  </head>
<body>
<script src="https://www.rfc-editor.org/js/metadata.min.js"></script>
<table class="ears">
<thead><tr>
<td class="left">RFC 8725</td>
<td class="center">JWT BCP</td>
<td class="right">February 2020</td>
</tr></thead>
<tfoot><tr>
<td class="left">Sheffer, et al.</td>
<td class="center">Best Current Practice</td>
<td class="right">[Page]</td>
</tr></tfoot>
</table>
<div id="external-metadata" class="document-information"></div>
<div id="internal-metadata" class="document-information">
<dl id="identifiers">
<dt class="label-stream">Stream:</dt>
<dd class="stream">Internet Engineering Task Force (IETF)</dd>
<dt class="label-rfc">RFC:</dt>
<dd class="rfc"><a href="https://www.rfc-editor.org/rfc/rfc8725" class="eref">8725</a></dd>
<dt class="label-bcp">BCP:</dt>
<dd class="bcp">225</dd>
<dt class="label-updates">Updates:</dt>
<dd class="updates">
<a href="https://www.rfc-editor.org/rfc/rfc7519" class="eref">7519</a> </dd>
<dt class="label-category">Category:</dt>
<dd class="category">Best Current Practice</dd>
<dt class="label-published">Published:</dt>
<dd class="published">
<time datetime="2020-02" class="published">February 2020</time>
    </dd>
<dt class="label-issn">ISSN:</dt>
<dd class="issn">2070-1721</dd>
<dt class="label-authors">Authors:</dt>
<dd class="authors">
<div class="author">
      <div class="author-name">Y. Sheffer</div>
<div class="org">Intuit</div>
</div>
<div class="author">
      <div class="author-name">D. Hardt</div>
</div>
<div class="author">
      <div class="author-name">M. Jones</div>
<div class="org">Microsoft</div>
</div>
</dd>
</dl>
</div>
<h1 id="rfcnum">RFC 8725</h1>
<h1 id="title">JSON Web Token Best Current Practices</h1>
<section id="section-abstract">
      <h2 id="abstract"><a href="#abstract" class="selfRef">Abstract</a></h2>
<p id="section-abstract-1">JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security
      tokens that contain a set of claims that can be signed and/or encrypted.
      JWTs are being widely used and deployed as a simple security token
      format in numerous protocols and applications, both in the area of
      digital identity and in other application areas.  This Best Current
      Practices document updates RFC 7519 to provide actionable guidance
      leading to secure implementation and deployment of JWTs.<a href="#section-abstract-1" class="pilcrow">¶</a></p>
</section>
<div id="status-of-memo">
<section id="section-boilerplate.1">
        <h2 id="name-status-of-this-memo">
<a href="#name-status-of-this-memo" class="section-name selfRef">Status of This Memo</a>
        </h2>
<p id="section-boilerplate.1-1">
            This memo documents an Internet Best Current Practice.<a href="#section-boilerplate.1-1" class="pilcrow">¶</a></p>
<p id="section-boilerplate.1-2">
            This document is a product of the Internet Engineering Task Force
            (IETF).  It represents the consensus of the IETF community.  It has
            received public review and has been approved for publication by
            the Internet Engineering Steering Group (IESG).  Further information
            on BCPs is available in Section 2 of RFC 7841.<a href="#section-boilerplate.1-2" class="pilcrow">¶</a></p>
<p id="section-boilerplate.1-3">
            Information about the current status of this document, any
            errata, and how to provide feedback on it may be obtained at
            <span><a href="https://www.rfc-editor.org/info/rfc8725">https://www.rfc-editor.org/info/rfc8725</a></span>.<a href="#section-boilerplate.1-3" class="pilcrow">¶</a></p>
</section>
</div>
<div id="copyright">
<section id="section-boilerplate.2">
        <h2 id="name-copyright-notice">
<a href="#name-copyright-notice" class="section-name selfRef">Copyright Notice</a>
        </h2>
<p id="section-boilerplate.2-1">
            Copyright (c) 2020 IETF Trust and the persons identified as the
            document authors. All rights reserved.<a href="#section-boilerplate.2-1" class="pilcrow">¶</a></p>
<p id="section-boilerplate.2-2">
            This document is subject to BCP 78 and the IETF Trust's Legal
            Provisions Relating to IETF Documents
            (<span><a href="https://trustee.ietf.org/license-info">https://trustee.ietf.org/license-info</a></span>) in effect on the date of
            publication of this document. Please review these documents
            carefully, as they describe your rights and restrictions with
            respect to this document. Code Components extracted from this
            document must include Simplified BSD License text as described in
            Section 4.e of the Trust Legal Provisions and are provided without
            warranty as described in the Simplified BSD License.<a href="#section-boilerplate.2-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="toc">
<section id="section-toc.1">
        <a href="#" onclick="scroll(0,0)" class="toplink">▲</a><h2 id="name-table-of-contents">
<a href="#name-table-of-contents" class="section-name selfRef">Table of Contents</a>
        </h2>
<nav class="toc"><ul class="toc ulEmpty">
<li class="toc ulEmpty" id="section-toc.1-1.1">
            <p id="section-toc.1-1.1.1"><a href="#section-1" class="xref">1</a>.  <a href="#name-introduction" class="xref">Introduction</a><a href="#section-toc.1-1.1.1" class="pilcrow">¶</a></p>
<ul class="toc ulEmpty">
<li class="toc ulEmpty" id="section-toc.1-1.1.2.1">
                <p id="section-toc.1-1.1.2.1.1"><a href="#section-1.1" class="xref">1.1</a>.  <a href="#name-target-audience" class="xref">Target Audience</a><a href="#section-toc.1-1.1.2.1.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.1.2.2">
                <p id="section-toc.1-1.1.2.2.1"><a href="#section-1.2" class="xref">1.2</a>.  <a href="#name-conventions-used-in-this-do" class="xref">Conventions Used in this Document</a><a href="#section-toc.1-1.1.2.2.1" class="pilcrow">¶</a></p>
</li>
</ul>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2">
            <p id="section-toc.1-1.2.1"><a href="#section-2" class="xref">2</a>.  <a href="#name-threats-and-vulnerabilities" class="xref">Threats and Vulnerabilities</a><a href="#section-toc.1-1.2.1" class="pilcrow">¶</a></p>
<ul class="toc ulEmpty">
<li class="toc ulEmpty" id="section-toc.1-1.2.2.1">
                <p id="section-toc.1-1.2.2.1.1"><a href="#section-2.1" class="xref">2.1</a>.  <a href="#name-weak-signatures-and-insuffi" class="xref">Weak Signatures and Insufficient Signature Validation</a><a href="#section-toc.1-1.2.2.1.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.2">
                <p id="section-toc.1-1.2.2.2.1"><a href="#section-2.2" class="xref">2.2</a>.  <a href="#name-weak-symmetric-keys" class="xref">Weak Symmetric Keys</a><a href="#section-toc.1-1.2.2.2.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.3">
                <p id="section-toc.1-1.2.2.3.1"><a href="#section-2.3" class="xref">2.3</a>.  <a href="#name-incorrect-composition-of-en" class="xref">Incorrect Composition of Encryption and Signature</a><a href="#section-toc.1-1.2.2.3.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.4">
                <p id="section-toc.1-1.2.2.4.1"><a href="#section-2.4" class="xref">2.4</a>.  <a href="#name-plaintext-leakage-through-a" class="xref">Plaintext Leakage through Analysis of Ciphertext Length</a><a href="#section-toc.1-1.2.2.4.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.5">
                <p id="section-toc.1-1.2.2.5.1"><a href="#section-2.5" class="xref">2.5</a>.  <a href="#name-insecure-use-of-elliptic-cu" class="xref">Insecure Use of Elliptic Curve Encryption</a><a href="#section-toc.1-1.2.2.5.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.6">
                <p id="section-toc.1-1.2.2.6.1"><a href="#section-2.6" class="xref">2.6</a>.  <a href="#name-multiplicity-of-json-encodi" class="xref">Multiplicity of JSON Encodings</a><a href="#section-toc.1-1.2.2.6.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.7">
                <p id="section-toc.1-1.2.2.7.1"><a href="#section-2.7" class="xref">2.7</a>.  <a href="#name-substitution-attacks" class="xref">Substitution Attacks</a><a href="#section-toc.1-1.2.2.7.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.8">
                <p id="section-toc.1-1.2.2.8.1"><a href="#section-2.8" class="xref">2.8</a>.  <a href="#name-cross-jwt-confusion" class="xref">Cross-JWT Confusion</a><a href="#section-toc.1-1.2.2.8.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.2.2.9">
                <p id="section-toc.1-1.2.2.9.1"><a href="#section-2.9" class="xref">2.9</a>.  <a href="#name-indirect-attacks-on-the-ser" class="xref">Indirect Attacks on the Server</a><a href="#section-toc.1-1.2.2.9.1" class="pilcrow">¶</a></p>
</li>
</ul>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3">
            <p id="section-toc.1-1.3.1"><a href="#section-3" class="xref">3</a>.  <a href="#name-best-practices" class="xref">Best Practices</a><a href="#section-toc.1-1.3.1" class="pilcrow">¶</a></p>
<ul class="toc ulEmpty">
<li class="toc ulEmpty" id="section-toc.1-1.3.2.1">
                <p id="section-toc.1-1.3.2.1.1"><a href="#section-3.1" class="xref">3.1</a>.  <a href="#name-perform-algorithm-verificat" class="xref">Perform Algorithm Verification</a><a href="#section-toc.1-1.3.2.1.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.2">
                <p id="section-toc.1-1.3.2.2.1"><a href="#section-3.2" class="xref">3.2</a>.  <a href="#name-use-appropriate-algorithms" class="xref">Use Appropriate Algorithms</a><a href="#section-toc.1-1.3.2.2.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.3">
                <p id="section-toc.1-1.3.2.3.1"><a href="#section-3.3" class="xref">3.3</a>.  <a href="#name-validate-all-cryptographic-" class="xref">Validate All Cryptographic Operations</a><a href="#section-toc.1-1.3.2.3.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.4">
                <p id="section-toc.1-1.3.2.4.1"><a href="#section-3.4" class="xref">3.4</a>.  <a href="#name-validate-cryptographic-inpu" class="xref">Validate Cryptographic Inputs</a><a href="#section-toc.1-1.3.2.4.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.5">
                <p id="section-toc.1-1.3.2.5.1"><a href="#section-3.5" class="xref">3.5</a>.  <a href="#name-ensure-cryptographic-keys-h" class="xref">Ensure Cryptographic Keys Have Sufficient Entropy</a><a href="#section-toc.1-1.3.2.5.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.6">
                <p id="section-toc.1-1.3.2.6.1"><a href="#section-3.6" class="xref">3.6</a>.  <a href="#name-avoid-compression-of-encryp" class="xref">Avoid Compression of Encryption Inputs</a><a href="#section-toc.1-1.3.2.6.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.7">
                <p id="section-toc.1-1.3.2.7.1"><a href="#section-3.7" class="xref">3.7</a>.  <a href="#name-use-utf-8" class="xref">Use UTF-8</a><a href="#section-toc.1-1.3.2.7.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.8">
                <p id="section-toc.1-1.3.2.8.1"><a href="#section-3.8" class="xref">3.8</a>.  <a href="#name-validate-issuer-and-subject" class="xref">Validate Issuer and Subject</a><a href="#section-toc.1-1.3.2.8.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.9">
                <p id="section-toc.1-1.3.2.9.1"><a href="#section-3.9" class="xref">3.9</a>.  <a href="#name-use-and-validate-audience" class="xref">Use and Validate Audience</a><a href="#section-toc.1-1.3.2.9.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.10">
                <p id="section-toc.1-1.3.2.10.1"><a href="#section-3.10" class="xref">3.10</a>. <a href="#name-do-not-trust-received-claim" class="xref">Do Not Trust Received Claims</a><a href="#section-toc.1-1.3.2.10.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.11">
                <p id="section-toc.1-1.3.2.11.1"><a href="#section-3.11" class="xref">3.11</a>. <a href="#name-use-explicit-typing" class="xref">Use Explicit Typing</a><a href="#section-toc.1-1.3.2.11.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.3.2.12">
                <p id="section-toc.1-1.3.2.12.1"><a href="#section-3.12" class="xref">3.12</a>. <a href="#name-use-mutually-exclusive-vali" class="xref">Use Mutually Exclusive Validation Rules for Different Kinds of JWTs</a><a href="#section-toc.1-1.3.2.12.1" class="pilcrow">¶</a></p>
</li>
</ul>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.4">
            <p id="section-toc.1-1.4.1"><a href="#section-4" class="xref">4</a>.  <a href="#name-security-considerations" class="xref">Security Considerations</a><a href="#section-toc.1-1.4.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.5">
            <p id="section-toc.1-1.5.1"><a href="#section-5" class="xref">5</a>.  <a href="#name-iana-considerations" class="xref">IANA Considerations</a><a href="#section-toc.1-1.5.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.6">
            <p id="section-toc.1-1.6.1"><a href="#section-6" class="xref">6</a>.  <a href="#name-references" class="xref">References</a><a href="#section-toc.1-1.6.1" class="pilcrow">¶</a></p>
<ul class="toc ulEmpty">
<li class="toc ulEmpty" id="section-toc.1-1.6.2.1">
                <p id="section-toc.1-1.6.2.1.1"><a href="#section-6.1" class="xref">6.1</a>.  <a href="#name-normative-references" class="xref">Normative References</a><a href="#section-toc.1-1.6.2.1.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.6.2.2">
                <p id="section-toc.1-1.6.2.2.1"><a href="#section-6.2" class="xref">6.2</a>.  <a href="#name-informative-references" class="xref">Informative References</a><a href="#section-toc.1-1.6.2.2.1" class="pilcrow">¶</a></p>
</li>
</ul>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.7">
            <p id="section-toc.1-1.7.1"><a href="#section-appendix.a" class="xref"></a><a href="#name-acknowledgements" class="xref">Acknowledgements</a><a href="#section-toc.1-1.7.1" class="pilcrow">¶</a></p>
</li>
<li class="toc ulEmpty" id="section-toc.1-1.8">
            <p id="section-toc.1-1.8.1"><a href="#section-appendix.b" class="xref"></a><a href="#name-authors-addresses" class="xref">Authors' Addresses</a><a href="#section-toc.1-1.8.1" class="pilcrow">¶</a></p>
</li>
</ul>
</nav>
</section>
</div>
<div id="introduction">
<section id="section-1">
      <h2 id="name-introduction">
<a href="#section-1" class="section-number selfRef">1. </a><a href="#name-introduction" class="section-name selfRef">Introduction</a>
      </h2>
<p id="section-1-1">JSON Web Tokens, also known as JWTs <span>[<a href="#RFC7519" class="xref">RFC7519</a>]</span>, are URL-safe JSON-based security tokens 
that contain a set of claims that can be signed and/or encrypted.
The JWT specification has seen rapid adoption because it encapsulates
security-relevant information in one easy-to-protect location, and because
it is easy to implement using widely available tools.
One application area in which JWTs are commonly used is representing digital identity information,
such as OpenID Connect ID Tokens <span>[<a href="#OpenID.Core" class="xref">OpenID.Core</a>]</span>
and OAuth 2.0 <span>[<a href="#RFC6749" class="xref">RFC6749</a>]</span> access tokens and
      refresh tokens, the details of which are deployment-specific.<a href="#section-1-1" class="pilcrow">¶</a></p>
<p id="section-1-2">Since the JWT specification was published, there have been several widely published
attacks on implementations and deployments.
Such attacks are the result of under-specified security mechanisms, as well as incomplete
implementations and incorrect usage by applications.<a href="#section-1-2" class="pilcrow">¶</a></p>
<p id="section-1-3">The goal of this document is to facilitate secure implementation and deployment of JWTs.
Many of the recommendations in this document are about
implementation and use of the cryptographic mechanisms underlying JWTs that are defined by
JSON Web Signature (JWS) <span>[<a href="#RFC7515" class="xref">RFC7515</a>]</span>,
JSON Web Encryption (JWE) <span>[<a href="#RFC7516" class="xref">RFC7516</a>]</span>, and
JSON Web Algorithms (JWA) <span>[<a href="#RFC7518" class="xref">RFC7518</a>]</span>.
Others are about use of the JWT claims themselves.<a href="#section-1-3" class="pilcrow">¶</a></p>
<p id="section-1-4">These are intended to be minimum recommendations for the use of JWTs
in the vast majority of implementation
and deployment scenarios. Other specifications that reference this document can have
stricter requirements related to one or more aspects of the format, based on their
particular circumstances; when that is the case, implementers are advised to adhere
to those stricter requirements. Furthermore, this document provides a floor, not a ceiling,
so stronger options are always allowed (e.g., depending on differing evaluations of the
importance of cryptographic strength vs. computational load).<a href="#section-1-4" class="pilcrow">¶</a></p>
<p id="section-1-5">Community knowledge about the strength of various algorithms and feasible attacks can
change quickly, and experience shows that a Best Current Practice (BCP) document about
security is a point-in-time statement. Readers are advised to seek out any errata or
updates that apply to this document.<a href="#section-1-5" class="pilcrow">¶</a></p>
<div id="target-audience">
<section id="section-1.1">
        <h3 id="name-target-audience">
<a href="#section-1.1" class="section-number selfRef">1.1. </a><a href="#name-target-audience" class="section-name selfRef">Target Audience</a>
        </h3>
<p id="section-1.1-1">The intended audiences of this document are:<a href="#section-1.1-1" class="pilcrow">¶</a></p>
<ul>
<li id="section-1.1-2.1">Implementers of JWT libraries (and the JWS and JWE libraries
   used by those libraries),<a href="#section-1.1-2.1" class="pilcrow">¶</a>
</li>
<li id="section-1.1-2.2">Implementers of code that uses such libraries (to the extent that some mechanisms may
not be provided by libraries, or until they are), and<a href="#section-1.1-2.2" class="pilcrow">¶</a>
</li>
<li id="section-1.1-2.3">Developers of specifications that rely on JWTs, both inside and
   outside the IETF.<a href="#section-1.1-2.3" class="pilcrow">¶</a>
</li>
</ul>
</section>
</div>
<div id="conventions-used-in-this-document">
<section id="section-1.2">
        <h3 id="name-conventions-used-in-this-do">
<a href="#section-1.2" class="section-number selfRef">1.2. </a><a href="#name-conventions-used-in-this-do" class="section-name selfRef">Conventions Used in this Document</a>
        </h3>
<p id="section-1.2-1">                                                                     
    The key words "<span class="bcp14">MUST</span>", "<span class="bcp14">MUST NOT</span>",
    "<span class="bcp14">REQUIRED</span>", "<span class="bcp14">SHALL</span>", "<span class="bcp14">SHALL NOT</span>", "<span class="bcp14">SHOULD</span>", "<span class="bcp14">SHOULD NOT</span>",
    "<span class="bcp14">RECOMMENDED</span>", "<span class="bcp14">NOT RECOMMENDED</span>",              
    "<span class="bcp14">MAY</span>", and "<span class="bcp14">OPTIONAL</span>" in this document are
    to be interpreted as           
    described in BCP 14 <span>[<a href="#RFC2119" class="xref">RFC2119</a>]</span> <span>[<a href="#RFC8174" class="xref">RFC8174</a>]</span> 
    when, and only when, they appear in all capitals, as shown here.<a href="#section-1.2-1" class="pilcrow">¶</a></p>
</section>
</div>
</section>
</div>
<div id="threats-and-vulnerabilities">
<section id="section-2">
      <h2 id="name-threats-and-vulnerabilities">
<a href="#section-2" class="section-number selfRef">2. </a><a href="#name-threats-and-vulnerabilities" class="section-name selfRef">Threats and Vulnerabilities</a>
      </h2>
<p id="section-2-1">This section lists some known and possible problems with JWT
      implementations and deployments. 
Each problem description is followed by references to one or more mitigations to those problems.<a href="#section-2-1" class="pilcrow">¶</a></p>
<div id="weak-signatures-and-insufficient-signature-validation">
<section id="section-2.1">
        <h3 id="name-weak-signatures-and-insuffi">
<a href="#section-2.1" class="section-number selfRef">2.1. </a><a href="#name-weak-signatures-and-insuffi" class="section-name selfRef">Weak Signatures and Insufficient Signature Validation</a>
        </h3>
<p id="section-2.1-1">Signed JSON Web Tokens carry an explicit indication of the signing algorithm,
in the form of the "alg" Header Parameter, to facilitate cryptographic agility.
This, in conjunction with design flaws in some libraries and applications,
 has led to several attacks:<a href="#section-2.1-1" class="pilcrow">¶</a></p>
<ul>
<li id="section-2.1-2.1">The algorithm can be changed to "none" by an attacker, and some libraries would trust
this value and "validate" the JWT without checking any signature.<a href="#section-2.1-2.1" class="pilcrow">¶</a>
</li>
<li id="section-2.1-2.2">An "RS256" (RSA, 2048 bit) parameter value can be changed into
"HS256" (HMAC, SHA-256), and some libraries
would try to validate the signature using HMAC-SHA256 and using the RSA public key as the
HMAC shared secret (see <span>[<a href="#McLean" class="xref">McLean</a>]</span> and
   <span>[<a href="#CVE-2015-9235" class="xref">CVE-2015-9235</a>]</span>).<a href="#section-2.1-2.2" class="pilcrow">¶</a>
</li>
</ul>
<p id="section-2.1-3">For mitigations, see Sections <a href="#algorithm-verification" class="xref">3.1</a> and <a href="#appropriate-algorithms" class="xref">3.2</a>.<a href="#section-2.1-3" class="pilcrow">¶</a></p>
</section>
</div>
<div id="weak-symmetric-keys">
<section id="section-2.2">
        <h3 id="name-weak-symmetric-keys">
<a href="#section-2.2" class="section-number selfRef">2.2. </a><a href="#name-weak-symmetric-keys" class="section-name selfRef">Weak Symmetric Keys</a>
        </h3>
<p id="section-2.2-1">In addition, some applications use a keyed Message Authentication
 Code (MAC) algorithm, such as
"HS256", to sign tokens but supply a weak symmetric key with
insufficient entropy (such as a human-memorable password). Such keys
are vulnerable to offline brute-force or dictionary attacks once an
attacker gets hold of such a token <span>[<a href="#Langkemper" class="xref">Langkemper</a>]</span>.<a href="#section-2.2-1" class="pilcrow">¶</a></p>
<p id="section-2.2-2">For mitigations, see <a href="#key-entropy" class="xref">Section 3.5</a>.<a href="#section-2.2-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="incorrect-composition-of-encryption-and-signature">
<section id="section-2.3">
        <h3 id="name-incorrect-composition-of-en">
<a href="#section-2.3" class="section-number selfRef">2.3. </a><a href="#name-incorrect-composition-of-en" class="section-name selfRef">Incorrect Composition of Encryption and Signature</a>
        </h3>
<p id="section-2.3-1">Some libraries that decrypt a JWE-encrypted JWT to obtain a JWS-signed object
do not always validate the internal signature.<a href="#section-2.3-1" class="pilcrow">¶</a></p>
<p id="section-2.3-2">For mitigations, see <a href="#validate-crypto" class="xref">Section 3.3</a>.<a href="#section-2.3-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="plaintext-leakage-through-analysis-of-ciphertext-length">
<section id="section-2.4">
        <h3 id="name-plaintext-leakage-through-a">
<a href="#section-2.4" class="section-number selfRef">2.4. </a><a href="#name-plaintext-leakage-through-a" class="section-name selfRef">Plaintext Leakage through Analysis of Ciphertext Length</a>
        </h3>
<p id="section-2.4-1">Many encryption algorithms leak information about the length of the
 plaintext, with a varying amount of 
leakage depending on the algorithm and mode of operation. This problem is exacerbated
when the plaintext is initially compressed, because the length of the
compressed plaintext and, thus, 
the ciphertext 
depends not only on the length of the original plaintext but also
on its content.
Compression attacks are particularly
powerful when there is attacker-controlled data in the same compression
space as secret data, which is the case for some attacks on HTTPS.<a href="#section-2.4-1" class="pilcrow">¶</a></p>
<p id="section-2.4-2">See <span>[<a href="#Kelsey" class="xref">Kelsey</a>]</span> for general background
on compression and encryption and <span>[<a href="#Alawatugoda" class="xref">Alawatugoda</a>]</span> for a specific example of attacks on HTTP cookies.<a href="#section-2.4-2" class="pilcrow">¶</a></p>
<p id="section-2.4-3">For mitigations, see <a href="#no-compression" class="xref">Section 3.6</a>.<a href="#section-2.4-3" class="pilcrow">¶</a></p>
</section>
</div>
<div id="insecure-use-of-elliptic-curve-encryption">
<section id="section-2.5">
        <h3 id="name-insecure-use-of-elliptic-cu">
<a href="#section-2.5" class="section-number selfRef">2.5. </a><a href="#name-insecure-use-of-elliptic-cu" class="section-name selfRef">Insecure Use of Elliptic Curve Encryption</a>
        </h3>
<p id="section-2.5-1">Per <span>[<a href="#Sanso" class="xref">Sanso</a>]</span>, several Javascript
 Object Signing and Encryption (JOSE) libraries
 fail to validate their inputs correctly 
when performing elliptic curve key agreement (the "ECDH-ES" algorithm).
An attacker that is able to send JWEs of its choosing that use invalid curve points and
observe the cleartext outputs resulting from decryption with the invalid curve points
can use this vulnerability to recover the recipient's private key.<a href="#section-2.5-1" class="pilcrow">¶</a></p>
<p id="section-2.5-2">For mitigations, see <a href="#validate-inputs" class="xref">Section 3.4</a>.<a href="#section-2.5-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="multiplicity-of-json-encodings">
<section id="section-2.6">
        <h3 id="name-multiplicity-of-json-encodi">
<a href="#section-2.6" class="section-number selfRef">2.6. </a><a href="#name-multiplicity-of-json-encodi" class="section-name selfRef">Multiplicity of JSON Encodings</a>
        </h3>
<p id="section-2.6-1">Previous versions of the JSON format, such as the obsoleted <span>[<a href="#RFC7159" class="xref">RFC7159</a>]</span>, 
allowed several different character
encodings: UTF-8, UTF-16, and UTF-32. This is not the case anymore, with the latest
standard <span>[<a href="#RFC8259" class="xref">RFC8259</a>]</span> only allowing UTF-8 except
for internal use within a "closed ecosystem". 
This ambiguity, where older implementations and those used within closed environments may generate
non-standard encodings, may result in the JWT being
misinterpreted by its recipient. This, in turn, could be used by a malicious sender to bypass
the recipient's validation checks.<a href="#section-2.6-1" class="pilcrow">¶</a></p>
<p id="section-2.6-2">For mitigations, see <a href="#use-utf8" class="xref">Section 3.7</a>.<a href="#section-2.6-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="substitution">
<section id="section-2.7">
        <h3 id="name-substitution-attacks">
<a href="#section-2.7" class="section-number selfRef">2.7. </a><a href="#name-substitution-attacks" class="section-name selfRef">Substitution Attacks</a>
        </h3>
<p id="section-2.7-1">There are attacks in which one recipient will be given a JWT that was intended for it
and will attempt to use it at a different recipient for which that JWT was not intended.
For instance, if an OAuth 2.0 <span>[<a href="#RFC6749" class="xref">RFC6749</a>]</span> access
token is legitimately presented to an 
OAuth 2.0 protected resource for which it is intended, that protected resource might then present
that same access token to a different protected resource for which the access token is not intended,
in an attempt to gain access. If such situations are not caught, this can result in
the attacker gaining access to resources that it is not entitled to access.<a href="#section-2.7-1" class="pilcrow">¶</a></p>
<p id="section-2.7-2">For mitigations, see Sections <a href="#validate-iss-sub" class="xref">3.8</a> and <a href="#use-aud" class="xref">3.9</a>.<a href="#section-2.7-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="cross-jwt-confusion">
<section id="section-2.8">
        <h3 id="name-cross-jwt-confusion">
<a href="#section-2.8" class="section-number selfRef">2.8. </a><a href="#name-cross-jwt-confusion" class="section-name selfRef">Cross-JWT Confusion</a>
        </h3>
<p id="section-2.8-1">As JWTs are being used by more different protocols in diverse
 application areas, it becomes increasingly 
important to prevent cases of JWT tokens that have been issued for one purpose
being subverted and used for another.
Note that this is a specific type of substitution attack.
If the JWT could be used in an application context in which it could be
confused with other kinds of JWTs, 
then mitigations <span class="bcp14">MUST</span> be employed to prevent these substitution attacks.<a href="#section-2.8-1" class="pilcrow">¶</a></p>
<p id="section-2.8-2">For mitigations, see Sections <a href="#validate-iss-sub" class="xref">3.8</a>, <a href="#use-aud" class="xref">3.9</a>, 
<a href="#use-typ" class="xref">3.11</a>, and <a href="#preventing-confusion" class="xref">3.12</a>.<a href="#section-2.8-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="indirect-attacks-on-the-server">
<section id="section-2.9">
        <h3 id="name-indirect-attacks-on-the-ser">
<a href="#section-2.9" class="section-number selfRef">2.9. </a><a href="#name-indirect-attacks-on-the-ser" class="section-name selfRef">Indirect Attacks on the Server</a>
        </h3>
<p id="section-2.9-1">Various JWT claims are used by the recipient to perform lookup operations,
such as database and Lightweight Directory Access Protocol (LDAP) searches.
Others include URLs that are similarly looked up by the server. Any of these claims can be used by
an attacker as vectors for injection attacks or server-side request forgery (SSRF) attacks.<a href="#section-2.9-1" class="pilcrow">¶</a></p>
<p id="section-2.9-2">For mitigations, see <a href="#do-not-trust-claims" class="xref">Section 3.10</a>.<a href="#section-2.9-2" class="pilcrow">¶</a></p>
</section>
</div>
</section>
</div>
<div id="BP">
<section id="section-3">
      <h2 id="name-best-practices">
<a href="#section-3" class="section-number selfRef">3. </a><a href="#name-best-practices" class="section-name selfRef">Best Practices</a>
      </h2>
<p id="section-3-1">The best practices listed below should be applied by practitioners
to mitigate the threats listed in the preceding section.<a href="#section-3-1" class="pilcrow">¶</a></p>
<div id="algorithm-verification">
<section id="section-3.1">
        <h3 id="name-perform-algorithm-verificat">
<a href="#section-3.1" class="section-number selfRef">3.1. </a><a href="#name-perform-algorithm-verificat" class="section-name selfRef">Perform Algorithm Verification</a>
        </h3>
<p id="section-3.1-1">Libraries <span class="bcp14">MUST</span> enable the caller to specify a
 supported set of algorithms and 
<span class="bcp14">MUST NOT</span> use any other algorithms when performing cryptographic operations.
The library <span class="bcp14">MUST</span> ensure that the "alg" or "enc" header specifies the same algorithm
that is used for the cryptographic operation.
Moreover, each key <span class="bcp14">MUST</span> be used with exactly one algorithm,
and this <span class="bcp14">MUST</span> be checked when the cryptographic operation is performed.<a href="#section-3.1-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="appropriate-algorithms">
<section id="section-3.2">
        <h3 id="name-use-appropriate-algorithms">
<a href="#section-3.2" class="section-number selfRef">3.2. </a><a href="#name-use-appropriate-algorithms" class="section-name selfRef">Use Appropriate Algorithms</a>
        </h3>
<p id="section-3.2-1">As <span><a href="https://www.rfc-editor.org/rfc/rfc7515#section-5.2" class="relref">Section 5.2</a> of [<a href="#RFC7515" class="xref">RFC7515</a>]</span> says,
"it is an application decision which algorithms may 
be used in a given context. Even if a JWS can be successfully
validated, unless the algorithm(s) used in the JWS are acceptable to
the application, it <span class="bcp14">SHOULD</span> consider the JWS to be invalid."<a href="#section-3.2-1" class="pilcrow">¶</a></p>
<p id="section-3.2-2">Therefore, applications <span class="bcp14">MUST</span> only allow the use of
 cryptographically current algorithms 
that meet the security requirements of the application.
This set will vary over time as new algorithms are introduced
and existing algorithms are deprecated due to discovered cryptographic weaknesses.
Applications <span class="bcp14">MUST</span> therefore be designed to enable cryptographic agility.<a href="#section-3.2-2" class="pilcrow">¶</a></p>
<p id="section-3.2-3">That said, if a JWT is cryptographically protected end-to-end by a
 transport layer, such as TLS 
using cryptographically current algorithms, there may be no need to apply another layer of
cryptographic protections to the JWT.
In such cases, the use of the "none" algorithm can be perfectly acceptable.
The "none" algorithm should only be used when the JWT is cryptographically protected by other means.
JWTs using "none" are often used in application contexts in which the content is optionally signed;
then, the URL-safe claims representation and processing can be the same in both
the signed and unsigned cases. 
JWT libraries <span class="bcp14">SHOULD NOT</span> generate JWTs using "none" unless
explicitly requested to do so by the caller. 
Similarly, JWT libraries <span class="bcp14">SHOULD NOT</span> consume JWTs using "none"
 unless explicitly requested by the caller.<a href="#section-3.2-3" class="pilcrow">¶</a></p>
<p id="section-3.2-4">Applications <span class="bcp14">SHOULD</span> follow these algorithm-specific recommendations:<a href="#section-3.2-4" class="pilcrow">¶</a></p>
<ul>
<li id="section-3.2-5.1">Avoid all RSA-PKCS1 v1.5 encryption algorithms (<span>[<a href="#RFC8017" class="xref">RFC8017</a>], <a href="https://www.rfc-editor.org/rfc/rfc8017#section-7.2" class="relref">Section 7.2</a></span>), preferring
   RSAES-OAEP
   (<span>[<a href="#RFC8017" class="xref">RFC8017</a>], <a href="https://www.rfc-editor.org/rfc/rfc8017#section-7.1" class="relref">Section 7.1</a></span>).<a href="#section-3.2-5.1" class="pilcrow">¶</a>
</li>
<li id="section-3.2-5.2">Elliptic Curve Digital Signature Algorithm (ECDSA) signatures <span>[<a href="#ANSI-X962-2005" class="xref">ANSI-X962-2005</a>]</span> require a unique random value for every message
   that is signed. 
If even just a few bits of the random value are predictable across multiple messages, then
the security of the signature scheme may be compromised. In the worst case,
the private key may be recoverable by an attacker. To counter these attacks,
JWT libraries <span class="bcp14">SHOULD</span> implement ECDSA using the deterministic
approach defined in <span>[<a href="#RFC6979" class="xref">RFC6979</a>]</span>. 
This approach is completely compatible with existing ECDSA verifiers and so can be implemented
without new algorithm identifiers being required.<a href="#section-3.2-5.2" class="pilcrow">¶</a>
</li>
</ul>
</section>
</div>
<div id="validate-crypto">
<section id="section-3.3">
        <h3 id="name-validate-all-cryptographic-">
<a href="#section-3.3" class="section-number selfRef">3.3. </a><a href="#name-validate-all-cryptographic-" class="section-name selfRef">Validate All Cryptographic Operations</a>
        </h3>
<p id="section-3.3-1">All cryptographic operations used in the JWT <span class="bcp14">MUST</span> be
 validated and the entire JWT <span class="bcp14">MUST</span> be rejected 
if any of them fail to validate.
This is true not only of JWTs with a single set of Header Parameters
but also for Nested JWTs in which both outer and inner operations <span class="bcp14">MUST</span> be validated
using the keys and algorithms supplied by the application.<a href="#section-3.3-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="validate-inputs">
<section id="section-3.4">
        <h3 id="name-validate-cryptographic-inpu">
<a href="#section-3.4" class="section-number selfRef">3.4. </a><a href="#name-validate-cryptographic-inpu" class="section-name selfRef">Validate Cryptographic Inputs</a>
        </h3>
<p id="section-3.4-1">Some cryptographic operations, such as Elliptic Curve Diffie-Hellman key agreement
("ECDH-ES"), take inputs that may contain invalid values. This includes points not on
the specified elliptic curve 
or other invalid points (e.g., <span>[<a href="#Valenta" class="xref">Valenta</a>]</span>, Section 7.1).
The JWS/JWE library itself must validate these inputs before using them,
or it must use underlying cryptographic libraries that do so (or both!).<a href="#section-3.4-1" class="pilcrow">¶</a></p>
<p id="section-3.4-2">Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) ephemeral
 public key (epk) inputs should be validated 
 according to the recipient's 
chosen elliptic curve. For the NIST prime-order curves P-256, P-384, and P-521,
validation <span class="bcp14">MUST</span> 
be performed according to Section 5.6.2.3.4 (ECC Partial Public-Key Validation
Routine) of "Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography" <span>[<a href="#nist-sp-800-56a-r3" class="xref">nist-sp-800-56a-r3</a>]</span>.
If the "X25519" or "X448" <span>[<a href="#RFC8037" class="xref">RFC8037</a>]</span> algorithms are used,
then the security considerations in <span>[<a href="#RFC8037" class="xref">RFC8037</a>]</span> apply.<a href="#section-3.4-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="key-entropy">
<section id="section-3.5">
        <h3 id="name-ensure-cryptographic-keys-h">
<a href="#section-3.5" class="section-number selfRef">3.5. </a><a href="#name-ensure-cryptographic-keys-h" class="section-name selfRef">Ensure Cryptographic Keys Have Sufficient Entropy</a>
        </h3>
<p id="section-3.5-1">The Key Entropy and Random Values advice in <span><a href="https://www.rfc-editor.org/rfc/rfc7515#section-10.1" class="relref">Section 10.1</a> of [<a href="#RFC7515" class="xref">RFC7515</a>]</span> and the
 Password Considerations in <span><a href="https://www.rfc-editor.org/rfc/rfc7518#section-8.8" class="relref">Section 8.8</a> of [<a href="#RFC7518" class="xref">RFC7518</a>]</span>
          <span class="bcp14">MUST</span> be followed.
In particular, human-memorizable passwords <span class="bcp14">MUST NOT</span> be directly used
as the key to a keyed-MAC algorithm such as "HS256".
Moreover, passwords should only be used to perform key encryption, rather
than content encryption, 
as described in <span><a href="https://www.rfc-editor.org/rfc/rfc7518#section-4.8" class="relref">Section 4.8</a> of [<a href="#RFC7518" class="xref">RFC7518</a>]</span>.
Note that even when used for key encryption, password-based encryption is
 still subject to brute-force attacks.<a href="#section-3.5-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="no-compression">
<section id="section-3.6">
        <h3 id="name-avoid-compression-of-encryp">
<a href="#section-3.6" class="section-number selfRef">3.6. </a><a href="#name-avoid-compression-of-encryp" class="section-name selfRef">Avoid Compression of Encryption Inputs</a>
        </h3>
<p id="section-3.6-1">Compression of data <span class="bcp14">SHOULD NOT</span> be done before encryption, because
such compressed data often reveals information about the plaintext.<a href="#section-3.6-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="use-utf8">
<section id="section-3.7">
        <h3 id="name-use-utf-8">
<a href="#section-3.7" class="section-number selfRef">3.7. </a><a href="#name-use-utf-8" class="section-name selfRef">Use UTF-8</a>
        </h3>
<p id="section-3.7-1"><span>[<a href="#RFC7515" class="xref">RFC7515</a>]</span>, <span>[<a href="#RFC7516" class="xref">RFC7516</a>]</span>, and <span>[<a href="#RFC7519" class="xref">RFC7519</a>]</span> all
 specify that UTF-8 be used for encoding and decoding JSON 
used in Header Parameters and JWT Claims Sets. This is also in line with the
latest JSON specification <span>[<a href="#RFC8259" class="xref">RFC8259</a>]</span>. 
Implementations and applications <span class="bcp14">MUST</span> do this and not use or admit the use of
other Unicode encodings for these purposes.<a href="#section-3.7-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="validate-iss-sub">
<section id="section-3.8">
        <h3 id="name-validate-issuer-and-subject">
<a href="#section-3.8" class="section-number selfRef">3.8. </a><a href="#name-validate-issuer-and-subject" class="section-name selfRef">Validate Issuer and Subject</a>
        </h3>
<p id="section-3.8-1">When a JWT contains an "iss" (issuer) claim, the application
 <span class="bcp14">MUST</span> validate that the cryptographic keys 
used for the cryptographic operations in the JWT belong to the issuer.
If they do not, the application <span class="bcp14">MUST</span> reject the JWT.<a href="#section-3.8-1" class="pilcrow">¶</a></p>
<p id="section-3.8-2">The means of determining the keys owned by an issuer is application-specific.
As one example, OpenID Connect <span>[<a href="#OpenID.Core" class="xref">OpenID.Core</a>]</span>
issuer values are "https" URLs 
that reference a JSON metadata document that contains a "jwks_uri" value that is
an "https" URL from which the issuer's keys are retrieved as a JWK Set <span>[<a href="#RFC7517" class="xref">RFC7517</a>]</span>. 
This same mechanism is used by <span>[<a href="#RFC8414" class="xref">RFC8414</a>]</span>.
Other applications may use different means of binding keys to issuers.<a href="#section-3.8-2" class="pilcrow">¶</a></p>
<p id="section-3.8-3">Similarly, when the JWT contains a "sub" (subject) claim, the
 application <span class="bcp14">MUST</span> validate that 
the subject value corresponds to a valid subject and/or issuer-subject pair at the application.
This may include confirming that the issuer is trusted by the application.
If the issuer, subject, or the pair are invalid, the application
 <span class="bcp14">MUST</span> reject the JWT.<a href="#section-3.8-3" class="pilcrow">¶</a></p>
</section>
</div>
<div id="use-aud">
<section id="section-3.9">
        <h3 id="name-use-and-validate-audience">
<a href="#section-3.9" class="section-number selfRef">3.9. </a><a href="#name-use-and-validate-audience" class="section-name selfRef">Use and Validate Audience</a>
        </h3>
<p id="section-3.9-1">If the same issuer can issue JWTs that are intended for use by more
 than one relying party or application, 
the JWT <span class="bcp14">MUST</span> contain an "aud" (audience) claim that can be used
to determine whether the JWT 
is being used by an intended party or was substituted by an attacker at an unintended party.<a href="#section-3.9-1" class="pilcrow">¶</a></p>
<p id="section-3.9-2">In such cases, the relying party or application <span class="bcp14">MUST</span>
 validate the audience value, 
and if the audience value is not present or not associated with the recipient,
it <span class="bcp14">MUST</span> reject the JWT.<a href="#section-3.9-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="do-not-trust-claims">
<section id="section-3.10">
        <h3 id="name-do-not-trust-received-claim">
<a href="#section-3.10" class="section-number selfRef">3.10. </a><a href="#name-do-not-trust-received-claim" class="section-name selfRef">Do Not Trust Received Claims</a>
        </h3>
<p id="section-3.10-1">The "kid" (key ID) header is used by the relying application to
 perform key lookup. Applications 
should ensure that this does not create SQL or LDAP injection vulnerabilities by validating
and/or sanitizing the received value.<a href="#section-3.10-1" class="pilcrow">¶</a></p>
<p id="section-3.10-2">Similarly, blindly following a "jku" (JWK set URL) or "x5u" (X.509 URL) header,
which may contain an arbitrary URL,
could result in server-side request forgery (SSRF) attacks. Applications
<span class="bcp14">SHOULD</span> protect against such 
attacks, e.g., by matching the URL to a whitelist of allowed locations
and ensuring no cookies are sent in the GET request.<a href="#section-3.10-2" class="pilcrow">¶</a></p>
</section>
</div>
<div id="use-typ">
<section id="section-3.11">
        <h3 id="name-use-explicit-typing">
<a href="#section-3.11" class="section-number selfRef">3.11. </a><a href="#name-use-explicit-typing" class="section-name selfRef">Use Explicit Typing</a>
        </h3>
<p id="section-3.11-1">Sometimes, one kind of JWT can be confused for another. If a particular
kind of JWT is subject to such confusion, that JWT can include an explicit
JWT type value, and the validation rules can specify checking the type.
This mechanism can prevent such confusion.
Explicit JWT typing is accomplished by using the "typ" Header Parameter.
For instance, the <span>[<a href="#RFC8417" class="xref">RFC8417</a>]</span> specification uses
the "application/secevent+jwt" media type 
to perform explicit typing of Security Event Tokens (SETs).<a href="#section-3.11-1" class="pilcrow">¶</a></p>
<p id="section-3.11-2">Per the definition of "typ" in <span><a href="https://www.rfc-editor.org/rfc/rfc7515#section-4.1.9" class="relref">Section 4.1.9</a> of [<a href="#RFC7515" class="xref">RFC7515</a>]</span>,
it is <span class="bcp14">RECOMMENDED</span> that the "application/" prefix be omitted from the "typ" value.
Therefore, for example, the "typ" value used to explicitly include a type for a SET
<span class="bcp14">SHOULD</span> be "secevent+jwt".
When explicit typing is employed for a JWT, it is <span class="bcp14">RECOMMENDED</span>
that a media type name of the format 
"application/example+jwt" be used, where "example" is replaced by the
 identifier for the specific kind of JWT.<a href="#section-3.11-2" class="pilcrow">¶</a></p>
<p id="section-3.11-3">When applying explicit typing to a Nested JWT, the "typ" Header
 Parameter containing the explicit type value 
<span class="bcp14">MUST</span> be present in the inner JWT of the Nested JWT (the JWT
whose payload is the JWT Claims Set). 
In some cases, the same "typ" Header Parameter value will be present in the outer JWT as well,
to explicitly type the entire Nested JWT.<a href="#section-3.11-3" class="pilcrow">¶</a></p>
<p id="section-3.11-4">Note that the use of explicit typing may not achieve disambiguation
 from existing kinds of JWTs, 
as the validation rules for existing kinds of JWTs often do not use the "typ" Header Parameter value.
Explicit typing is <span class="bcp14">RECOMMENDED</span> for new uses of JWTs.<a href="#section-3.11-4" class="pilcrow">¶</a></p>
</section>
</div>
<div id="preventing-confusion">
<section id="section-3.12">
        <h3 id="name-use-mutually-exclusive-vali">
<a href="#section-3.12" class="section-number selfRef">3.12. </a><a href="#name-use-mutually-exclusive-vali" class="section-name selfRef">Use Mutually Exclusive Validation Rules for Different Kinds of JWTs</a>
        </h3>
<p id="section-3.12-1">Each application of JWTs defines a profile specifying the required
 and optional JWT claims 
and the validation rules associated with them.
If more than one kind of JWT can be issued by the same issuer,
the validation rules for those JWTs <span class="bcp14">MUST</span> be written such that
they are mutually exclusive, 
rejecting JWTs of the wrong kind.
To prevent substitution of JWTs from one context into another,
application developers may employ a number of strategies:<a href="#section-3.12-1" class="pilcrow">¶</a></p>
<ul>
<li id="section-3.12-2.1">Use explicit typing for different kinds of JWTs.
Then the distinct "typ" values can be used to differentiate between the
   different kinds of JWTs.<a href="#section-3.12-2.1" class="pilcrow">¶</a>
</li>
<li id="section-3.12-2.2">Use different sets of required claims or different required claim values.
Then the validation rules for one kind of JWT will reject those with different
   claims or values.<a href="#section-3.12-2.2" class="pilcrow">¶</a>
</li>
<li id="section-3.12-2.3">Use different sets of required Header Parameters or different
   required Header Parameter values. 
Then the validation rules for one kind of JWT will reject those with different
   Header Parameters or values.<a href="#section-3.12-2.3" class="pilcrow">¶</a>
</li>
<li id="section-3.12-2.4">Use different keys for different kinds of JWTs.
Then the keys used to validate one kind of JWT will fail to validate other kinds of JWTs.<a href="#section-3.12-2.4" class="pilcrow">¶</a>
</li>
<li id="section-3.12-2.5">Use different "aud" values for different uses of JWTs from the same issuer.
Then audience validation will reject JWTs substituted into inappropriate contexts.<a href="#section-3.12-2.5" class="pilcrow">¶</a>
</li>
<li id="section-3.12-2.6">Use different issuers for different kinds of JWTs.
Then the distinct "iss" values can be used to segregate the different kinds of JWTs.<a href="#section-3.12-2.6" class="pilcrow">¶</a>
</li>
</ul>
<p id="section-3.12-3">Given the broad diversity of JWT usage and applications,
the best combination of types, required claims, values, Header Parameters, key usages, and issuers
to differentiate among different kinds of JWTs
will, in general, be application-specific.
As discussed in <a href="#use-typ" class="xref">Section 3.11</a>, for new JWT
 applications, the use of explicit typing is
 <span class="bcp14">RECOMMENDED</span>.<a href="#section-3.12-3" class="pilcrow">¶</a></p>
</section>
</div>
</section>
</div>
<div id="security-considerations">
<section id="section-4">
      <h2 id="name-security-considerations">
<a href="#section-4" class="section-number selfRef">4. </a><a href="#name-security-considerations" class="section-name selfRef">Security Considerations</a>
      </h2>
<p id="section-4-1">This entire document is about security considerations when
      implementing and deploying JSON Web Tokens.<a href="#section-4-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="iana-considerations">
<section id="section-5">
      <h2 id="name-iana-considerations">
<a href="#section-5" class="section-number selfRef">5. </a><a href="#name-iana-considerations" class="section-name selfRef">IANA Considerations</a>
      </h2>
<p id="section-5-1">This document has no IANA actions.<a href="#section-5-1" class="pilcrow">¶</a></p>
</section>
</div>
<section id="section-6">
      <h2 id="name-references">
<a href="#section-6" class="section-number selfRef">6. </a><a href="#name-references" class="section-name selfRef">References</a>
      </h2>
<section id="section-6.1">
        <h3 id="name-normative-references">
<a href="#section-6.1" class="section-number selfRef">6.1. </a><a href="#name-normative-references" class="section-name selfRef">Normative References</a>
        </h3>
<dl class="references">
<dt id="nist-sp-800-56a-r3">[nist-sp-800-56a-r3]</dt>
<dd>
<span class="refAuthor">Barker, E.</span><span class="refAuthor">, Chen, L.</span><span class="refAuthor">, Roginsky, A.</span><span class="refAuthor">, Vassilev, A.</span><span class="refAuthor">, and R. Davis</span>, <span class="refTitle">"Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography"</span>, <span class="seriesInfo">NIST Special Publication 800-56A Revision 3</span>, <span class="seriesInfo">DOI 10.6028/NIST.SP.800-56Ar3</span>, <time datetime="2018-04">April 2018</time>, <span>&lt;<a href="https://doi.org/10.6028/NIST.SP.800-56Ar3">https://doi.org/10.6028/NIST.SP.800-56Ar3</a>&gt;</span>. </dd>
<dt id="RFC2119">[RFC2119]</dt>
<dd>
<span class="refAuthor">Bradner, S.</span>, <span class="refTitle">"Key words for use in RFCs to Indicate Requirement Levels"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 2119</span>, <span class="seriesInfo">DOI 10.17487/RFC2119</span>, <time datetime="1997-03">March 1997</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc2119">https://www.rfc-editor.org/info/rfc2119</a>&gt;</span>. </dd>
<dt id="RFC6979">[RFC6979]</dt>
<dd>
<span class="refAuthor">Pornin, T.</span>, <span class="refTitle">"Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)"</span>, <span class="seriesInfo">RFC 6979</span>, <span class="seriesInfo">DOI 10.17487/RFC6979</span>, <time datetime="2013-08">August 2013</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc6979">https://www.rfc-editor.org/info/rfc6979</a>&gt;</span>. </dd>
<dt id="RFC7515">[RFC7515]</dt>
<dd>
<span class="refAuthor">Jones, M.</span><span class="refAuthor">, Bradley, J.</span><span class="refAuthor">, and N. Sakimura</span>, <span class="refTitle">"JSON Web Signature (JWS)"</span>, <span class="seriesInfo">RFC 7515</span>, <span class="seriesInfo">DOI 10.17487/RFC7515</span>, <time datetime="2015-05">May 2015</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc7515">https://www.rfc-editor.org/info/rfc7515</a>&gt;</span>. </dd>
<dt id="RFC7516">[RFC7516]</dt>
<dd>
<span class="refAuthor">Jones, M.</span><span class="refAuthor"> and J. Hildebrand</span>, <span class="refTitle">"JSON Web Encryption (JWE)"</span>, <span class="seriesInfo">RFC 7516</span>, <span class="seriesInfo">DOI 10.17487/RFC7516</span>, <time datetime="2015-05">May 2015</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc7516">https://www.rfc-editor.org/info/rfc7516</a>&gt;</span>. </dd>
<dt id="RFC7518">[RFC7518]</dt>
<dd>
<span class="refAuthor">Jones, M.</span>, <span class="refTitle">"JSON Web Algorithms (JWA)"</span>, <span class="seriesInfo">RFC 7518</span>, <span class="seriesInfo">DOI 10.17487/RFC7518</span>, <time datetime="2015-05">May 2015</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc7518">https://www.rfc-editor.org/info/rfc7518</a>&gt;</span>. </dd>
<dt id="RFC7519">[RFC7519]</dt>
<dd>
<span class="refAuthor">Jones, M.</span><span class="refAuthor">, Bradley, J.</span><span class="refAuthor">, and N. Sakimura</span>, <span class="refTitle">"JSON Web Token (JWT)"</span>, <span class="seriesInfo">RFC 7519</span>, <span class="seriesInfo">DOI 10.17487/RFC7519</span>, <time datetime="2015-05">May 2015</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc7519">https://www.rfc-editor.org/info/rfc7519</a>&gt;</span>. </dd>
<dt id="RFC8017">[RFC8017]</dt>
<dd>
<span class="refAuthor">Moriarty, K., Ed.</span><span class="refAuthor">, Kaliski, B.</span><span class="refAuthor">, Jonsson, J.</span><span class="refAuthor">, and A. Rusch</span>, <span class="refTitle">"PKCS #1: RSA Cryptography Specifications Version 2.2"</span>, <span class="seriesInfo">RFC 8017</span>, <span class="seriesInfo">DOI 10.17487/RFC8017</span>, <time datetime="2016-11">November 2016</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8017">https://www.rfc-editor.org/info/rfc8017</a>&gt;</span>. </dd>
<dt id="RFC8037">[RFC8037]</dt>
<dd>
<span class="refAuthor">Liusvaara, I.</span>, <span class="refTitle">"CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)"</span>, <span class="seriesInfo">RFC 8037</span>, <span class="seriesInfo">DOI 10.17487/RFC8037</span>, <time datetime="2017-01">January 2017</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8037">https://www.rfc-editor.org/info/rfc8037</a>&gt;</span>. </dd>
<dt id="RFC8174">[RFC8174]</dt>
<dd>
<span class="refAuthor">Leiba, B.</span>, <span class="refTitle">"Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 8174</span>, <span class="seriesInfo">DOI 10.17487/RFC8174</span>, <time datetime="2017-05">May 2017</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8174">https://www.rfc-editor.org/info/rfc8174</a>&gt;</span>. </dd>
<dt id="RFC8259">[RFC8259]</dt>
<dd>
<span class="refAuthor">Bray, T., Ed.</span>, <span class="refTitle">"The JavaScript Object Notation (JSON) Data Interchange Format"</span>, <span class="seriesInfo">STD 90</span>, <span class="seriesInfo">RFC 8259</span>, <span class="seriesInfo">DOI 10.17487/RFC8259</span>, <time datetime="2017-12">December 2017</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8259">https://www.rfc-editor.org/info/rfc8259</a>&gt;</span>. </dd>
</dl>
</section>
<section id="section-6.2">
        <h3 id="name-informative-references">
<a href="#section-6.2" class="section-number selfRef">6.2. </a><a href="#name-informative-references" class="section-name selfRef">Informative References</a>
        </h3>
<dl class="references">
<dt id="Alawatugoda">[Alawatugoda]</dt>
<dd>
<span class="refAuthor">Alawatugoda, J.</span><span class="refAuthor">, Stebila, D.</span><span class="refAuthor">, and C. Boyd</span>, <span class="refTitle">"Protecting Encrypted Cookies from Compression Side-Channel Attacks"</span>, <span class="refContent">Financial Cryptography and Data Security, pp. 86-106</span>, <span class="seriesInfo">DOI 10.1007/978-3-662-47854-7_6</span>, <time datetime="2015-07">July 2015</time>, <span>&lt;<a href="https://doi.org/10.1007/978-3-662-47854-7_6">https://doi.org/10.1007/978-3-662-47854-7_6</a>&gt;</span>. </dd>
<dt id="ANSI-X962-2005">[ANSI-X962-2005]</dt>
<dd>
<span class="refAuthor">American National Standards Institute</span>, <span class="refTitle">"Public Key Cryptography for the Financial Services Industry: the Elliptic Curve Digital Signature Algorithm (ECDSA)"</span>, <span class="seriesInfo">ANSI X9.62-2005</span>, <time datetime="2005-11">November 2005</time>. </dd>
<dt id="CVE-2015-9235">[CVE-2015-9235]</dt>
<dd>
<span class="refAuthor">NIST</span>, <span class="refTitle">"CVE-2015-9235 Detail"</span>, <span class="refContent">National Vulnerability Database</span>, <time datetime="2018-05">May 2018</time>, <span>&lt;<a href="https://nvd.nist.gov/vuln/detail/CVE-2015-9235">https://nvd.nist.gov/vuln/detail/CVE-2015-9235</a>&gt;</span>. </dd>
<dt id="Kelsey">[Kelsey]</dt>
<dd>
<span class="refAuthor">Kelsey, J.</span>, <span class="refTitle">"Compression and Information Leakage of Plaintext"</span>, <span class="refContent">Fast Software Encryption, pp. 263-276</span>, <span class="seriesInfo">DOI 10.1007/3-540-45661-9_21</span>, <time datetime="2002-07">July 2002</time>, <span>&lt;<a href="https://doi.org/10.1007/3-540-45661-9_21">https://doi.org/10.1007/3-540-45661-9_21</a>&gt;</span>. </dd>
<dt id="Langkemper">[Langkemper]</dt>
<dd>
<span class="refAuthor">Langkemper, S.</span>, <span class="refTitle">"Attacking JWT authentication"</span>, <time datetime="2016-09">September 2016</time>, <span>&lt;<a href="https://www.sjoerdlangkemper.nl/2016/09/28/attacking-jwt-authentication/">https://www.sjoerdlangkemper.nl/2016/09/28/attacking-jwt-authentication/</a>&gt;</span>. </dd>
<dt id="McLean">[McLean]</dt>
<dd>
<span class="refAuthor">McLean, T.</span>, <span class="refTitle">"Critical vulnerabilities in JSON Web Token libraries"</span>, <time datetime="2015-03">March 2015</time>, <span>&lt;<a href="https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/">https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/</a>&gt;</span>. </dd>
<dt id="OpenID.Core">[OpenID.Core]</dt>
<dd>
<span class="refAuthor">Sakimura, N.</span><span class="refAuthor">, Bradley, J.</span><span class="refAuthor">, Jones, M.</span><span class="refAuthor">, de Medeiros, B.</span><span class="refAuthor">, and C. Mortimore</span>, <span class="refTitle">"OpenID Connect Core 1.0 incorporating errata set 1"</span>, <time datetime="2014-11">November 2014</time>, <span>&lt;<a href="https://openid.net/specs/openid-connect-core-1_0.html">https://openid.net/specs/openid-connect-core-1_0.html</a>&gt;</span>. </dd>
<dt id="RFC6749">[RFC6749]</dt>
<dd>
<span class="refAuthor">Hardt, D., Ed.</span>, <span class="refTitle">"The OAuth 2.0 Authorization Framework"</span>, <span class="seriesInfo">RFC 6749</span>, <span class="seriesInfo">DOI 10.17487/RFC6749</span>, <time datetime="2012-10">October 2012</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc6749">https://www.rfc-editor.org/info/rfc6749</a>&gt;</span>. </dd>
<dt id="RFC7159">[RFC7159]</dt>
<dd>
<span class="refAuthor">Bray, T., Ed.</span>, <span class="refTitle">"The JavaScript Object Notation (JSON) Data Interchange Format"</span>, <span class="seriesInfo">RFC 7159</span>, <span class="seriesInfo">DOI 10.17487/RFC7159</span>, <time datetime="2014-03">March 2014</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc7159">https://www.rfc-editor.org/info/rfc7159</a>&gt;</span>. </dd>
<dt id="RFC7517">[RFC7517]</dt>
<dd>
<span class="refAuthor">Jones, M.</span>, <span class="refTitle">"JSON Web Key (JWK)"</span>, <span class="seriesInfo">RFC 7517</span>, <span class="seriesInfo">DOI 10.17487/RFC7517</span>, <time datetime="2015-05">May 2015</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc7517">https://www.rfc-editor.org/info/rfc7517</a>&gt;</span>. </dd>
<dt id="RFC8414">[RFC8414]</dt>
<dd>
<span class="refAuthor">Jones, M.</span><span class="refAuthor">, Sakimura, N.</span><span class="refAuthor">, and J. Bradley</span>, <span class="refTitle">"OAuth 2.0 Authorization Server Metadata"</span>, <span class="seriesInfo">RFC 8414</span>, <span class="seriesInfo">DOI 10.17487/RFC8414</span>, <time datetime="2018-06">June 2018</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8414">https://www.rfc-editor.org/info/rfc8414</a>&gt;</span>. </dd>
<dt id="RFC8417">[RFC8417]</dt>
<dd>
<span class="refAuthor">Hunt, P., Ed.</span><span class="refAuthor">, Jones, M.</span><span class="refAuthor">, Denniss, W.</span><span class="refAuthor">, and M. Ansari</span>, <span class="refTitle">"Security Event Token (SET)"</span>, <span class="seriesInfo">RFC 8417</span>, <span class="seriesInfo">DOI 10.17487/RFC8417</span>, <time datetime="2018-07">July 2018</time>, <span>&lt;<a href="https://www.rfc-editor.org/info/rfc8417">https://www.rfc-editor.org/info/rfc8417</a>&gt;</span>. </dd>
<dt id="Sanso">[Sanso]</dt>
<dd>
<span class="refAuthor">Sanso, A.</span>, <span class="refTitle">"Critical Vulnerability Uncovered in JSON Encryption"</span>, <time datetime="2017-03">March 2017</time>, <span>&lt;<a href="https://blogs.adobe.com/security/2017/03/critical-vulnerability-uncovered-in-json-encryption.html">https://blogs.adobe.com/security/2017/03/critical-vulnerability-uncovered-in-json-encryption.html</a>&gt;</span>. </dd>
<dt id="Valenta">[Valenta]</dt>
<dd>
<span class="refAuthor">Valenta, L.</span><span class="refAuthor">, Sullivan, N.</span><span class="refAuthor">, Sanso, A.</span><span class="refAuthor">, and N. Heninger</span>, <span class="refTitle">"In search of CurveSwap: Measuring elliptic curve implementations in the wild"</span>, <time datetime="2018-03">March 2018</time>, <span>&lt;<a href="https://ia.cr/2018/298">https://ia.cr/2018/298</a>&gt;</span>. </dd>
</dl>
</section>
</section>
<div id="acknowledgements">
<section id="section-appendix.a">
      <h2 id="name-acknowledgements">
<a href="#name-acknowledgements" class="section-name selfRef">Acknowledgements</a>
      </h2>
<p id="section-appendix.a-1">Thanks to <span class="contact-name">Antonio Sanso</span> for bringing the
      "ECDH-ES" invalid point attack to the attention 
of JWE and JWT implementers. <span class="contact-name">Tim McLean</span> published the
RSA/HMAC confusion attack <span>[<a href="#McLean" class="xref">McLean</a>]</span>. 
Thanks to <span class="contact-name">Nat Sakimura</span> for advocating the use of
explicit typing. Thanks to <span class="contact-name">Neil Madden</span> for his 
numerous comments, and to
<span class="contact-name">Carsten Bormann</span>,
<span class="contact-name">Brian Campbell</span>,
<span class="contact-name">Brian Carpenter</span>,
<span class="contact-name">Alissa Cooper</span>,
<span class="contact-name">Roman Danyliw</span>,
<span class="contact-name">Ben Kaduk</span>,
<span class="contact-name">Mirja Kühlewind</span>,
<span class="contact-name">Barry Leiba</span>,
<span class="contact-name">Eric Rescorla</span>,
<span class="contact-name">Adam Roach</span>,
<span class="contact-name">Martin Vigoureux</span>,
and <span class="contact-name">Éric Vyncke</span> 
for their reviews.<a href="#section-appendix.a-1" class="pilcrow">¶</a></p>
</section>
</div>
<div id="authors-addresses">
<section id="section-appendix.b">
      <h2 id="name-authors-addresses">
<a href="#name-authors-addresses" class="section-name selfRef">Authors' Addresses</a>
      </h2>
<address class="vcard">
        <div dir="auto" class="left"><span class="fn nameRole">Yaron Sheffer</span></div>
<div dir="auto" class="left"><span class="org">Intuit</span></div>
<div class="email">
<span>Email:</span>
<a href="mailto:yaronf.ietf@gmail.com" class="email">yaronf.ietf@gmail.com</a>
</div>
</address>
<address class="vcard">
        <div dir="auto" class="left"><span class="fn nameRole">Dick Hardt</span></div>
<div class="email">
<span>Email:</span>
<a href="mailto:dick.hardt@gmail.com" class="email">dick.hardt@gmail.com</a>
</div>
</address>
<address class="vcard">
        <div dir="auto" class="left"><span class="fn nameRole">Michael B. Jones</span></div>
<div dir="auto" class="left"><span class="org">Microsoft</span></div>
<div class="email">
<span>Email:</span>
<a href="mailto:mbj@microsoft.com" class="email">mbj@microsoft.com</a>
</div>
<div class="url">
<span>URI:</span>
<a href="https://self-issued.info/" class="url">https://self-issued.info/</a>
</div>
</address>
</section>
</div>
<script>var toc = document.getElementById("toc");
var tocToggle = toc.querySelector("h2");
var tocNav = toc.querySelector("nav");

// mobile menu toggle
tocToggle.onclick = function(event) {
    if (window.innerWidth < 1024) {
 var tocNavDisplay = tocNav.currentStyle ? tocNav.currentStyle.display : getComputedStyle(tocNav, null).display;
 if (tocNavDisplay == "none") {
     tocNav.style.display = "block";
 } else {
     tocNav.style.display = "none";
 }
    }
}

// toc anchor scroll to anchor
tocNav.addEventListener("click", function (event) {
    event.preventDefault();
    if (event.target.nodeName == 'A') {
 if (window.innerWidth < 1024) {
     tocNav.style.display = "none";
 }
 var href = event.target.getAttribute("href");
 var anchorId = href.substr(1);
 var anchor =  document.getElementById(anchorId);
 anchor.scrollIntoView(true);
 window.history.pushState("","",href);
    }
});

// switch toc mode when window resized
window.onresize = function () {
    if (window.innerWidth < 1024) {
 tocNav.style.display = "none";
    } else {
 tocNav.style.display = "block";
    }
}
</script>
</body>
</html>