| <!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"> <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="Eclipse 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="sandbox.html">Sandbox</a></li> |
| |
| |
| |
| |
| <li><a href="https://github.com/eclipse/ditto" target="_blank"> |
| <img src="images/GitHub-Mark-Light-32px.png" alt="Sources at GitHub"> |
| </a></li> |
| |
| |
| |
| |
| |
| <li><a href="https://github.com/eclipse/ditto-clients" target="_blank"> |
| <img src="images/GitHub-Mark-Light-32px.png" alt="SDK sources at GitHub">SDKs |
| </a></li> |
| |
| |
| |
| |
| |
| <li><a href="https://github.com/eclipse/ditto-examples" target="_blank"> |
| <img src="images/GitHub-Mark-Light-32px.png" alt="Example sources at 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="2.0">2.0</option> |
| |
| <option value="1.5">1.5</option> |
| |
| <option value="1.4">1.4</option> |
| |
| <option value="1.3">1.3</option> |
| |
| <option value="1.2">1.2</option> |
| |
| <option value="1.1">1.1</option> |
| |
| <option value="1.0">1.0</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_201.html">2.0.1</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_200.html">2.0.0</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_151.html">1.5.1</a></li> |
| |
| |
| |
| |
| |
| |
| <li><a href="release_notes_150.html">1.5.0</a></li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Archive</a> |
| <ul> |
| |
| |
| |
| <li><a href="release_notes_140.html">1.4.0</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_130.html">1.3.0</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_121.html">1.2.1</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_120.html">1.2.0</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_115.html">1.1.5</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_113.html">1.1.3</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_112.html">1.1.2</a></li> |
| |
| |
| |
| |
| |
| <li><a href="release_notes_111.html">1.1.1</a></li> |
| |
| |
| |
| |
| |
| <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><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-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> |
| |
| |
| |
| |
| |
| <li><a href="basic-metadata.html">Thing Metadata</a></li> |
| |
| |
| |
| |
| |
| <li><a href="basic-errors.html">Errors</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> |
| |
| |
| |
| |
| |
| <li><a href="basic-signals-announcement.html">Announcement</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 / QoS</a></li> |
| |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>Advanced concepts</a> |
| <ul> |
| |
| |
| |
| <li><a href="advanced-data-by-pass.html">Data By-Pass</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-protocol-bindings-cloudevents.html">Cloud Events HTTP 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> |
| |
| |
| |
| |
| |
| |
| <li><a href="connectivity-ssh-tunneling.html">SSH tunneling</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-errors.html">Errors</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-merge.html">Merge</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> |
| |
| |
| |
| |
| |
| <li><a href="protocol-specification-policies-announcement.html">Announcement</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-createdesiredproperties.html">Create desired Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletedesiredproperties.html">Delete desired Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifydesiredproperties.html">Modify desired Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievedesiredproperties.html">Retrieve desired Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-createdesiredproperty.html">Create a single desired Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-deletedesiredproperty.html">Delete a single desired Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-modifydesiredproperty.html">Modify a single desired Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-retrievedesiredproperty.html">Retrieve a single desired Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-errorresponses.html">Error responses</a></li> |
| |
| |
| |
| </ul> |
| </li> |
| |
| |
| |
| <li class="subfolders"> |
| <a href="#"><span></span>→ Things merge examples</a> |
| <ul> |
| |
| |
| |
| <li><a href="protocol-examples-mergething.html">Merge a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergepolicyid.html">Merge the Policy ID of a Thing</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergeattributes.html">Merge Attributes</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergeattribute.html">Merge a single Attribute</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergethingdefinition.html">Merge a Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergefeatures.html">Merge Features</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergefeature.html">Merge a single Feature</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergefeaturedefinition.html">Merge Feature Definition</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergeproperties.html">Merge Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergeproperty.html">Merge a single Property</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergedesiredproperties.html">Merge desired Feature Properties</a></li> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-mergedesiredproperty.html">Merge a single desired 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> |
| |
| |
| |
| |
| |
| <li><a href="protocol-examples-policies-announcement-subjectDeletion.html">Announcement for subject deletion</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 easily.</p> |
| |
| <div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> 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> 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="#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 write permission, because |
| <em>write does not imply read.</em></p> |
| |
| <h2 id="model-specification">Model specification</h2> |
| |
| <script src="docson/widget.js" data-schema="../jsonschema/policy.json"></script> |
| |
| <h2 id="subjects">Subjects</h2> |
| |
| <p>Subjects in a policy define <strong>who</strong> gets permissions granted/revoked on the <a href="#which-resources-can-be-controlled">resources</a> |
| of a policy entry.<br /> |
| Each subject ID contains a prefix defining the subject “issuer” (so which party issued the authentication) and an actual |
| subject, separated with a colon:</p> |
| <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code><subject-issuer>:<subject> |
| </code></pre></div></div> |
| |
| <p>The subject can be one of the following ones:</p> |
| <ul> |
| <li><code class="highlighter-rouge">nginx:<nginx-username></code> - when using nginx as |
| <a href="installation-operating.html#pre-authentication">pre-authentication provider</a> - by default enabled in the Ditto |
| installation’s nginx</li> |
| <li><code class="highlighter-rouge"><other-pre-auth-provider>:<username></code> - when using another custom provider as |
| <a href="installation-operating.html#pre-authentication">pre-authentication provider</a> which sets the |
| <code class="highlighter-rouge">x-ditto-pre-authenticated</code> HTTP header</li> |
| <li> |
| <p><code class="highlighter-rouge">google:<google-user-id></code> - in general different |
| <a href="#" data-toggle="tooltip" data-original-title="JSON Web Token (JWT)">JWT</a> - the currently supported |
| are listed in the table:</p> |
| |
| <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> |
| </li> |
| <li><code class="highlighter-rouge"><custom-openid-connect-provider>:<jwt-sub-claim></code> - |
| custom 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> - |
| <a href="installation-operating.html#openid-connect">can be configured</a> in Ditto defining the prefix in Ditto’s config file.<br /> |
| The <code class="highlighter-rouge">sub</code> claim from the JWT and the configured provider name are used in the form <code class="highlighter-rouge"><provider>:<jwt-sub-claim></code>.</li> |
| </ul> |
| |
| <h3 id="expiring-policy-subjects">Expiring Policy subjects</h3> |
| |
| <p>When a Policy subject contains an <code class="highlighter-rouge">"expiry"</code> timestamp (formatted as ISO-8601 string), this subject will get |
| automatically deleted once this timestamp was reached.</p> |
| |
| <p>When providing an <code class="highlighter-rouge">"expiry"</code> for a Policy subject, this timestamp is rounded up:</p> |
| <ul> |
| <li>by default to the next full hour</li> |
| <li>this is configurable via the environment variable <code class="highlighter-rouge">POLICY_SUBJECT_EXPIRY_GRANULARITY</code> of the |
| <a href="architecture-services-policies.html">policies</a> service which takes a |
| <a href="https://github.com/lightbend/config/blob/master/HOCON.md#duration-format">HOCON duration</a>, e.g.: |
| <ul> |
| <li>configured to “1s”: a received “expiry” is rounded up to the next full second</li> |
| <li>configured to “30s”: a received “expiry” is rounded up to the next half minute</li> |
| <li>configured to “1h”: a received “expiry” is rounded up to the next full hour (<strong>default</strong>)</li> |
| <li>configured to “12h”: a received “expiry” is rounded up to the next half day</li> |
| <li>configured to “1d”: a received “expiry” is rounded up to the next full day</li> |
| <li>configured to “15d”: a received “expiry” is rounded up to the next half month</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>Once an expired subject is deleted, it will immediately no longer have access to the resources protected by the policy |
| it was deleted from.</p> |
| |
| <h2 id="actions">Actions</h2> |
| |
| <p>Policy actions are available via Ditto’s <a href="httpapi-overview.html">HTTP API</a> and can be invoked for certain |
| <a href="#model-specification">policy entries</a> or for complete policies.</p> |
| |
| <p>They require neither <code class="highlighter-rouge">READ</code> nor <code class="highlighter-rouge">WRITE</code> permission, but instead a granted <code class="highlighter-rouge">EXECUTE</code> permission on the specific action |
| name, e.g. for a single policy entry:</p> |
| <ul> |
| <li><code class="highlighter-rouge">policy:/entries/{label}/actions/{actionName}</code></li> |
| </ul> |
| |
| <h3 id="action-activatetokenintegration">Action activateTokenIntegration</h3> |
| |
| <div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> |
| Make use of this action in order to copy your existing permissions for a pre-configured connection |
| (e.g. invoking an HTTP webhook) until the expiration time of the JWT the user authenticated |
| with passes. |
| </div> |
| |
| <p>When authenticated using OpenID Connect, it is possible to inject a subject into policies that expires when |
| the <a href="#" data-toggle="tooltip" data-original-title="JSON Web Token (JWT)">JWT</a> expires. |
| The form of the injected subject (the token integration subject) is configurable globally in the Ditto installation.</p> |
| |
| <p>A user is authorized to inject the token integration subject when granted the <code class="highlighter-rouge">EXECUTE</code> permission on a policy entry.<br /> |
| The <code class="highlighter-rouge">WRITE</code> permission is not necessary. To activate or deactivate a token integration subject, send a <code class="highlighter-rouge">POST</code> |
| request to the following HTTP routes:</p> |
| |
| <ul> |
| <li><a href="/http-api-doc.html#/Policies/post_policies__policyId__actions_activateTokenIntegration">POST /api/2/policies/{policyId}/actions/activateTokenIntegration</a><br /> |
| Injects a new subject <strong>into all matched policy entries</strong> calculated with information extracted from the authenticated |
| JWT. |
| <ul> |
| <li>the authenticated token must be granted the <code class="highlighter-rouge">EXECUTE</code> permission to perform the <code class="highlighter-rouge">activateTokenIntegration</code> action</li> |
| <li>one of the subject IDs must be contained in the authenticated token</li> |
| <li>at least one <code class="highlighter-rouge">READ</code> permission to a <code class="highlighter-rouge">thing:/</code> resource path must be granted</li> |
| </ul> |
| </li> |
| <li><a href="/http-api-doc.html#/Policies/post_policies__policyId__actions_deactivateTokenIntegration">POST /api/2/policies/{policyId}/actions/deactivateTokenIntegration</a><br /> |
| Removes the calculated subject with information extracted from the authenticated JWT <strong>from all matched policy entries</strong>. |
| <ul> |
| <li>the authenticated token must be granted the <code class="highlighter-rouge">EXECUTE</code> permission to perform the <code class="highlighter-rouge">deactivateTokenIntegration</code> action</li> |
| <li>one of the subject IDs must be contained in the authenticated token</li> |
| </ul> |
| </li> |
| <li><a href="/http-api-doc.html#/Policies/post_policies__policyId__entries__label__actions_activateTokenIntegration">POST /api/2/policies/{policyId}/entries/{label}/actions/activateTokenIntegration</a><br /> |
| Injects the calculated subject <strong>into the policy entry</strong> calculated with information extracted from the authenticated JWT. |
| <ul> |
| <li>the authenticated token must be granted the <code class="highlighter-rouge">EXECUTE</code> permission to perform the <code class="highlighter-rouge">activateTokenIntegration</code> action</li> |
| <li>one of the subject IDs must be contained in the authenticated token</li> |
| <li>at least one <code class="highlighter-rouge">READ</code> permission to a <code class="highlighter-rouge">thing:/</code> resource path must be granted</li> |
| </ul> |
| </li> |
| <li><a href="/http-api-doc.html#/Policies/post_policies__policyId__entries__label__actions_deactivateTokenIntegration">POST /api/2/policies/{policyId}/entries/{label}/actions/deactivateTokenIntegration</a><br /> |
| Removes the calculated subject with information extracted from the authenticated JWT <strong>from the policy entry</strong>. |
| <ul> |
| <li>the authenticated token must be granted the <code class="highlighter-rouge">EXECUTE</code> permission to perform the <code class="highlighter-rouge">deactivateTokenIntegration</code> action</li> |
| <li>one of the subject IDs must be contained in the authenticated token</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>The injected subject pattern is configurable in Ditto and is by default:</p> |
| <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code> |
| integration:{{policy-entry:label}}:{{jwt:aud}} |
| |
| </code></pre></div></div> |
| |
| <p>To configure the token integration subject, set the path</p> |
| <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ditto.gateway.authentication.oauth.token-integration-subject |
| </code></pre></div></div> |
| <p>in <code class="highlighter-rouge">gateway-extension.conf</code>, or set the environment variable <code class="highlighter-rouge">OAUTH_TOKEN_INTEGRATION_SUBJECT</code> for Gateway Service.</p> |
| <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code> |
| ditto.gateway.authentication.oauth.token-integration-subject = |
| "my-token-integration-issuer:{{policy-entry:label}}:{{jwt:sub}}" |
| |
| ditto.gateway.authentication.oauth.token-integration-subject = |
| ${?OAUTH_TOKEN_INTEGRATION_SUBJECT} |
| |
| </code></pre></div></div> |
| |
| <p>The <a href="basic-placeholders.html">placeholders</a> below are usable as a part of the <code class="highlighter-rouge">activateTokenIntegration</code> configuration:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Placeholder</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code class="highlighter-rouge">{{ header:<header-name> }}</code></td> |
| <td>HTTP header values passed along the HTTP action request</td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">{{ jwt:<jwt-body-claim> }}</code></td> |
| <td>any standard or custom claims in the body of the JWT - e.g., <code class="highlighter-rouge">jwt:sub</code> for the JWT “subject”</td> |
| </tr> |
| <tr> |
| <td><code class="highlighter-rouge">{{ policy-entry:label }}</code></td> |
| <td>label of the policy entry in which the token integration subject is injected</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> |
| |
| <h3 id="policy">Policy</h3> |
| |
| <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> |
| |
| <h3 id="thing">Thing</h3> |
| |
| <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> |
| |
| <h3 id="feature">Feature</h3> |
| |
| <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> |
| <tr> |
| <td>thing:/features/X/desiredProperties</td> |
| <td>Applies to all desired properties of the Feature X.</td> |
| </tr> |
| <tr> |
| <td>thing:/features/X/desiredProperties/Y</td> |
| <td>Applies to the desired 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> |
| |
| <h3 id="message">Message</h3> |
| |
| <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 <em>read</em> permission on the resources specified in the path, and all nested paths, except they are revoked at a deeper level, or another policy entry (label).</td> |
| </tr> |
| <tr> |
| <td>grant</td> |
| <td>WRITE</td> |
| <td>All subjects named in the section are granted <em>write</em> permission on the resources specified in the path, and all nested paths, except they are revoked at a deeper level, or another policy entry (label).</td> |
| </tr> |
| <tr> |
| <td>grant</td> |
| <td>EXECUTE</td> |
| <td>All subjects named in the section are granted <em>execute</em> permission on the resources specified in the path, and all nested paths, except they are revoked at a deeper level, or another policy entry (label).</td> |
| </tr> |
| <tr> |
| <td>revoke</td> |
| <td>READ</td> |
| <td>All subjects named in the section are <em>prohibited to read</em> on the resources specified in the path, and all nested paths, except they are granted again such permission at a deeper level, or another policy entry (label).</td> |
| </tr> |
| <tr> |
| <td>revoke</td> |
| <td>WRITE</td> |
| <td>All subjects named in the section are <em>prohibited to write</em> on the resources specified in the path, and all nested paths, except they are granted again such permission at a deeper level, or another policy entry (label).</td> |
| </tr> |
| <tr> |
| <td>revoke</td> |
| <td>EXECUTE</td> |
| <td>All subjects named in the section are <em>prohibited to execute</em> on the resources specified in the path, and all nested paths, except they are granted again such permission at a deeper level, or another policy entry (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="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/<policyId></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/<thingId>?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"> |
| ©2021 Eclipse Ditto™. |
| Site last generated: May 20, 2021 <br /> |
| </p> |
| <div class="quickLinks"> |
| <a href="https://www.eclipse.org/legal/privacy.php" target="_blank"> |
| > Privacy Policy |
| </a> |
| <a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank"> |
| > Terms of Use |
| </a> |
| <a href="https://www.eclipse.org/legal/copyright.php" target="_blank"> |
| > Copyright Agent |
| </a> |
| <a href="https://www.eclipse.org/legal" target="_blank"> |
| > Legal |
| </a> |
| <a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank"> |
| > License |
| </a> |
| <a href="https://eclipse.org/security" target="_blank"> |
| > Report a Vulnerability |
| </a> |
| </div> |
| </div> |
| </div> |
| </footer> |
| |
| |
| </div> |
| <!-- /.row --> |
| </div> |
| <!-- /.container --> |
| </div> |
| <!-- /#main --> |
| </div> |
| |
| </body> |
| </html> |
