documentation/security/security.html - gerrit/www.eclipse.org/hawkbit - Git at Google

 <!DOCTYPE html>
 <html>
   <!--Head section for CSS/Javascript  -->

 <head>
   <meta charset="utf-8">
   <meta content='width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no' name='viewport'>
   <meta name="description" content="IoT Software Update">
   <meta name="author" content="">
   <!--base to have relative path for offline navigation -->


   <title>Eclipse hawkBit - IoT Software Update</title>

   <!--Stylesheets-->
   <!-- Bootstrap 3.3.1 -->
   <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/css/bootstrap.min.css" rel="stylesheet" type="text/css" />
   <!-- Font Awesome Icons -->
   <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.2.0/css/font-awesome.css" rel="stylesheet" type="text/css" />
   <link rel="stylesheet" href="../../css/prettyPhoto.css" type="text/css" media="screen" title="prettyPhoto main stylesheet" charset="utf-8" />
   <!-- Custom CSS -->
   <link href="../../css/hawkbit.css" rel="stylesheet">

   <!--Javascript-->
   <!-- JQuery 2.1.1-->
   <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
   <!-- Bootstrap 3.3.1 JS -->
   <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/js/bootstrap.min.js" type="text/javascript"></script>
   <script src="../../js/jquery.prettyPhoto.js" type="text/javascript" charset="utf-8"></script>
   <script type="text/javascript" charset="utf-8">
                $(document).ready(function(){
                  $("a[rel^='prettyPhoto']").prettyPhoto();
                });
              </script>
 </head>

   <body>
     <!--Header section Site navigation -->

 <!--base to have relative path for offline navigation -->


 <!-- Navigation -->
 <nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
 		<div class="container">
 				<div class="navbar-header">
 						<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar-collapse">
 								<span class="sr-only">Toggle navigation</span>
 								<span class="icon-bar"></span>
 								<span class="icon-bar"></span>
 								<span class="icon-bar"></span>
 						</button>
 						<a class="navbar-brand" href="../../index.html">Eclipse hawkBit™</a>
 				</div>
 				<div class="collapse navbar-collapse wow fadeIn" id="navbar-collapse" data-wow-delay="0.2s">
 						<ul class="nav navbar-nav pull-right">

 								<li >

 										<a href="../../news/index.html">News</a>


 								</li>

 								<li >

 										<a href="../../documentation/overview/introduction.html">Documentation</a>


 								</li>

 						</ul>
 				</div>
 				<!-- /.navbar-collapse -->
 		</div>
 		<style>#forkongithub a{background:#8d0c0c;color:#fff;text-decoration:none;font-family:Arial, Helvetica, sans-serif;text-align:center;font-weight:bold;padding:5px 40px;font-size:12px;line-height:3rem;position:relative;transition:0.5s;}#forkongithub a:hover{background:#c11;color:#fff;}#forkongithub a::before,#forkongithub a::after{content:"";width:100%;display:block;position:absolute;top:1px;left:0;height:1px;background:#fff;}#forkongithub a::after{bottom:1px;top:auto;}@media screen and (min-width:800px){#forkongithub{position:fixed;display:block;top:0;right:0;width:50px;overflow:visible;height:200px;z-index:9999;}#forkongithub a{width:260px;position:absolute;top:40px;right:-60px;transform:rotate(45deg);-webkit-transform:rotate(45deg);-ms-transform:rotate(45deg);-moz-transform:rotate(45deg);-o-transform:rotate(45deg);}}</style><span id="forkongithub"><a href="https://github.com/eclipse/hawkbit">Fork me on GitHub</a></span>
 		<!-- /.container -->
 </nav>

     <div id="header_wrapper" class="container">
       <div class="nav-bar col-md-3">
         <nav class="navmenu navmenu-default"  role="navigation">
           <ul class="nav navmenu-nav">
             <!--base to have relative path for offline navigation -->


     <li>
       Introduction
       <ul class="nav navmenu-nav">
         <!-- 2nd level -->
         <!--base to have relative path for offline navigation -->


     <li  >

         <a href="../../documentation/overview/introduction.html">Overview</a>


     </li>


     <li  >

         <a href="../../documentation/overview/features.html">Features</a>


     </li>


     <li  >

         <a href="../../documentation/overview/getting-started.html">Getting Started</a>


     </li>


       </ul>
     </li>


     <li>
       Concepts
       <ul class="nav navmenu-nav">
         <!-- 2nd level -->
         <!--base to have relative path for offline navigation -->


     <li  >

         <a href="../../documentation/architecture/architecture.html">Architecture</a>


     </li>


     <li  >

         <a href="../../documentation/architecture/datamodel.html">Data model</a>


     </li>


     <li  >

         <a href="../../documentation/architecture/targetstate.html">Target States</a>


     </li>


       </ul>
     </li>


     <li>
       Interfaces
       <ul class="nav navmenu-nav">
         <!-- 2nd level -->
         <!--base to have relative path for offline navigation -->


     <li  >

         <a href="../../documentation/interfaces/interfaces.html">Overview</a>


     </li>


     <li  >

         <a href="../../documentation/interfaces/management-ui.html">Management UI</a>


     </li>


     <li  >

         <a href="../../documentation/interfaces/management-api.html">Management API</a>


     </li>


     <li  >

         <a href="../../documentation/interfaces/ddi-api.html">DDI API</a>


     </li>


     <li  >

         <a href="../../documentation/interfaces/dmf-api.html">DMF API</a>


     </li>


       </ul>
     </li>


     <li>
       Security
       <ul class="nav navmenu-nav">
         <!-- 2nd level -->
         <!--base to have relative path for offline navigation -->


     <li  >

         <a href="../../documentation/security/security.html">Overview</a>


     </li>


       </ul>
     </li>


     <li>
       Guides
       <ul class="nav navmenu-nav">
         <!-- 2nd level -->
         <!--base to have relative path for offline navigation -->


     <li  >

         <a href="../../documentation/guide/runhawkbit.html">Build and Run hawkBit</a>


     </li>


     <li  >

         <a href="../../documentation/guide/clustering.html">Clustering</a>


     </li>


     <li  >

         <a href="../../documentation/guide/customtheme.html">Theme Customization</a>


     </li>


     <li  >

         <a href="../../documentation/guide/feignclient.html">Create Feign Client</a>


     </li>


       </ul>
     </li>


           </ul>
       </nav>
     </div>


     <div id="page" class="col-md-9">
     	<div class="inner">
         <div id="maincontainer">
           <section id="top" class="documentation-section">
             <div class="row">
 					     <div class="span8 offset3">
                  <!--base to have relative path for offline navigation -->

 <h1 id="security">Security</h1>

 <h2 id="authentication">Authentication</h2>
 <p>A <em>hawkBit</em> update server can be accessed in four different ways:
 - <em>Direct Device Integration (DDI) API</em> by <strong>targets</strong>.
 - <em>Management API</em> by 3rd party <strong>applications</strong>.
 - <em>Device Management Federation (DMF) API</em> by 3rd party <strong>applications</strong> through AMQP.
 - <em>Management UI</em> by <strong>users</strong>.</p>

 <h3 id="ddi-api-authentication-modes">DDI API Authentication Modes</h3>

 <h4 id="security-token">Security Token</h4>

 <p><em>hawkBit</em> supports multiple ways to authenticate a target against the server. The different authentication modes can be individual enabled and disabled within <em>hawkBit</em>. Both on system level (with Spring Boot properties) as per individual tenant.</p>

 <h5 id="target-security-token-authentication">Target Security Token Authentication</h5>
 <p>There is a 32 alphanumeric character security-token for each created target within IoT <em>hawkBit</em>. This token can be used to authenticate the target at <em>hawkBit</em> through the HTTP-Authorization header with the custom scheme <em>TargetToken</em>.</p>

 <pre><code>GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
 Host: your.hawkBit.server
 Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY
 </code></pre>

 <p>The target security token is provided in <a href="https://github.com/eclipse/hawkbit/wiki/Device-Management-Federation-API">DMF API</a> as part of the update message in order to allow DMF clients to leverage the feature or can it be manually retrieved per target by <a href="https://github.com/eclipse/hawkbit/wiki/Management-API">Management API</a> or in the <a href="https://github.com/eclipse/hawkbit/wiki/Management-UI">Management UI</a> in the target details.</p>

 <p>Note: needs to be enabled in your <em>hawkBit</em> installation <strong>and</strong> in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java">DdiSecurityProperties</a> for system wide enablement.</p>

 <p>The additional activation for the individual tenant:</p>

 <p><img src="../images/security/targetToken.png" alt="Enable Target Token" width="800px" /></p>

 <h5 id="gateway-security-token-authentication">Gateway Security Token Authentication</h5>
 <p>Often the targets are connected through a gateway which manages the targets directly and as a result are indirectly connected to the <em>hawkBit</em> update server.</p>

 <p>To authenticate this gateway and allow it to manage all target instances under its tenant there is a <em>GatewayToken</em> to authenticate this gateway through the HTTP-Authorization header with a custom scheme <em>GatewayToken</em>. This is of course also handy during development or for testing purposes. However, we generally recommend to use this token with care as it allows to act <em>in the name of</em> any device.</p>

 <pre><code>GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
 Host: your.hawkBit.server
 Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW
 </code></pre>

 <p>Note: needs to be enabled in your <em>hawkBit</em> installation <strong>and</strong> in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java">DdiSecurityProperties</a> for system wide enablement.</p>

 <p>The additional activation for the individual tenant:</p>

 <p><img src="../images/security/gatewayToken.png" alt="Enable Gateway Token" width="800px" /></p>

 <h5 id="anonymous-access">Anonymous access</h5>
 <p>Here we offer general anonymous access for all targets (see <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java">DdiSecurityProperties</a>) which we consider not really sufficient for a production system but it might come in handy to get a project started in the beginning.</p>

 <p>However, anonymous download on the other side might be interesting even in production for scenarios where the artifact itself is already encrypted.</p>

 <p>The activation for the individual tenant:</p>

 <p><img src="../images/security/anonymousDownload.png" alt="Enable Anonymous Download" width="800px" /></p>

 <h3 id="dmf-api">DMF API</h3>
 <p>Authentication is provided by <em>RabbitMQ</em> <a href="https://www.rabbitmq.com/access-control.html">vhost and user credentials</a> that is used for the integration.</p>

 <h3 id="management-api">Management API</h3>
 <ul>
   <li>Basic Auth</li>
 </ul>

 <h3 id="management-ui">Management UI</h3>
 <ul>
   <li>Login Dialog</li>
 </ul>

 <h2 id="authorization">Authorization</h2>
 <p>Authorization is handled separately for <em>Direct Device Integration (DDI) API</em> and <em>Device Management Federation (DMF) API</em> (where successful authentication includes full authorization) and <em>Management API</em> and <em>UI</em> which is based on Spring security <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/im/authentication/SpPermission.java">authorities</a>.</p>

 <p>However, keep in mind that <em>hawkBit</em> does not offer an off the shelf authentication provider to leverage these permissions and the underlying multi user/tenant capabilities of <em>hawkBit</em>. Check out <a href="http://projects.spring.io/spring-security/">Spring security documentation</a> for further information. In <em>hawkBit</em> <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-autoconfigure/src/main/java/org/eclipse/hawkbit/autoconfigure/security/SecurityAutoConfiguration.java">SecurityAutoConfiguration</a> is a good starting point for integration.</p>

 <p>The default implementation is single user/tenant with basic auth and the logged in user is provided with all permissions.</p>

 <h3 id="ddi-api">DDI API</h3>
 <p>An authenticated target is permitted to:
 - retrieve commands from the server
 - provide feedback to the the server
 - download artifacts that are assigned to it</p>

 <p>A target might be permitted to download artifacts without authentication (if enabled, see above). Only the download can be permitted to disable the authentication. This can be used in scenarios where the artifacts itself are e.g. signed and secured.  </p>

 <h3 id="management-api-and-ui">Management API and UI</h3>
 <p>#### Delivered Permissions
 - READ<em>/UPDATE</em>/CREATE_/DELETE_TARGETS for:
   - Target entities including metadata (that includes also the installed and assigned distribution sets)
   - Target tags
   - Target actions
   - Target registration rules
   - Bulk operations
   - Target filters</p>

 <ul>
   <li>READ<em>/UPDATE</em>/CREATE_/DELETE_REPOSITORY for:
     <ul>
       <li>Distribution sets</li>
       <li>Software Modules</li>
       <li>Artifacts</li>
       <li>DS tags</li>
     </ul>
   </li>
   <li>READ_TARGET_SECURITY_TOKEN
     <ul>
       <li>Permission to read the target security token. The security token is security concerned and should be protected.</li>
     </ul>
   </li>
   <li>DOWNLOAD_REPOSITORY_ARTIFACT
     <ul>
       <li>Permission to download artifacts of an software module (Note: READ_REPOSITORY allows only to read the metadata).</li>
     </ul>
   </li>
   <li>TENANT_CONFIGURATION
     <ul>
       <li>Permission to administrate the tenant settings.</li>
     </ul>
   </li>
   <li>ROLLOUT_MANAGEMENT
     <ul>
       <li>Permission to provision targets through rollouts.</li>
     </ul>
   </li>
 </ul>

 <h4 id="permission-matrix-for-example-uses-cases-that-need-more-than-one-permission">Permission Matrix for example uses cases that need more than one permission</h4>

 <table>
   <thead>
     <tr>
       <th>Use Case</th>
       <th>Needed permissions</th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <td>Search <em>targets</em> by installed or assigned <em>distribution set</em></td>
       <td>READ_TARGET, READ_REPOSITORY</td>
     </tr>
     <tr>
       <td>Assign <em>DS</em> to a <em>target</em></td>
       <td>READ_REPOSITORY, UPDATE_TARGET</td>
     </tr>
     <tr>
       <td>Assign DS to target through a <em>Rollout</em>, i.e. <em>Rollout</em> creation and start</td>
       <td>READ_REPOSITORY, UPDATE_TARGET, ROLLOUT_MANAGEMENT</td>
     </tr>
     <tr>
       <td>Read <em>Rollout</em> status including its <em>deployment groups</em></td>
       <td>ROLLOUT_MANAGEMENT</td>
     </tr>
     <tr>
       <td>Checks <em>targets</em> inside <em>Rollout deployment group</em></td>
       <td>READ_TARGET, ROLLOUT_MANAGEMENT</td>
     </tr>
   </tbody>
 </table>

 <h3 id="device-management-federation-api">Device Management Federation API</h3>
 <p>The provided <em>RabbitMQ</em> <a href="https://www.rabbitmq.com/access-control.html">vhost and user</a> should be provided with the necessary permissions to send messages to <em>hawkBit</em> through the exchange and receive messages from it through the specified queue.</p>

                 </div>
              </div>
           </section>
         </div>
       </div>
     </div>
   </div>
     <!-- Footer -->
 <footer>
    <div class="container">
    <div class="row">
          <div class="col-md-4">
            <h3 class="footer-links-header">Quick Links</h3>
            <ul class="footer-links clearfix">
              <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
              <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
              <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
              <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
            </ul>
            <ul class="footer-links clearfix">
              <li><a href="http://www.eclipse.org">Eclipse Home</a></li>
              <li><a href="http://marketplace.eclipse.org/">Market Place</a></li>
              <li><a href="http://live.eclipse.org/">Eclipse Live</a></li>
              <li><a href="http://www.planeteclipse.org/">Eclipse Planet</a></li>
            </ul>
            </div>
          <div class="col-md-2">

    </div>
 </footer>

 <!--/.Footer-->

   </body>

 </html>
	<!DOCTYPE html>
	<html>
	<!--Head section for CSS/Javascript -->

	<head>
	<meta charset="utf-8">
	<meta content='width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no' name='viewport'>
	<meta name="description" content="IoT Software Update">
	<meta name="author" content="">
	<!--base to have relative path for offline navigation -->






	<title>Eclipse hawkBit - IoT Software Update</title>

	<!--Stylesheets-->
	<!-- Bootstrap 3.3.1 -->
	<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/css/bootstrap.min.css" rel="stylesheet" type="text/css" />
	<!-- Font Awesome Icons -->
	<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.2.0/css/font-awesome.css" rel="stylesheet" type="text/css" />
	<link rel="stylesheet" href="../../css/prettyPhoto.css" type="text/css" media="screen" title="prettyPhoto main stylesheet" charset="utf-8" />
	<!-- Custom CSS -->
	<link href="../../css/hawkbit.css" rel="stylesheet">

	<!--Javascript-->
	<!-- JQuery 2.1.1-->
	<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
	<!-- Bootstrap 3.3.1 JS -->
	<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/js/bootstrap.min.js" type="text/javascript"></script>
	<script src="../../js/jquery.prettyPhoto.js" type="text/javascript" charset="utf-8"></script>
	<script type="text/javascript" charset="utf-8">
	$(document).ready(function(){
	$("a[rel^='prettyPhoto']").prettyPhoto();
	});
	</script>
	</head>

	<body>
	<!--Header section Site navigation -->

	<!--base to have relative path for offline navigation -->






	<!-- Navigation -->
	<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar-collapse">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="navbar-brand" href="../../index.html">Eclipse hawkBit™</a>
	</div>
	<div class="collapse navbar-collapse wow fadeIn" id="navbar-collapse" data-wow-delay="0.2s">
	<ul class="nav navbar-nav pull-right">

	<li >

	<a href="../../news/index.html">News</a>


	</li>

	<li >

	<a href="../../documentation/overview/introduction.html">Documentation</a>


	</li>

	</ul>
	</div>
	<!-- /.navbar-collapse -->
	</div>
	<style>#forkongithub a{background:#8d0c0c;color:#fff;text-decoration:none;font-family:Arial, Helvetica, sans-serif;text-align:center;font-weight:bold;padding:5px 40px;font-size:12px;line-height:3rem;position:relative;transition:0.5s;}#forkongithub a:hover{background:#c11;color:#fff;}#forkongithub a::before,#forkongithub a::after{content:"";width:100%;display:block;position:absolute;top:1px;left:0;height:1px;background:#fff;}#forkongithub a::after{bottom:1px;top:auto;}@media screen and (min-width:800px){#forkongithub{position:fixed;display:block;top:0;right:0;width:50px;overflow:visible;height:200px;z-index:9999;}#forkongithub a{width:260px;position:absolute;top:40px;right:-60px;transform:rotate(45deg);-webkit-transform:rotate(45deg);-ms-transform:rotate(45deg);-moz-transform:rotate(45deg);-o-transform:rotate(45deg);}}</style><span id="forkongithub"><a href="https://github.com/eclipse/hawkbit">Fork me on GitHub</a></span>
	<!-- /.container -->
	</nav>

	<div id="header_wrapper" class="container">
	<div class="nav-bar col-md-3">
	<nav class="navmenu navmenu-default" role="navigation">
	<ul class="nav navmenu-nav">
	<!--base to have relative path for offline navigation -->








	<li>
	Introduction
	<ul class="nav navmenu-nav">
	<!-- 2nd level -->
	<!--base to have relative path for offline navigation -->








	<li >

	<a href="../../documentation/overview/introduction.html">Overview</a>


	</li>



	<li >

	<a href="../../documentation/overview/features.html">Features</a>


	</li>



	<li >

	<a href="../../documentation/overview/getting-started.html">Getting Started</a>


	</li>



	</ul>
	</li>



	<li>
	Concepts
	<ul class="nav navmenu-nav">
	<!-- 2nd level -->
	<!--base to have relative path for offline navigation -->








	<li >

	<a href="../../documentation/architecture/architecture.html">Architecture</a>


	</li>



	<li >

	<a href="../../documentation/architecture/datamodel.html">Data model</a>


	</li>



	<li >

	<a href="../../documentation/architecture/targetstate.html">Target States</a>


	</li>



	</ul>
	</li>



	<li>
	Interfaces
	<ul class="nav navmenu-nav">
	<!-- 2nd level -->
	<!--base to have relative path for offline navigation -->








	<li >

	<a href="../../documentation/interfaces/interfaces.html">Overview</a>


	</li>



	<li >

	<a href="../../documentation/interfaces/management-ui.html">Management UI</a>


	</li>



	<li >

	<a href="../../documentation/interfaces/management-api.html">Management API</a>


	</li>



	<li >

	<a href="../../documentation/interfaces/ddi-api.html">DDI API</a>


	</li>



	<li >

	<a href="../../documentation/interfaces/dmf-api.html">DMF API</a>


	</li>



	</ul>
	</li>



	<li>
	Security
	<ul class="nav navmenu-nav">
	<!-- 2nd level -->
	<!--base to have relative path for offline navigation -->








	<li >

	<a href="../../documentation/security/security.html">Overview</a>


	</li>



	</ul>
	</li>



	<li>
	Guides
	<ul class="nav navmenu-nav">
	<!-- 2nd level -->
	<!--base to have relative path for offline navigation -->








	<li >

	<a href="../../documentation/guide/runhawkbit.html">Build and Run hawkBit</a>


	</li>



	<li >

	<a href="../../documentation/guide/clustering.html">Clustering</a>


	</li>



	<li >

	<a href="../../documentation/guide/customtheme.html">Theme Customization</a>


	</li>



	<li >

	<a href="../../documentation/guide/feignclient.html">Create Feign Client</a>


	</li>



	</ul>
	</li>



	</ul>
	</nav>
	</div>


	<div id="page" class="col-md-9">
	<div class="inner">
	<div id="maincontainer">
	<section id="top" class="documentation-section">
	<div class="row">
	<div class="span8 offset3">
	<!--base to have relative path for offline navigation -->

	<h1 id="security">Security</h1>

	<h2 id="authentication">Authentication</h2>
	<p>A <em>hawkBit</em> update server can be accessed in four different ways:
	- <em>Direct Device Integration (DDI) API</em> by <strong>targets</strong>.
	- <em>Management API</em> by 3rd party <strong>applications</strong>.
	- <em>Device Management Federation (DMF) API</em> by 3rd party <strong>applications</strong> through AMQP.
	- <em>Management UI</em> by <strong>users</strong>.</p>

	<h3 id="ddi-api-authentication-modes">DDI API Authentication Modes</h3>

	<h4 id="security-token">Security Token</h4>

	<p><em>hawkBit</em> supports multiple ways to authenticate a target against the server. The different authentication modes can be individual enabled and disabled within <em>hawkBit</em>. Both on system level (with Spring Boot properties) as per individual tenant.</p>

	<h5 id="target-security-token-authentication">Target Security Token Authentication</h5>
	<p>There is a 32 alphanumeric character security-token for each created target within IoT <em>hawkBit</em>. This token can be used to authenticate the target at <em>hawkBit</em> through the HTTP-Authorization header with the custom scheme <em>TargetToken</em>.</p>

	<pre><code>GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
	Host: your.hawkBit.server
	Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY
	</code></pre>

	<p>The target security token is provided in <a href="https://github.com/eclipse/hawkbit/wiki/Device-Management-Federation-API">DMF API</a> as part of the update message in order to allow DMF clients to leverage the feature or can it be manually retrieved per target by <a href="https://github.com/eclipse/hawkbit/wiki/Management-API">Management API</a> or in the <a href="https://github.com/eclipse/hawkbit/wiki/Management-UI">Management UI</a> in the target details.</p>

	<p>Note: needs to be enabled in your <em>hawkBit</em> installation <strong>and</strong> in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java">DdiSecurityProperties</a> for system wide enablement.</p>

	<p>The additional activation for the individual tenant:</p>

	<p><img src="../images/security/targetToken.png" alt="Enable Target Token" width="800px" /></p>

	<h5 id="gateway-security-token-authentication">Gateway Security Token Authentication</h5>
	<p>Often the targets are connected through a gateway which manages the targets directly and as a result are indirectly connected to the <em>hawkBit</em> update server.</p>

	<p>To authenticate this gateway and allow it to manage all target instances under its tenant there is a <em>GatewayToken</em> to authenticate this gateway through the HTTP-Authorization header with a custom scheme <em>GatewayToken</em>. This is of course also handy during development or for testing purposes. However, we generally recommend to use this token with care as it allows to act <em>in the name of</em> any device.</p>

	<pre><code>GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
	Host: your.hawkBit.server
	Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW
	</code></pre>

	<p>Note: needs to be enabled in your <em>hawkBit</em> installation <strong>and</strong> in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java">DdiSecurityProperties</a> for system wide enablement.</p>

	<p>The additional activation for the individual tenant:</p>

	<p><img src="../images/security/gatewayToken.png" alt="Enable Gateway Token" width="800px" /></p>

	<h5 id="anonymous-access">Anonymous access</h5>
	<p>Here we offer general anonymous access for all targets (see <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java">DdiSecurityProperties</a>) which we consider not really sufficient for a production system but it might come in handy to get a project started in the beginning.</p>

	<p>However, anonymous download on the other side might be interesting even in production for scenarios where the artifact itself is already encrypted.</p>

	<p>The activation for the individual tenant:</p>

	<p><img src="../images/security/anonymousDownload.png" alt="Enable Anonymous Download" width="800px" /></p>

	<h3 id="dmf-api">DMF API</h3>
	<p>Authentication is provided by <em>RabbitMQ</em> <a href="https://www.rabbitmq.com/access-control.html">vhost and user credentials</a> that is used for the integration.</p>

	<h3 id="management-api">Management API</h3>
	<ul>
	<li>Basic Auth</li>
	</ul>

	<h3 id="management-ui">Management UI</h3>
	<ul>
	<li>Login Dialog</li>
	</ul>

	<h2 id="authorization">Authorization</h2>
	<p>Authorization is handled separately for <em>Direct Device Integration (DDI) API</em> and <em>Device Management Federation (DMF) API</em> (where successful authentication includes full authorization) and <em>Management API</em> and <em>UI</em> which is based on Spring security <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/im/authentication/SpPermission.java">authorities</a>.</p>

	<p>However, keep in mind that <em>hawkBit</em> does not offer an off the shelf authentication provider to leverage these permissions and the underlying multi user/tenant capabilities of <em>hawkBit</em>. Check out <a href="http://projects.spring.io/spring-security/">Spring security documentation</a> for further information. In <em>hawkBit</em> <a href="https://github.com/eclipse/hawkbit/blob/master/hawkbit-autoconfigure/src/main/java/org/eclipse/hawkbit/autoconfigure/security/SecurityAutoConfiguration.java">SecurityAutoConfiguration</a> is a good starting point for integration.</p>

	<p>The default implementation is single user/tenant with basic auth and the logged in user is provided with all permissions.</p>

	<h3 id="ddi-api">DDI API</h3>
	<p>An authenticated target is permitted to:
	- retrieve commands from the server
	- provide feedback to the the server
	- download artifacts that are assigned to it</p>

	<p>A target might be permitted to download artifacts without authentication (if enabled, see above). Only the download can be permitted to disable the authentication. This can be used in scenarios where the artifacts itself are e.g. signed and secured. </p>

	<h3 id="management-api-and-ui">Management API and UI</h3>
	<p>#### Delivered Permissions
	- READ<em>/UPDATE</em>/CREATE_/DELETE_TARGETS for:
	- Target entities including metadata (that includes also the installed and assigned distribution sets)
	- Target tags
	- Target actions
	- Target registration rules
	- Bulk operations
	- Target filters</p>

	<ul>
	<li>READ<em>/UPDATE</em>/CREATE_/DELETE_REPOSITORY for:
	<ul>
	<li>Distribution sets</li>
	<li>Software Modules</li>
	<li>Artifacts</li>
	<li>DS tags</li>
	</ul>
	</li>
	<li>READ_TARGET_SECURITY_TOKEN
	<ul>
	<li>Permission to read the target security token. The security token is security concerned and should be protected.</li>
	</ul>
	</li>
	<li>DOWNLOAD_REPOSITORY_ARTIFACT
	<ul>
	<li>Permission to download artifacts of an software module (Note: READ_REPOSITORY allows only to read the metadata).</li>
	</ul>
	</li>
	<li>TENANT_CONFIGURATION
	<ul>
	<li>Permission to administrate the tenant settings.</li>
	</ul>
	</li>
	<li>ROLLOUT_MANAGEMENT
	<ul>
	<li>Permission to provision targets through rollouts.</li>
	</ul>
	</li>
	</ul>

	<h4 id="permission-matrix-for-example-uses-cases-that-need-more-than-one-permission">Permission Matrix for example uses cases that need more than one permission</h4>

	<table>
	<thead>
	<tr>
	<th>Use Case</th>
	<th>Needed permissions</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td>Search <em>targets</em> by installed or assigned <em>distribution set</em></td>
	<td>READ_TARGET, READ_REPOSITORY</td>
	</tr>
	<tr>
	<td>Assign <em>DS</em> to a <em>target</em></td>
	<td>READ_REPOSITORY, UPDATE_TARGET</td>
	</tr>
	<tr>
	<td>Assign DS to target through a <em>Rollout</em>, i.e. <em>Rollout</em> creation and start</td>
	<td>READ_REPOSITORY, UPDATE_TARGET, ROLLOUT_MANAGEMENT</td>
	</tr>
	<tr>
	<td>Read <em>Rollout</em> status including its <em>deployment groups</em></td>
	<td>ROLLOUT_MANAGEMENT</td>
	</tr>
	<tr>
	<td>Checks <em>targets</em> inside <em>Rollout deployment group</em></td>
	<td>READ_TARGET, ROLLOUT_MANAGEMENT</td>
	</tr>
	</tbody>
	</table>

	<h3 id="device-management-federation-api">Device Management Federation API</h3>
	<p>The provided <em>RabbitMQ</em> <a href="https://www.rabbitmq.com/access-control.html">vhost and user</a> should be provided with the necessary permissions to send messages to <em>hawkBit</em> through the exchange and receive messages from it through the specified queue.</p>

	</div>
	</div>
	</section>
	</div>
	</div>
	</div>
	</div>
	<!-- Footer -->
	<footer>
	<div class="container">
	<div class="row">
	<div class="col-md-4">
	<h3 class="footer-links-header">Quick Links</h3>
	<ul class="footer-links clearfix">
	<li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
	<li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
	<li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
	<li><a href="http://www.eclipse.org/legal/">Legal</a></li>
	</ul>
	<ul class="footer-links clearfix">
	<li><a href="http://www.eclipse.org">Eclipse Home</a></li>
	<li><a href="http://marketplace.eclipse.org/">Market Place</a></li>
	<li><a href="http://live.eclipse.org/">Eclipse Live</a></li>
	<li><a href="http://www.planeteclipse.org/">Eclipse Planet</a></li>
	</ul>
	</div>
	<div class="col-md-2">

	</div>
	</footer>

	<!--/.Footer-->

	</body>

	</html>