Policies

Activate a subject for this policy entry derived from the token

POST

https://ditto.eclipseprojects.io/api/2/policies/{policyId}/entries/{label}/actions/activateTokenIntegration

This action only works when authenticated with a Json Web Token (JWT).

Based on the authenticated token (JWT), this policy entry is checked to match those conditions:

the authenticated token is granted the EXECUTE permission to perform the activateTokenIntegration action
one of the subject IDs is contained in the authenticated token
at least one READ permission to a thing:/ resource path is granted

When all conditions match, a new subject is injected into this policy entry calculated with information extracted from the authenticated JWT.

The injected subjects expire when the JWT expires. The expiry timestamp (a string in ISO-8601 format) specifies how long the specific subject will have access to the resource secured by the policy. The subject will be automatically deleted from the policy once this timestamp is reached. To give the subject a chance to prolong the access he can configure a connection to get announcements. Policy announcements are published to websockets and connections that have the relevant subject ID.

The settings under announcement control when a policy announcement is published (before expiry or when deleted). If the field requestedAcks is set, then the announcements are published with at-least-once delivery until the acknowledgement requests under labels are fulfilled. If a "beforeExpiry" announcement was sent without acknowledgement requests, or the a "beforeExpiry" announcement was acknowledged, the "whenDeleted" announcement will not be triggered.

Activate a subject for this policy entry derived from the token

curl -X POST 'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/actions/activateTokenIntegration' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}'

const body = `{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}`;

const response = await fetch('https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/actions/activateTokenIntegration', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}'''

response = requests.post(
    'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/actions/activateTokenIntegration',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "requestedAcks": {
      "labels": [
        "my-connection-id:my-issued-acknowledgement"
      ],
      "timeout": "30s"
    },
    "randomizationInterval": "5m"
  }
}

Body

application/json

Optional request payload for activateTokenIntegration policy action.

announcementSubjectAnnouncement

Settings for announcements to be made about the subject.

Show child attributes

beforeExpirystring

The duration before expiry when an announcement should be made. Must be a positive integer followed by one of h (hour), m (minute) or s (second).

whenDeletedboolean

Whether an announcement should be made when this subject is deleted.

requestedAcksobject

Settings to enable at-least-once delivery for policy announcements.

Show child attributes

labelsArray<string>

Acknowledgement labels to request when an announcement is published.

timeoutstring

How long to wait for requested announcements before retrying publication of an announcement.

Example

{
  "labels": [
    "my-connection-id:my-issued-acknowledgement"
  ],
  "timeout": "5s"
}

randomizationIntervalstring5m

Interval in which the announcement can be sent earlier than the configured beforeExpiry. The actual point in time when the announcement will be sent is beforeExpire plus a randomly chosen time within the randomizationInterval. E.g assuming beforeExpiry is set to 5m and randomizationInterval is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.

Example

{
  "beforeExpiry": "5m",
  "whenDeleted": true,
  "randomizationInterval": "5m"
}

Parameters

policyIdstringrequiredpath

The ID of the policy needs to follow the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).

The namespace needs to:

conform to the reverse domain name notation

labelstringrequiredpath

The label of a policy entry

Response

204No Content

The request was successful. The subject was injected.

400Bad Request

The request could not be completed because the authentication was not performed with a JWT.

403Forbidden

The request could not be completed because the authenticated JWT did not have the EXECUTE permission on this policy entry.

404Not Found

The request could not be completed because this policy entry did not match the following conditions:

containing a a subject ID matching the JWT's authenticated subject
containing a READ permission granted to a thing:/ resource path

Authorization

OpenIDConnectopenIdConnect

OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.

NginxBasichttp (basic)

Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)

Bearerhttp (bearer)

A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Docs by Sourcey