You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://www.openhub.net/p/eclipse-ditto)
11
12
12
13
[Eclipse Ditto](https://eclipse.org/ditto/) is the open-source project of Eclipse IoT that provides a ready-to-use functionality to manage the state of Digital Twins. It provides access to them and mediates between the physical world and this digital representation.
"description": "The authorization context defines all authorization subjects associated for this source. ",
82
+
"uniqueItems": true,
83
+
"items": {
84
+
"$id": "/properties/authorizationContext/items",
85
+
"type": "string",
86
+
"title": "Authorization Subject",
87
+
"description": "An authorization subject associated with this source. You can either use a fixed subject or use a placeholder that resolves header values from incoming messages. For example to use the `device_id` header in the subject, you can specify the placeholder `{{ header:device_id }}` which is then replaced by Ditto when a message from this source is processed. By using a placeholder you can access any header value: `{{ header:<any-header-name> }}`.",
88
+
"examples": [
89
+
"ditto:myAuthorizationSubject",
90
+
"device:{{ header:device-id }}"
91
+
]
92
+
}
93
+
}
94
+
}
72
95
}
73
96
},
74
97
"targets": {
@@ -81,7 +104,49 @@
81
104
"$id": "/properties/targets/items",
82
105
"type": "object",
83
106
"title": "Target",
84
-
"description": "A publish target served by this connection"
107
+
"description": "A publish target served by this connection",
108
+
"properties": {
109
+
"address": {
110
+
"$id": "/properties/targets/properties/address",
111
+
"type": "string",
112
+
"title": "Target address",
113
+
"description": "The target address where events, commands and messages are published to. The following placeholders are allowed within the target address:\n * Thing ID: `{{ thing:id }}`\n * Thing Namespace: `{{ thing:namespace }}`\n * Thing Name: `{{ thing:name }}` (the part of the ID without the namespace)"
"description": "The topics to which this target is registered for.",
120
+
"uniqueItems": true,
121
+
"items": {
122
+
"type": "string",
123
+
"enum": [
124
+
"_/_/things/twin/events",
125
+
"_/_/things/live/commands",
126
+
"_/_/things/live/events",
127
+
"_/_/things/live/messages"
128
+
],
129
+
"title": "Subscribed topics.",
130
+
"description": "Contains the type of messages that are delivered to this target. You can receive\n * Thing events: `_/_/things/twin/events` (notification about twin change) \n * Live events: `_/_/things/live/events`\n * Live commands: `_/_/things/live/commands`\n * Live messages: `_/_/things/live/messages`"
Copy file name to clipboardexpand all lines: documentation/src/main/resources/pages/ditto/basic-connections.md
+77-8
Original file line number
Diff line number
Diff line change
@@ -5,17 +5,20 @@ tags: [connectivity]
5
5
permalink: basic-connections.html
6
6
---
7
7
8
+
## Connection model
9
+
8
10
{%
9
-
include note.html content="To get started with connections right away, consolidate the [Manage connections](connectivity-manage-connections.html)
10
-
page. "
11
+
include note.html content="To get started with connections right away, consult the [Manage connections]
12
+
(connectivity-manage-connections.html) page. "
11
13
%}
12
14
13
15
You can integrate your Ditto instance with external messaging services such as
14
16
[Eclipse Hono](https://eclipse.org/hono/) or a [RabbitMQ](https://www.rabbitmq.com/) broker via custom "connections".
15
17
16
18
A connection represents a communication channel for the exchange of messages between any service and Ditto. It
17
19
requires a transport protocol, which is used to transmit [Ditto Protocol] messages. Ditto supports one-way and two-way
18
-
communication over connections. This enables consumer/producer scenarios as well as fully-fledged command and response use cases. Nevertheless, those options might be limited by the used transport protocol and/or the other endpoint's
20
+
communication over connections. This enables consumer/producer scenarios as well as fully-fledged command and response
21
+
use cases. Nevertheless, those options might be limited by the transport protocol or the other endpoint's
19
22
capabilities.
20
23
21
24
All connections are configured and supervised via Ditto's
@@ -35,15 +38,81 @@ for custom payload formats. Currently the following connection types are support
35
38
The `sources` and `targets` identifier format depends on the `connectionType` and has therefore `connectionType`
36
39
specific limitations. Those are documented with the corresponding protocol bindings.
37
40
38
-
A connection is initiated by the connectivity service. This obsoletes the need for client authorization, because
41
+
A connection is initiated by the connectivity service. This obviates the need for client authorization, because
39
42
Ditto becomes the client in this case. Nevertheless, to access resources within Ditto, the connection must know on
40
-
which instance’s behalf it is acting. This is controlled via the configured `authorizationContext`, which holds a list of
41
-
self-assigned authorization subjects. Before a connection can access a Ditto resource, one of its
42
-
`authorizationSubject`s must be referenced in the used authorization mechanism, having the needed access rights. You
43
-
can achieve this via [ACLs](basic-acl.html) or [Policies](basic-policy.html).
43
+
whose behalf it is acting. This is controlled via the configured `authorisationContext`, which holds a list of
44
+
self-assigned authorization subjects. Before a connection can access a Ditto resource, one of its
45
+
`authorizationSubject`s must be granted the access rights by an authorization mechanism such as
46
+
[ACLs](basic-acl.html) or [Policies](basic-policy.html).
44
47
45
48
For more information on the `mappingContext` see the corresponding [Payload Mapping Documentation](connectivity-mapping.html)
46
49
50
+
## Placeholders
51
+
52
+
The configuration of a connection allows to use placeholders at certain places. This allows more fine grained control
53
+
over how messages are consumed or where they are published to. The general syntax of a placeholder is
54
+
`{% raw %}{{ placeholder }}{% endraw %}`. A missing placeholder results in an error which is passed back to the sender (if a _reply-to_
55
+
header was provided). Which placeholder values are available depends on the context where the placeholder is used.
56
+
57
+
### Placeholder for source authorization subjects
58
+
Processing the messages received via a source using the _same fixed authorization subject_ may not be
59
+
suitable for every scenario. For example you want to declare fine-grained write permissions per device which would not
60
+
be possible with a fixed global subject. For this use case we introduced placeholder substitution for authorization subjects of
61
+
source addresses that are resolved when processing messages from a source. Of course this requires the sender of the
62
+
message to provide necessary information about the original issuer of the message.
63
+
64
+
{%
65
+
include important.html content="Only use this kind of placeholder if you trust the source of the message. The value from the header is used as the **authorized subject**."
66
+
%}
67
+
68
+
You can access any header value of the incoming message by using a placeholder like `{% raw %}{{ header:name }}{% endraw %}`.
69
+
70
+
Example:
71
+
Assuming the messages received from the source _telemetry_ contain a `device_id` header (e.g. _sensor-123_),
72
+
you may configure your source's authorization subject as follows:
73
+
```json
74
+
{
75
+
"id": "auth-subject-placeholder-example",
76
+
"sources": [
77
+
{
78
+
"addresses": [ "telemetry" ],
79
+
"authorizationContext": ["device:{% raw %}{{ header:device_id }}{% endraw %}"]
80
+
}
81
+
]
82
+
}
83
+
```
84
+
The placeholder is then replaced by the value from the message headers and the message is forwarded and processed under the
85
+
subject _device:sensor-123_.
86
+
In case the header cannot be resolved or the header contains unexpected characters an exception is thrown which is sent
87
+
back to the sender as an error message, if a valid _reply-to_ header was provided, otherwise the message is dropped.
88
+
89
+
### Placeholder for target addresses
90
+
Another use case for placeholders may be to publish thing events or live commands and events to a target address
91
+
containing Thing-specific information e.g. you can distribute Things from different namespaces to different target addresses.
92
+
You can use the placeholders `{% raw %}{{ thing:id }}{% endraw %}`, `{% raw %}{{ thing:namespace }}{% endraw %}` and `{% raw %}{{ thing:name }}{% endraw %}` in the target address for this purpose.
93
+
For a Thing with the ID _org.eclipse.ditto:device-123_ these placeholders are resolved as follows:
94
+
95
+
| Placeholder | Description | Resolved value |
96
+
|--------|------------|------------|
97
+
|`thing:id`| Full ID composed of _namespace_ + _:_ as a separator + _name_| org.eclipse.ditto:device-123|
98
+
|`thing:namespace`| Namespace (i.e. first part of an ID) | org.eclipse.ditto |
99
+
|`thing:name`| Name (i.e. second part of an ID ) | device-123 |
100
+
101
+
102
+
Example:
103
+
Sending live commands and events to a target address that contains the Things' namespace.
104
+
```json
105
+
{
106
+
"id": "target-placeholder-example",
107
+
"targets": [
108
+
{
109
+
"addresses": [ "live/{% raw %}{{ thing:namespace }}{% endraw %}" ],
0 commit comments