blob: 174f861386e5ae3fd1ab6ca4377b24d44b8dd57d [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="model, authentication, authorization, auth, policies, policy">
<title> Policy • Eclipse Ditto • a digital twin framework</title>
<link rel="stylesheet" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/modern-business.css">
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/boxshadowproperties.css">
<link rel="stylesheet" href="css/theme-ditto.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Organization",
"url": "https://eclipse.org/ditto/",
"logo": "https://eclipse.org/ditto/images/ditto.svg"
}
</script>
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="images/favicon-96x96.png" sizes="96x96">
<link rel="alternate" type="application/rss+xml" title="Eclipse Ditto Blog" href="https://www.eclipse.org/ditto/feed.xml">
<!-- Eclipse Foundation cookie consent: -->
<link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
<script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>
<script>
$(document).ready(function() {
$("#tg-sb-link").click(function() {
$("#tg-sb-sidebar").toggle();
$("#tg-sb-content").toggleClass('col-md-9');
$("#tg-sb-content").toggleClass('col-md-12');
$("#tg-sb-icon").toggleClass('fa-toggle-on');
$("#tg-sb-icon").toggleClass('fa-toggle-off');
});
});
</script>
</head>
<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>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container topnavlinks">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<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-ditto-home" href="index.html">&nbsp;<img src="images/ditto_allwhite_symbolonly.svg" class="ditto-navbar-symbol" alt="Home"> <img src="images/ditto_allwhite_textonly.svg" class="ditto-navbar-symbol-text" alt="Ditto"></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<!-- toggle sidebar button -->
<!--<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>-->
<!-- entries without drop-downs appear here -->
<li><a href="blog.html">Blog</a></li>
<li><a href="intro-overview.html">Documentation</a></li>
<li><a href="http-api-doc.html">HTTP API</a></li>
<li><a href="https://ditto.eclipse.org" target="_blank">Sandbox</a></li>
<li><a href="https://github.com/eclipse/ditto" target="_blank">GitHub</a></li>
<li><a href="https://github.com/eclipse/ditto-examples" target="_blank">GitHub examples</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Links<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://projects.eclipse.org/projects/iot.ditto" target="_blank">Eclipse Ditto Project</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/364/" target="_blank">Forum</a></li>
<li><a href="https://ci.eclipse.org/ditto/" target="_blank">Jenkins</a></li>
<li><a href="https://dev.eclipse.org/mhonarc/lists/ditto-dev/" target="_blank">Mailing list archives</a></li>
<li><a href="https://gitter.im/eclipse/ditto" target="_blank">Gitter.im chat</a></li>
</ul>
</li>
<!--comment out this block if you want to hide search-->
<li>
<!--start search-->
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="//cdnjs.cloudflare.com/ajax/libs/simple-jekyll-search/0.0.9/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'search.json',
searchResultTemplate: '<li><a href="{url}" title="Policy">{title}</a></li>',
noResultsText: 'No results found.',
limit: 10,
fuzzy: true,
})
</script>
<!--end search-->
</li>
</ul>
</div>
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<div class="container">
<div id="main">
<!-- Content Row -->
<div class="row">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle">
<label for="docVersion">Eclipse Ditto version:</label>
<div class="select-wrapper">
<select id="docVersion" name="docVersion">
<option value="">development</option>
<option value="1.0">1.0</option>
<option value="1.1">1.1</option>
<option value="1.2">1.2</option>
<option value="1.3">1.3</option>
<option value="1.4">1.4</option>
</select>
</div>
<div id="dev-warning">
<div markdown="span" class="alert alert-warning" role="alert" style="font-size:0.6em"><i class="fa fa-warning"></i> <b>Important:</b> This documentation reflects the latest 'development'. You might want to choose a released version.</div>
</div>
</li>
<li class="subfolders">
<a href="#"><span></span>Introduction</a>
<ul>
<li><a href="intro-overview.html">Overview</a></li>
<li><a href="intro-digitaltwins.html">Digital twins</a></li>
<li><a href="intro-hello-world.html">Hello world</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Release Notes</a>
<ul>
<li><a href="release_notes_110.html">1.1.0</a></li>
<li><a href="release_notes_100.html">1.0.0</a></li>
<li><a href="release_notes_090.html">0.9.0</a></li>
<li><a href="release_notes_080.html">0.8.0</a></li>
<li class="subfolders">
<a href="#"><span></span>Milestone releases</a>
<ul>
<li><a href="release_notes_100-M2.html">1.0.0-M2</a></li>
<li><a href="release_notes_100-M1a.html">1.0.0-M1a</a></li>
<li><a href="release_notes_090-M2.html">0.9.0-M2</a></li>
<li><a href="release_notes_090-M1.html">0.9.0-M1</a></li>
<li><a href="release_notes_080-M3.html">0.8.0-M3</a></li>
<li><a href="release_notes_080-M2.html">0.8.0-M2</a></li>
<li><a href="release_notes_080-M1.html">0.8.0-M1</a></li>
<li><a href="release_notes_030-M2.html">0.3.0-M2</a></li>
<li><a href="release_notes_030-M1.html">0.3.0-M1</a></li>
<li><a href="release_notes_020-M1.html">0.2.0-M1</a></li>
<li><a href="release_notes_010-M3.html">0.1.0-M3</a></li>
<li><a href="release_notes_010-M1.html">0.1.0-M1</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Installation</a>
<ul>
<li><a href="installation-building.html">Building Ditto</a></li>
<li><a href="installation-running.html">Running Ditto</a></li>
<li><a href="installation-operating.html">Operating Ditto</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Basic concepts</a>
<ul>
<li><a href="basic-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Model entities</a>
<ul>
<li><a href="basic-thing.html">Thing</a></li>
<li><a href="basic-acl.html">Access Control List (ACL)</a></li>
<li><a href="basic-feature.html">Feature</a></li>
<li class="active"><a href="basic-policy.html">Policy</a></li>
<li><a href="basic-namespaces-and-names.html">Namespaces and Names</a></li>
</ul>
</li>
<li><a href="basic-auth.html">Authentication and Authorization</a></li>
<li><a href="basic-messages.html">Messages</a></li>
<li><a href="basic-signals.html">Signals</a></li>
<li class="subfolders">
<a href="#"><span></span>Signal types</a>
<ul>
<li><a href="basic-signals-command.html">Command</a></li>
<li><a href="basic-signals-commandresponse.html">Command response</a></li>
<li><a href="basic-signals-errorresponse.html">Error response</a></li>
<li><a href="basic-signals-event.html">Event</a></li>
</ul>
</li>
<li><a href="basic-apis.html">APIs</a></li>
<li><a href="basic-connections.html">Connections</a></li>
<li><a href="basic-placeholders.html">Placeholders</a></li>
<li><a href="basic-changenotifications.html">Change notifications</a></li>
<li><a href="basic-rql.html">RQL expressions</a></li>
<li><a href="basic-enrichment.html">Signal enrichment</a></li>
<li><a href="basic-search.html">Search</a></li>
<li><a href="basic-acknowledgements.html">Acknowledgements</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Architecture</a>
<ul>
<li><a href="architecture-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Services</a>
<ul>
<li><a href="architecture-services-policies.html">Policies</a></li>
<li><a href="architecture-services-things.html">Things</a></li>
<li><a href="architecture-services-things-search.html">Things-Search</a></li>
<li><a href="architecture-services-connectivity.html">Connectivity</a></li>
<li><a href="architecture-services-concierge.html">Concierge</a></li>
<li><a href="architecture-services-gateway.html">Gateway</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>HTTP API</a>
<ul>
<li><a href="httpapi-overview.html">Overview</a></li>
<li><a href="httpapi-concepts.html">Concepts</a></li>
<li><a href="httpapi-search.html">Search</a></li>
<li><a href="httpapi-messages.html">Messages</a></li>
<li><a href="httpapi-protocol-bindings-websocket.html">WebSocket protocol binding</a></li>
<li><a href="httpapi-sse.html">Server sent events</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Connectivity API</a>
<ul>
<li><a href="connectivity-overview.html">Overview</a></li>
<li><a href="connectivity-manage-connections.html">Manage connections</a></li>
<li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x protocol binding</a></li>
<li><a href="connectivity-mapping.html">Payload mapping</a></li>
<li><a href="connectivity-header-mapping.html">Header mapping</a></li>
<li><a href="connectivity-tls-certificates.html">TLS certificates</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Client SDK</a>
<ul>
<li><a href="client-sdk-overview.html">Overview</a></li>
<li><a href="client-sdk-java.html">Java</a></li>
<li><a href="client-sdk-javascript.html">JavaScript</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Ditto Protocol</a>
<ul>
<li><a href="protocol-overview.html">Overview</a></li>
<li><a href="protocol-twinlive.html">Twin/live channel</a></li>
<li><a href="protocol-specification.html">Specification</a></li>
<li><a href="protocol-specification-topic.html">Protocol topic</a></li>
<li><a href="protocol-specification-things.html">Things group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-things-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-things-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-things-delete.html">Delete</a></li>
<li><a href="protocol-specification-acks.html">Acknowledgements</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ search/messages</a>
<ul>
<li><a href="protocol-specification-things-search.html">Search</a></li>
<li><a href="protocol-specification-things-messages.html">Messages</a></li>
</ul>
</li>
<li><a href="protocol-specification-policies.html">Policies group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-policies-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-policies-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-policies-delete.html">Delete</a></li>
</ul>
</li>
<li><a href="protocol-bindings.html">Bindings</a></li>
<li><a href="protocol-examples.html">Examples</a></li>
<li class="subfolders">
<a href="#"><span></span>→ Things examples</a>
<ul>
<li><a href="protocol-examples-creatething.html">Create a Thing</a></li>
<li><a href="protocol-examples-deletething.html">Delete a Thing</a></li>
<li><a href="protocol-examples-modifything.html">Modify a Thing</a></li>
<li><a href="protocol-examples-retrievething.html">Retrieve a Thing</a></li>
<li><a href="protocol-examples-retrievethings.html">Retrieve multiple Things</a></li>
<li><a href="protocol-examples-modifypolicyid.html">Modify the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-createattributes.html">Create Attributes</a></li>
<li><a href="protocol-examples-deleteattributes.html">Delete Attributes</a></li>
<li><a href="protocol-examples-modifyattributes.html">Modify Attributes</a></li>
<li><a href="protocol-examples-retrieveattributes.html">Retrieve Attributes</a></li>
<li><a href="protocol-examples-createattribute.html">Create a single Attribute</a></li>
<li><a href="protocol-examples-deleteattribute.html">Delete a single Attribute</a></li>
<li><a href="protocol-examples-modifyattribute.html">Modify a single Attribute</a></li>
<li><a href="protocol-examples-retrieveattribute.html">Retrieve a single Attribute</a></li>
<li><a href="protocol-examples-createthingdefinition.html">Create a Definition</a></li>
<li><a href="protocol-examples-deletethingdefinition.html">Delete a Definition</a></li>
<li><a href="protocol-examples-modifythingdefinition.html">Modify a Definition</a></li>
<li><a href="protocol-examples-retrievethingdefinition.html">Retrieve a Definition</a></li>
<li><a href="protocol-examples-createfeatures.html">Create Features</a></li>
<li><a href="protocol-examples-deletefeatures.html">Delete Features</a></li>
<li><a href="protocol-examples-modifyfeatures.html">Modify Features</a></li>
<li><a href="protocol-examples-retrievefeatures.html">Retrieve Features</a></li>
<li><a href="protocol-examples-createfeature.html">Create a single Feature</a></li>
<li><a href="protocol-examples-deletefeature.html">Delete a single Feature</a></li>
<li><a href="protocol-examples-modifyfeature.html">Modify a single Feature</a></li>
<li><a href="protocol-examples-retrievefeature.html">Retrieve a single Feature</a></li>
<li><a href="protocol-examples-createdefinition.html">Create Feature Definition</a></li>
<li><a href="protocol-examples-deletedefinition.html">Delete Feature Definition</a></li>
<li><a href="protocol-examples-modifydefinition.html">Modify Feature Definition</a></li>
<li><a href="protocol-examples-retrievedefinition.html">Retrieve Feature Definition</a></li>
<li><a href="protocol-examples-createproperties.html">Create Feature Properties</a></li>
<li><a href="protocol-examples-deleteproperties.html">Delete Feature Properties</a></li>
<li><a href="protocol-examples-modifyproperties.html">Modify Feature Properties</a></li>
<li><a href="protocol-examples-retrieveproperties.html">Retrieve Feature Properties</a></li>
<li><a href="protocol-examples-createproperty.html">Create a single Property</a></li>
<li><a href="protocol-examples-deleteproperty.html">Delete a single Property</a></li>
<li><a href="protocol-examples-modifyproperty.html">Modify a single Property</a></li>
<li><a href="protocol-examples-retrieveproperty.html">Retrieve a single Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Policies examples</a>
<ul>
<li><a href="protocol-examples-policies-createpolicy.html">Create a Policy</a></li>
<li><a href="protocol-examples-policies-deletepolicy.html">Delete a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicy.html">Modify a Policy</a></li>
<li><a href="protocol-examples-policies-retrievepolicy.html">Retrieve a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicyentries.html">Modify entries</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentries.html">Retrieve entries</a></li>
<li><a href="protocol-examples-policies-createpolicyentry.html">Create a single entry</a></li>
<li><a href="protocol-examples-policies-deletepolicyentry.html">Delete a single entry</a></li>
<li><a href="protocol-examples-policies-modifypolicyentry.html">Modify a single entry</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentry.html">Retrieve a single entry</a></li>
<li><a href="protocol-examples-policies-modifysubjects.html">Modify subjects</a></li>
<li><a href="protocol-examples-policies-retrievesubjects.html">Retrieve subjects</a></li>
<li><a href="protocol-examples-policies-createsubject.html">Create a single subject</a></li>
<li><a href="protocol-examples-policies-deletesubject.html">Delete a single subject</a></li>
<li><a href="protocol-examples-policies-modifysubject.html">Modify a single subject</a></li>
<li><a href="protocol-examples-policies-retrievesubject.html">Retrieve a single subject</a></li>
<li><a href="protocol-examples-policies-modifyresources.html">Modify resources</a></li>
<li><a href="protocol-examples-policies-retrieveresources.html">Retrieve resources</a></li>
<li><a href="protocol-examples-policies-createresource.html">Create a single resource</a></li>
<li><a href="protocol-examples-policies-deleteresource.html">Delete a single resource</a></li>
<li><a href="protocol-examples-policies-modifyresource.html">Modify a single resource</a></li>
<li><a href="protocol-examples-policies-retrieveresource.html">Retrieve a single resource</a></li>
<li><a href="protocol-examples-policies-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li><a href="protocol-examples-search.html">→ Search examples</a></li>
</ul>
</li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="presentations.html">Presentations</a></li>
<li><a href="glossary.html">Glossary</a></li>
<li><a href="feedback.html">Feedback</a></li>
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
</ul>
<!-- this highlights the active parent class in the sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");
</script>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<div class="post-header">
<h1 class="post-title-main">Policy</h1>
</div>
<div class="post-content">
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
// Handler for .ready() called.
$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });
/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
var target = $(this.getAttribute('href'))
, scroll_target = target.offset().top
$(window).scrollTop(scroll_target - 10);
return false
})
});
</script>
<div id="toc"></div>
<p>A Policy enables developers to configure fine-grained access control for Things and other entities in an easy way.</p>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> The policy concept is only supported for Ditto <strong>HTTP API version 2</strong>. <br />
Find the HTTP API reference at <a href="http-api-doc.html?urls.primaryName=api2#/Policies">Policies resources</a>.</div>
<h2 id="authorization-concept">Authorization concept</h2>
<p>A specific policy provides someone (called subject), permission to read and/or write a given resource.</p>
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> The write permission at the policy root resource (i.e. <code class="highlighter-rouge">policy:/</code>) allows to manage the
policy itself.<br />Find an <a href="basic-policy.html#example">example</a> at the end of the page.</div>
<p>Please note, that in most cases it makes sense to grant read permission in addition to a write permission, because
<em>write does not imply read.</em></p>
<h2 id="who-can-be-addressed">Who can be addressed?</h2>
<p>A Subject ID must conform to one of the following rules:</p>
<ul>
<li>The ID of a User defined in the nginx reverse proxy prefixed with <code class="highlighter-rouge">nginx</code>.</li>
<li>Different JWT providers with their JWT “iss” fields - the currently supported are listed in the table below.</li>
<li>OpenID Connect compliant providers - supported providers are listed at <a href="https://openid.net/developers/certified/">OpenID Connect - Certified OpenID Provider Servers and Services</a> The <code class="highlighter-rouge">sub</code> claim and configured provider name are used in the form <code class="highlighter-rouge">&lt;provider&gt;:&lt;sub-claim&gt;</code>.</li>
</ul>
<table>
<thead>
<tr>
<th>Prefix</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>google</td>
<td>jwt</td>
<td>A <a href="#" data-toggle="tooltip" data-original-title="JSON Web Token (JWT)">JWT</a> issued by Google</td>
</tr>
</tbody>
</table>
<h2 id="which-resources-can-be-controlled">Which Resources can be controlled?</h2>
<p>A Policy can contain access control definitions for several resources:</p>
<ul>
<li><strong>Policy:</strong> Someone who was granted write permission at the policy root resource (i.e. <code class="highlighter-rouge">policy:/</code>) is allowed to
manage the policy itself.</li>
<li><strong>Thing:</strong> The resource can be defined as fine-grained as necessary for the respective use case: e.g. <code class="highlighter-rouge">thing:/</code> as
top-level resource or on sub-resources such as <code class="highlighter-rouge">thing:/features</code>.
At runtime, the permissions are propagated down to all Thing sub-entities.
<ul>
<li>In case you grant read permission on top-level and revoke it at a sub-entity, the subject can read the upper
part only.</li>
<li>In case you omit a subject at top-level but grant permission at a sub-entity, the subject can access the lower
part only (and the Thing ID).</li>
</ul>
</li>
</ul>
<h2 id="policy">Policy</h2>
<p>The Policy resource (addressable as <code class="highlighter-rouge">policy:/</code>) defines the access control for the Policy itself.</p>
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> Please make sure to define at least one user (for which you have the credentials) with
top-level <em>read</em> and <em>write</em> permissions on the Policy, otherwise you won’t be able to access/change it.</div>
<table>
<thead>
<tr>
<th>Resource</th>
<th>Addressed data, description</th>
</tr>
</thead>
<tbody>
<tr>
<td>policy:/</td>
<td>The Policy itself (top-level)<br />Applies to the Policy and all of its sub-resources.</td>
</tr>
<tr>
<td>policy:/policyId</td>
<td>The Policy’s ID.<br />However, such a reference is <em>not recommended</em> because write is not supported anyway, and read on the ID only, does not provide any benefit.</td>
</tr>
<tr>
<td>policy:/entries</td>
<td>Applies to all entries of the Policy.</td>
</tr>
<tr>
<td>policy:/entries/X</td>
<td>Applies to all subjects and resources of the specific entry X.</td>
</tr>
<tr>
<td>policy:/entries/X/subjects</td>
<td>Applies to all subjects of the specific entry X.</td>
</tr>
<tr>
<td>policy:/entries/X/subjects/Y</td>
<td>Applies to subject Y of the specific entry X.</td>
</tr>
<tr>
<td>policy:/entries/X/resources</td>
<td>Applies to all resources of the specific entry X.</td>
</tr>
<tr>
<td>policy:/entries/X/resources/Y</td>
<td>Applies to resource Y of the specific entry X.</td>
</tr>
</tbody>
</table>
<p>The <a href="basic-policy.html#example">Things example at the end of the page</a> also defines access control on the policy
resource.</p>
<h2 id="thing">Thing</h2>
<p>The Thing resource (addressable as <code class="highlighter-rouge">thing:/</code>) defines the access control for Things.</p>
<p>The access control definitions defined in a Policy’s Thing resource will be applied to all Things referencing this
Policy.</p>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> In case you want to re-use a policy for various things, please make sure to name the
Policy ID differently than the Thing ID.</div>
<table>
<thead>
<tr>
<th>Resource</th>
<th>Addressed data, description</th>
</tr>
</thead>
<tbody>
<tr>
<td>thing:/</td>
<td>The Thing itself (top-level).<br />Applies to the Thing and all of its sub-resources.</td>
</tr>
<tr>
<td>thing:/thingId</td>
<td>The Thing’s ID.<br />Not recommended, because write is not supported anyway and read on the ID only does not provide any benefit.</td>
</tr>
<tr>
<td>thing:/policyId</td>
<td>Applies to the Policy ID of the Thing, which implicitly defines its access control.<br /><em>Please double-check write permissions on this resource.</em></td>
</tr>
<tr>
<td>thing:/attributes</td>
<td>Applies to all attributes of the Thing.</td>
</tr>
<tr>
<td>thing:/attributes/X</td>
<td>Applies to the specific attribute X and its sub-paths.<br />X may be a nested path such as tire/pressure.</td>
</tr>
</tbody>
</table>
<p>Find a <a href="basic-policy.html#example">Things example at the end of the page.</a></p>
<h2 id="feature">Feature</h2>
<table>
<thead>
<tr>
<th>Resource</th>
<th>Addressed data, description</th>
</tr>
</thead>
<tbody>
<tr>
<td>thing:/features</td>
<td>Applies to all Features of the Thing.</td>
</tr>
<tr>
<td>thing:/features/X</td>
<td>Applies to the Feature with ID X and all its sub-paths.</td>
</tr>
<tr>
<td>thing:/features/X/properties</td>
<td>Applies to all properties of the Feature X.</td>
</tr>
<tr>
<td>thing:/features/X/properties/Y</td>
<td>Applies to the property with path Y (and its sub-paths) of the Feature with ID X. <br />Y may be a nested path such as tire/pressure.</td>
</tr>
</tbody>
</table>
<p>Find a <a href="basic-policy.html#example">Things example at the end of the page.</a></p>
<h2 id="message">Message</h2>
<p>The Message resource (addressable as <code class="highlighter-rouge">message:/</code>) defines the access control for Messages.</p>
<p>The access control definitions defined in a Policy’s Message resource will be applied to all Messages sent to or from Things referencing this Policy.</p>
<ul>
<li>For sending messages to a Thing or its Features write permission is required</li>
<li>For receiving messages from a Thing or its Features read permission is required.</li>
</ul>
<p>Such permissions can be defined at resources of different granularity.</p>
<table>
<thead>
<tr>
<th>Resource</th>
<th>Addressed data, description</th>
</tr>
</thead>
<tbody>
<tr>
<td>message:/</td>
<td>All messages (top-level) <br />Applies to all messages sent to or from Things referencing this Policy and all messages sent to or from features of these Things.</td>
</tr>
<tr>
<td>message:/inbox</td>
<td>Applies to all messages sent to a specific Thing (or multiple things referencing this Policy)</td>
</tr>
<tr>
<td>message:/inbox/messages/X</td>
<td>Applies to all messages on message-subject X, sent to the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/outbox</td>
<td>Applies to all messages sent from the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/outbox/messages/X</td>
<td>Applies to all messages on message-subject X, sent from the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/features</td>
<td>Messages for all Features <br />Applies to all messages sent to or from all Features of Things referencing this Policy</td>
</tr>
<tr>
<td>message:/features/Y</td>
<td>Applies to all messages sent to or from Feature Y of the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/features/Y/inbox</td>
<td>Applies to all messages sent to Feature Y of the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/features/Y/inbox/messages/X</td>
<td>Applies to all messages on message-subject X sent to Feature Y of the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/features/Y/outbox</td>
<td>Applies to all messages sent from Feature Y of the Things referencing this Policy</td>
</tr>
<tr>
<td>message:/features/Y/outbox/messages/X</td>
<td>Applies to all messages on message-subject X sent from Feature Y of the Things referencing this Policy</td>
</tr>
</tbody>
</table>
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> The resources <code class="highlighter-rouge">message:/inbox</code> and <code class="highlighter-rouge">message:/outbox</code> do not address feature-related messages.
For providing access to feature-related messages, you have to either grant top-level permission (<code class="highlighter-rouge">message:/</code>) or grant permission to the resource <code class="highlighter-rouge">message:/features</code> (or the required sub-resources).</div>
<p>The <a href="basic-policy.html#example">Things example at the end of the page</a> also defines access control on messages.</p>
<h2 id="grant-and-revoke-some-permission">Grant and Revoke some Permission</h2>
<table>
<thead>
<tr>
<th>Change</th>
<th>Permission</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>grant</td>
<td>READ</td>
<td>All subjects named in the section are granted read permission on the resources specified in the path, and all subsequent paths, except they are revoked at a subsequent policy label.</td>
</tr>
<tr>
<td>grant</td>
<td>WRITE</td>
<td>All subjects named in the section are granted write permission on the resources specified in the path, and all subsequent paths, except they are revoked at a subsequent policy label.</td>
</tr>
<tr>
<td>revoke</td>
<td>READ</td>
<td>All subjects named in the section are prohibited to read on the resources specified in the path, and all subsequent paths, except they are granted again such permission at a subsequent policy label.</td>
</tr>
<tr>
<td>revoke</td>
<td>WRITE</td>
<td>All subjects named in the section are prohibited to write on the resources specified in the path, and all subsequent paths, except they are granted again such permission at a subsequent policy label.</td>
</tr>
</tbody>
</table>
<h2 id="tools-for-editing-a-policy">Tools for editing a Policy</h2>
<p>The Policy can be edited with a text editor of your choice.
Just make sure it is in valid JSON representation, and that at least one valid subject is granted write permission at
the root resources.</p>
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> The easiest way to create a Policy is to copy the model schema provided at the
<a href="http-api-doc.html?urls.primaryName=api2">interactive HTTP API documentation</a> and adapt it to your needs.</div>
<p>In case of fine-grained access on Things, keep an eye on your actual Thing structure to make sure that all paths will be
granted or revoked the permissions your use case is supposed to support.</p>
<h2 id="example">Example</h2>
<p>Given you need to support the following scenario:</p>
<ul>
<li>Owner: The Thing <em>my.namespace:thing-0123</em> is owned by a user. Thus, she needs full access and admin rights for the
complete Thing.
In our example her ID is <em>ditto</em></li>
<li>Observer of changes at featureX and featureY:
<ul>
<li>Another application needs to be informed on each change at those features.
In our example its ID is <em>observer-client</em>.</li>
<li>There is a group of users who are allowed to read both features.
In our example the group ID is <em>some-users</em>.</li>
</ul>
</li>
<li>Privacy: The value of the “city” property at “featureY” is confidential and needs to be “hidden” from the group of
users.</li>
</ul>
<figure><img class="docimage" src="images/pages/basic/policy-example.png" alt="Policy Example" /><figcaption>Example Thing with link to a Policy ID</figcaption></figure>
<p>Your Policy then might look like the following:</p>
<figure><img class="docimage" src="images/pages/basic/policy-example-2.png" alt="Policy Example 2" /><figcaption>Example Policy</figcaption></figure>
<p>The correct Policy JSON object notation would be as shown in the following code block.</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"policyId"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my.namespace:policy-a"</span><span class="p">,</span><span class="w">
</span><span class="s2">"entries"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"owner"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"subjects"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"nginx:ditto"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"nginx basic auth user"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"resources"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"thing:/"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"grant"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"READ"</span><span class="p">,</span><span class="w"> </span><span class="s2">"WRITE"</span><span class="p">],</span><span class="w">
</span><span class="s2">"revoke"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"policy:/"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"grant"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"READ"</span><span class="p">,</span><span class="w"> </span><span class="s2">"WRITE"</span><span class="p">],</span><span class="w">
</span><span class="s2">"revoke"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"message:/"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"grant"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"READ"</span><span class="p">,</span><span class="w"> </span><span class="s2">"WRITE"</span><span class="p">],</span><span class="w">
</span><span class="s2">"revoke"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"observer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"subjects"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"nginx:observer-client"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"technical client"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"nginx:some-users"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a group of users"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"resources"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"thing:/features/featureX"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"grant"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"READ"</span><span class="p">],</span><span class="w">
</span><span class="s2">"revoke"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"thing:/features/featureY"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"grant"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"READ"</span><span class="p">],</span><span class="w">
</span><span class="s2">"revoke"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"private"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"subjects"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"nginx:some-users"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a group of users"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"resources"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"thing:/features/featureX/properties/location/city"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"grant"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span><span class="w">
</span><span class="s2">"revoke"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"READ"</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>The Policy can be found:</p>
<ul>
<li>Via GET request at <code class="highlighter-rouge">/api/2/policies/&lt;policyId&gt;</code>, and</li>
<li>Via GET request at <code class="highlighter-rouge">/api/2/things/{thingId}/policyId</code></li>
<li>At any Thing itself in its JSON representation.
It is however not included by default, but can be retrieved by specifying the <code class="highlighter-rouge">/api/2/things/&lt;thingId&gt;?fields=_policy</code> query parameter.</li>
</ul>
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> As soon as a sophisticated policy is described, you will only need to add a further <strong>subject</strong> entry to have for example a new group of users equally empowered as the initial one.</div>
<div class="tags">
<b>Tags: </b>
<a href="tag_model.html" class="btn btn-default navbar-btn cursorNorm" role="button">model</a>
</div>
</div>
<hr class="shaded"/>
<footer>
<div class="row">
<div class="col-lg-12 footer">
<div class="logo">
<a href="https://eclipse.org"><img src="images/eclipse_foundation_logo.svg" alt="Eclipse logo"/></a>
</div>
<p class="notice">
&copy;2020 Eclipse Ditto.
Site last generated: Dec 9, 2020 <br />
</p>
<div class="quickLinks">
<a href="https://www.eclipse.org/legal/privacy.php" target="_blank">
&gt; Privacy Policy
</a>
<a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank">
&gt; Terms of Use
</a>
<a href="https://www.eclipse.org/legal/copyright.php" target="_blank">
&gt; Copyright Agent
</a>
<a href="https://www.eclipse.org/legal" target="_blank">
&gt; Legal
</a>
<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">
&gt; License
</a>
<a href="https://eclipse.org/security" target="_blank">
&gt; Report a Vulnerability
</a>
</div>
</div>
</div>
</footer>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- /#main -->
</div>
</body>
</html>