docs/1.4/api/authentication/index.html - gerrit/www.eclipse.org/hono - Git at Google

 <!DOCTYPE html>
 <html lang="1.4" class="js csstransforms3d">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="Hugo 0.81.0" />
     <meta name="description" content="A set of micro-services for connecting millions of devices.">
 <meta name="author" content="The Eclipse Hono Project">

     <link rel="apple-touch-icon" sizes="180x180" href="/hono/docs/favicon/apple-touch-icon.png">
 <link rel="icon" type="image/png" sizes="48x48" href="/hono/docs/favicon/favicon-48x48.png">
 <link rel="icon" type="image/png" sizes="32x32" href="/hono/docs/favicon/favicon-32x32.png">
 <link rel="icon" type="image/png" sizes="16x16" href="/hono/docs/favicon/favicon-16x16.png">
 <link rel="manifest" href="/hono/docs/favicon/site.webmanifest">
 <link rel="mask-icon" href="/hono/docs/favicon/safari-pinned-tab.svg" color="#5bbad5">
 <link rel="shortcut icon" href="/hono/docs/favicon/favicon.ico">
 <meta name="msapplication-TileColor" content="#da532c">
 <meta name="msapplication-config" content="/hono/docs/favicon/browserconfig.xml">
 <meta name="theme-color" content="#ffffff">

     <title>Authentication API Specification :: Eclipse Hono&trade; Vers.: 1.4</title>


     <link href="/hono/docs/css/nucleus.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/fontawesome-all.min.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/hybrid.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/featherlight.min.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/perfect-scrollbar.min.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/auto-complete.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/atom-one-dark-reasonable.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/theme.css?1626138726" rel="stylesheet">
     <link href="/hono/docs/css/hugo-theme.css?1626138726" rel="stylesheet">

     <link href="/hono/docs/css/theme-hono.css?1626138726" rel="stylesheet">

     <link href="/hono/docs/css/hono.css?1626138726" rel="stylesheet">

     <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138726"></script>

     <style>
       :root #header + #content > #left > #rlblock_left{
           display:none !important;
       }

         :not(pre) > code + span.copy-to-clipboard {
             display: none;
         }

     </style>

 <link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css">


 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:site" content="@EclipseHono">
 <meta name="twitter:title" content="Authentication API Specification :: Eclipse Hono&amp;trade; Vers.: 1.4">
 <meta name="twitter:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png">
 <meta name="twitter:description" content="A set of micro-services for connecting millions of devices.">


 <meta property="og:title" content="Authentication API Specification :: Eclipse Hono&amp;trade; Vers.: 1.4" />
 <meta property="og:type" content="website" />
 <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.4/api/authentication//" />
 <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" />

   </head>
   <body class="" data-url="/hono/docs/1.4/api/authentication/">
     <nav id="sidebar" class="">


   <div id="header-wrapper">
     <div id="header">
       <a href="https://www.eclipse.org/hono/">
     <img src="/hono/docs/images/HONO-Logo_Bild-Wort_quer-w-310x120px.svg" alt="Hono logo" class="logo-img">
 </a>

     </div>

         <div class="searchbox">
     <label for="search-by"><i class="fas fa-search"></i></label>
     <input data-search-input id="search-by" type="search" placeholder="Search...">
     <span data-search-clear=""><i class="fas fa-times"></i></span>
 </div>

 <script type="text/javascript" src="/hono/docs/js/lunr.min.js?1626138726"></script>
 <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138726"></script>
 <script type="text/javascript">

         var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/1.4";

 </script>
 <script type="text/javascript" src="/hono/docs/js/search.js?1626138726"></script>


   </div>

     <div class="highlightable">
     <ul class="topics">


     <li data-nav-id="/hono/docs/1.4/concepts/" title="Concepts" class="dd-item


         ">
       <a href="/hono/docs/1.4/concepts/">
           <i class="far fa-lightbulb"></i> Concepts

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/concepts/device-identity/" title="Device Identity" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/device-identity/">
         Device Identity

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/tenancy/" title="Multi-Tenancy" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/tenancy/">
         Multi-Tenancy

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/device-provisioning/" title="Device Provisioning" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/device-provisioning/">
         Device Provisioning

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/connecting-devices/" title="Connecting Devices" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/connecting-devices/">
         Connecting Devices

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/device-notifications/" title="Device Notifications" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/device-notifications/">
         Device Notifications

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/command-and-control/" title="Command &amp; Control" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/command-and-control/">
         Command &amp; Control

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/resource-limits/" title="Resource limits" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/resource-limits/">
         Resource limits

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/concepts/connection-events/" title="Connection Events" class="dd-item ">
         <a href="/hono/docs/1.4/concepts/connection-events/">
         Connection Events

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.4/user-guide/" title="User Guide" class="dd-item


         ">
       <a href="/hono/docs/1.4/user-guide/">
           <i class="fas fa-book-reader"></i> User Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/user-guide/mongodb-based-device-registry/" title="MongoDB Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/mongodb-based-device-registry/">
         MongoDB Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/file-based-device-registry/" title="File Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/file-based-device-registry/">
         File Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/http-adapter/">
         HTTP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/mqtt-adapter/">
         MQTT Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/amqp-adapter/">
         AMQP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/coap-adapter/" title="CoAP Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/coap-adapter/">
         CoAP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/kura-adapter/">
         Kura Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/sigfox-adapter/">
         Sigfox Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/user-guide/jmeter_load_tests/" title="Load Tests with JMeter" class="dd-item ">
         <a href="/hono/docs/1.4/user-guide/jmeter_load_tests/">
         Load Tests with JMeter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.4/admin-guide/" title="Admin Guide" class="dd-item


         ">
       <a href="/hono/docs/1.4/admin-guide/">
           <i class="fas fa-sliders-h"></i> Admin Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/admin-guide/common-config/" title="Common Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/common-config/">
         Common Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/auth-server-config/">
         Auth Server Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/mongodb-device-registry-config/" title="MongoDB Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/mongodb-device-registry-config/">
         MongoDB Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/file-based-device-registry-config/" title="File Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/file-based-device-registry-config/">
         File Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/device-connection-config/">
         Device Connection Service Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/http-adapter-config/">
         HTTP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/mqtt-adapter-config/">
         MQTT Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/amqp-adapter-config/">
         AMQP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/coap-adapter-config/" title="CoAP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/coap-adapter-config/">
         CoAP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/kura-adapter-config/">
         Kura Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/hono-client-configuration/">
         Hono Client Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/amqp-network-config/">
         AMQP 1.0 Messaging Network Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/secure_communication/" title="Secure Communication" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/secure_communication/">
         Secure Communication

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/admin-guide/monitoring-tracing-config/" title="Monitoring &amp; Tracing" class="dd-item ">
         <a href="/hono/docs/1.4/admin-guide/monitoring-tracing-config/">
         Monitoring &amp; Tracing

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.4/dev-guide/" title="Developer Guide" class="dd-item


         ">
       <a href="/hono/docs/1.4/dev-guide/">
           <i class="fas fa-tools"></i> Developer Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/dev-guide/building_hono/" title="Building from Source" class="dd-item ">
         <a href="/hono/docs/1.4/dev-guide/building_hono/">
         Building from Source

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/dev-guide/amqp_adapter_client/" title="AMQP Adapter Client for Java" class="dd-item ">
         <a href="/hono/docs/1.4/dev-guide/amqp_adapter_client/">
         AMQP Adapter Client for Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item ">
         <a href="/hono/docs/1.4/dev-guide/java_client_consumer/">
         Consuming Messages from Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item ">
         <a href="/hono/docs/1.4/dev-guide/custom_http_adapter/">
         Implement a Custom Hono HTTP Protocol Adapter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.4/api/" title="API" class="dd-item
         parent


         ">
       <a href="/hono/docs/1.4/api/">
           &nbsp;<i class='fas fa-plug'></i>&nbsp;API

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/api/telemetry/" title="Telemetry API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/telemetry/">
         Telemetry API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/event/" title="Event API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/event/">
         Event API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/command-and-control/" title="Command &amp; Control API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/command-and-control/">
         Command &amp; Control API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/tenant/" title="Tenant API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/tenant/">
         Tenant API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/device-connection/" title="Device Connection API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/device-connection/">
         Device Connection API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/device-registration/" title="Device Registration API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/device-registration/">
         Device Registration API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/credentials/" title="Credentials API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/credentials/">
         Credentials API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/authentication/" title="Authentication API Specification" class="dd-item active">
         <a href="/hono/docs/1.4/api/authentication/">
         Authentication API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/management/" title="Device Registry Management API Specification" class="dd-item ">
         <a href="/hono/docs/1.4/api/management/">
         Device Registry Management API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/api/metrics/" title="Metrics" class="dd-item ">
         <a href="/hono/docs/1.4/api/metrics/">
         Metrics

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.4/deployment/" title="Deployment" class="dd-item


         ">
       <a href="/hono/docs/1.4/deployment/">
           <i class="fas fa-shipping-fast"></i> Deployment

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item ">
         <a href="/hono/docs/1.4/deployment/helm-based-deployment/">
         Helm based Deployment

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/deployment/openshift/" title="OpenShift / OKD" class="dd-item ">
         <a href="/hono/docs/1.4/deployment/openshift/">
         OpenShift / OKD

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item ">
         <a href="/hono/docs/1.4/deployment/create-kubernetes-cluster/">
         Setting up a Kubernetes Cluster

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item ">
         <a href="/hono/docs/1.4/deployment/resource-limitation/">
         Limiting Resource Usage

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.4/architecture/" title="Architecture" class="dd-item


         ">
       <a href="/hono/docs/1.4/architecture/">
           <i class="fas fa-landmark"></i> Architecture

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.4/architecture/component-view/" title="Component View" class="dd-item ">
         <a href="/hono/docs/1.4/architecture/component-view/">
         Component View

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.4/architecture/auth/" title="Authentication/Authorization" class="dd-item ">
         <a href="/hono/docs/1.4/architecture/auth/">
         Authentication/Authorization

         </a>
     </li>


         </ul>

     </li>


     </ul>


       <section id="shortcuts">
         <h3></h3>
         <ul>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/" title="Hono&#39;s Homepage"><i class='fas fa-home'></i> Hono Home</a>
               </li>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/getting-started/" title="Getting started with Eclipse Hono"><i class='fas fa-plane-departure'></i> Getting Started</a>
               </li>

         </ul>
       </section>


     <section id="prefooter">
       <hr/>
       <ul>

         <li>
           <div id="select-box-wrapper">
           <div id="select-box">
           <a class="padding">
             Version:&nbsp;
           <div class="select-style">
             <select id="select-language" onchange="location = this.value;">


                       <option id="stable" value="https://www.eclipse.org/hono/docs/api/authentication/">stable (1.8)</option>


                       <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/api/authentication/">1.8</option>


                       <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/api/authentication/">1.7</option>


                       <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/api/authentication/">1.6</option>


                       <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/api/authentication/">1.5</option>


                       <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/api/authentication/" selected>1.4</option>


                       <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/api/authentication/">1.3</option>


                       <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/api/authentication/">1.2</option>


                       <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/api/authentication/">1.1</option>


                       <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/api/authentication/">1.0</option>


                       <option id="dev" value="https://www.eclipse.org/hono/docs/dev/api/authentication/">dev</option>


         </select>
         <svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
           width="255px" height="255px" viewBox="0 0 255 255" style="enable-background:new 0 0 255 255;" xml:space="preserve">
           <g>
             <g id="arrow-drop-down">
               <polygon points="0,63.75 127.5,191.25 255,63.75 		" />
             </g>
           </g>
         </svg>
         </div>
         </a>
         </div>
         </div>
         </li>


       </ul>
     </section>

     <section id="footer">


 <p>&copy; 2021 <a href="https://www.eclipse.org/hono/">The Eclipse Hono Project</a></p>

 <p>
     Documentation built with
     <a href="https://gohugo.io/" target="_blank">Hugo</a>
     using the
     <a href="https://github.com/matcornic/hugo-theme-learn" target="_blank">Learn</a> theme.
 </p>

 <div class="eclipse-logo">
     <a href="https://www.eclipse.org" target="_blank">
         <img src="https://www.eclipse.org/hono/docs/images/eclipse_foundation_logo.svg"/>
     </a>
 </div>

     </section>
   </div>
 </nav>


         <section id="body">
         <div id="overlay"></div>


     <div class="old-version-hint">
         <p>This page refers to version <em>1.4</em>.
             You might want to use the <a href="https://www.eclipse.org/hono/docs/">current stable</a> version.
         </p>
     </div>


         <div class="padding highlightable">

               <div>
                 <div id="top-bar">


                   <div id="top-github-link">
                     <a class="github-link" title='Edit this page' href="https://github.com/eclipse/hono/edit/master/site/documentation/content/api/authentication/index.md" target="blank">
                       <i class="fas fa-code-branch"></i>
                       <span id="top-github-link-text">Edit this page</span>
                     </a>
                   </div>


                 <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
                     <span id="sidebar-toggle-span">
                         <a href="#" id="sidebar-toggle" data-sidebar-toggle="">
                           <i class="fas fa-bars"></i>
                         </a>
                     </span>

                   <span id="toc-menu"><i class="fas fa-list-alt"></i></span>

                   <span class="links">


             <a href='/hono/docs/1.4/'>Documentation</a> > <a href='/hono/docs/1.4/api/'>API</a> > Authentication API Specification


                   </span>
                 </div>

                     <div class="progress">
     <div class="wrapper">
 <nav id="TableOfContents">
   <ul>
     <li><a href="#get-token">Get Token</a></li>
     <li><a href="#token-format">Token Format</a>
       <ul>
         <li><a href="#resource-authorities">Resource Authorities</a></li>
         <li><a href="#operation-authorities">Operation Authorities</a></li>
       </ul>
     </li>
   </ul>
 </nav>
     </div>
 </div>


               </div>
             </div>

         <div id="head-tags">

         </div>

         <div id="body-inner">

             <h1>

               Authentication API Specification
             </h1>


 <p>The <em>Authentication API</em> is used to retrieve a <em>token</em> asserting a subject&rsquo;s identity and granted authorities. Other service implementations use such a token to make authorization decisions on a client&rsquo;s request to read or write from/to a resource or to invoke a certain operation.</p>
 <p>The Authentication API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to an Authentication service using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.</p>
 <p>Note that a component implementing this API will most likely need to also provide means to add, alter or remove identities and authorities as well. However, Hono itself does not require this kind of functionality, thus this kind of functionality is considered out of scope of this API.</p>
 <p>In a real world environment there will often already be an <em>identity management system</em> in place. In such cases it can make sense to just implement a <em>facade</em> exposing the Authentication API operations and mapping them to the underlying existing system&rsquo;s functionality.</p>
 <h2 id="get-token">Get Token</h2>
 <p>Clients use this operation to</p>
 <ul>
 <li>verify a set of credentials and</li>
 <li>retrieve a token asserting the authenticated subject&rsquo;s identity and granted authorities.</li>
 </ul>
 <p><strong>Message Flow</strong></p>
 <p>The following sequence diagram illustrates the flow of messages involved in a <em>Client</em> retrieving a token.</p>
 <figure>
     <img src="get-token.svg"/> <figcaption>
             <h4>Get Token message flow</h4>
         </figcaption>
 </figure>

 <ol>
 <li>The <em>Client</em> and <em>Authentication</em> service have agreed to use the SASL PLAIN mechanism for authenticating the client. The <em>Client</em> therefore sends the credentials of the identity it wants to retrieve a token for. The <em>Authentication</em> service successfully verifies the credentials and establishes the <em>authorization ID</em>.
 <ol>
 <li>The <em>Authentication</em> service completes the SASL exchange with a successful outcome (SASL OK).</li>
 </ol>
 </li>
 <li>The <em>Client</em> continues by opening an AMQP connection with the <em>Authentication</em> service. The <em>Authentication</em> service creates a token asserting the <em>authorization ID</em> and authorities established during the SASL exchange and associates it with the connection.</li>
 <li>The <em>Client</em> opens a receiving link using source address <code>cbs</code>.
 <ol>
 <li>The <em>Authentication</em> service opens the link and</li>
 <li>sends the token associated with the connection to the <em>Client</em>.</li>
 </ol>
 </li>
 <li>The <em>Client</em> closes the connection.</li>
 </ol>
 <p><strong>Token Message Format</strong></p>
 <p>On successful establishment of the receiving link with the client as described above, the server sends a message to the client containing a token asserting the identity and authorities of the client that has been authenticated as part of establishing the underlying AMQP connection.</p>
 <p>The following table provides an overview of the properties of the message sent to the client.</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">Type</th>
 <th style="text-align:left">Value</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>type</em></td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left"><code>amqp:jwt</code></td>
 </tr>
 </tbody>
 </table>
 <p>The message&rsquo;s body consists of a single AMQP 1.0 <em>AmqpValue</em> section which contains the UTF-8 representation of a JSON Web Token as defined in <a href="#token-format">Token Format</a>.</p>
 <h2 id="token-format">Token Format</h2>
 <p>The token returned by the <em>get Token</em> operation is a cryptographically signed JSON Web Token as defined by <a href="https://tools.ietf.org/html/rfc7519">RFC 7519</a>.</p>
 <p>The token contains the following mandatory <em>claims</em>:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:left">Type</th>
 <th style="text-align:left">Value</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>sub</em></td>
 <td style="text-align:left"><a href="https://tools.ietf.org/html/rfc7519#section-4.1.2">RFC 7519, Section 4.1.2</a></td>
 <td style="text-align:left">The <em>authorization ID</em> of the authenticated client. This represents the asserted identity.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>exp</em></td>
 <td style="text-align:left"><a href="https://tools.ietf.org/html/rfc7519#section-4.1.4">RFC 7519, Section 4.1.4</a></td>
 <td style="text-align:left">The point in time after which the claims contained in this token must be considered no longer valid. Clients MUST NOT use any information from a token that has expired.</td>
 </tr>
 </tbody>
 </table>
 <p>The subject&rsquo;s authorities on resources and operations are represented by additional JWT <em>claims</em> with a name identifying the resource or operation and a value containing the activities the subject is allowed to perform. The following activities are supported:</p>
 <ul>
 <li>READ - The client is allowed to establish a receiving link using the resource&rsquo;s node address as the link&rsquo;s <em>source address</em>.</li>
 <li>WRITE - The client is allowed to establish a sending link using the resource&rsquo;s node address as the link&rsquo;s <em>target address</em>.</li>
 <li>EXECUTE - The client is allowed to <em>invoke</em> an operation on an endpoint, i.e. send a message over a link with a <em>subject</em> representing the operation name and the link&rsquo;s target address representing the API endpoint&rsquo;s node address.</li>
 </ul>
 <p>The allowed activities are encoded in a claim&rsquo;s value by means of simply concatenating the activities' initial characters (<code>R</code>, <code>W</code>, <code>E</code>).</p>
 <p>The token may contain any number of additional claims which may be ignored by clients that do not understand their meaning.</p>
 <h3 id="resource-authorities">Resource Authorities</h3>
 <p>A client&rsquo;s authority on a resource is represented by a JWT <em>claim</em> with a name containing the resource node address prefixed with <code>r:</code> and a value containing the activities the client is allowed to perform on the resource. The node address MAY contain one or more wildcard (<code>*</code>) characters to represent <em>any</em> string.</p>
 <p><strong>Example:</strong></p>
 <p>Assuming a client which is allowed to</p>
 <ul>
 <li>send and consume events for tenant <code>my-tenant</code> and</li>
 <li>consume telemetry data for all tenants</li>
 </ul>
 <p>the corresponding claims (in the token&rsquo;s JSON representation) would look like this:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
   <span style="color:#960050;background-color:#1e0010">...</span>
   <span style="color:#f92672">&#34;r:event/my-tenant&#34;</span>: <span style="color:#e6db74">&#34;RW&#34;</span>,
   <span style="color:#f92672">&#34;r:telemetry/*&#34;</span>: <span style="color:#e6db74">&#34;R&#34;</span>,
   <span style="color:#960050;background-color:#1e0010">...</span>
 }
 </code></pre></div><h3 id="operation-authorities">Operation Authorities</h3>
 <p>A client&rsquo;s authority to invoke an endpoint&rsquo;s operation(s) is represented by a JWT <em>claim</em> with a name containing the endpoint&rsquo;s node address and operation identifier prefixed with <code>o:</code> and a value of <code>E</code> (for <code>EXECUTE</code>). The endpoint node address MAY contain one or more wildcard (<code>*</code>) characters to represent <em>any</em> string. The operation identifier is the <em>subject</em> value defined by the corresponding API for the operation. The operation identifier MAY be set to <code>*</code> to represent <em>any</em> operation of the endpoint.</p>
 <p><strong>Example:</strong></p>
 <p>Assuming a client which is allowed to</p>
 <ul>
 <li>invoke the Device Registration API&rsquo;s <em>assert Registration</em> operation for any tenant and</li>
 <li>invoke all methods of the Credentials API for tenant <code>my-tenant</code></li>
 </ul>
 <p>the corresponding claims (in the token&rsquo;s JSON representation) would look like this:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
   <span style="color:#960050;background-color:#1e0010">...</span>
   <span style="color:#f92672">&#34;o:registration/*:assert&#34;</span>: <span style="color:#e6db74">&#34;E&#34;</span>,
   <span style="color:#f92672">&#34;o:credentials/my-tenant:*&#34;</span>: <span style="color:#e6db74">&#34;E&#34;</span>,
   <span style="color:#960050;background-color:#1e0010">...</span>
 }
 </code></pre></div>

 <footer class="footline">

 </footer>


         </div>


       </div>

     <div id="navigation">


     </div>

     </section>

     <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
       <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
     </div>
     <script src="/hono/docs/js/clipboard.min.js?1626138727"></script>
     <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138727"></script>
     <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138727"></script>
     <script src="/hono/docs/js/jquery.sticky.js?1626138727"></script>
     <script src="/hono/docs/js/featherlight.min.js?1626138727"></script>
     <script src="/hono/docs/js/highlight.pack.js?1626138727"></script>
     <script>hljs.initHighlightingOnLoad();</script>
     <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138727"></script>
     <script src="/hono/docs/js/learn.js?1626138727"></script>
     <script src="/hono/docs/js/hugo-learn.js?1626138727"></script>

     <link href="/hono/docs/mermaid/mermaid.css?1626138727" rel="stylesheet" />
     <script src="/hono/docs/mermaid/mermaid.js?1626138727"></script>
     <script>
         mermaid.initialize({ startOnLoad: true });
     </script>


 <script>
     (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
             new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
         j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
         'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
     })(window,document,'script','dataLayer','GTM-5WLCZXC');
 </script>


 <script src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>

   </body>
 </html>