ACL are use to secure avatar. They add access rules to avatars. The description of the ACL language can be found here.
Here, we provide a full example showing haw to protect avatar with you own key.
First we create an avatar for the example. This avatar is very simple, it has the IRI http://test.com/acl/obj1
and it is tagged with the label test:red
.
Request:
curl -X 'POST' \
'https://coreapi.thinginthefuture.com/avatars/' \
-H 'Authorization: Bearer ???' \
-H 'Content-Type: application/json' \
-d '{
"_iri": "http://test.com/acl/obj1",
"_labels": ["test:red"]
}'
As this avatar is not yet secured, it can be freely retreived with a find
request (filtering the domain and label).
Request:
curl -X 'POST' \
'https://coreapi.thinginthefuture.com/avatars/find/' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ???' \
-H 'Content-Type: application/json' \
-d '{
"query": {"$domain": "http://test.com/acl/", "$label" : {"$any_in": ["test:red"]}},
"view": {}
}'
Response
{
"size": 1,
"items": [
{
"_uuid": "c445973c-12dc-452a-9067-f9c9da11c8b8",
"_iri": "http://test.com/acl/obj1",
"_domain": "http://test.com/acl/",
"_classes": [],
"_labels": [
"test:red"
],
"_static": false,
"_visibility": 255,
"_source": "5ea27ada-b47f-47b4-b3ed-ad38421c8405",
"_last_updated": 1623317325089,
"_depth": 0,
"_owner": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"_creationDate": 1623317325076
}
],
"page_size": 100,
"index": 0,
"hidden": 0,
"classes": [],
"next": "https://coreapi.thinginthefuture.com/avatars/find?index=100&page_size=100"
}
To add a condition on specific metadata, you should use the $metadata keyword that will provide the information passed by the user.
curl -X 'POST' \
'https://coreapi.thinginthefuture.com/acl/' \
-H 'Authorization: Bearer ???' \
-H 'Content-Type: application/json' \
-d '{
"statements": [
{
"rules": [
{
"action": [
"Read"
],
"effect": "Allow",
"resources": [
"."
]
}
],
"condition": {"$eq" : ["$metadata.mykey", "password"]}
}
],
"desc": "test access with an owner defined metadata"
}'
The uuid of the acl can be found in the response header location like
location: https://coreapi.thinginthefuture.com/acl/912c261a-bec0-4401-80fc-bb8bcc7d68ea
To secure the avatar, the owner of this avatar shall link it to an ACL.
curl -X 'POST' \
'https://coreapi.thinginthefuture.com/acl/912c261a-bec0-4401-80fc-bb8bcc7d68ea/avatars' \
-H 'Authorization: Bearer ???' \
-H 'Content-Type: application/json' \
-d '{
"avatar_iri": [
"http://test.com/acl/obj1"
]
}'
With the same Find request (previously described), the response is now:
{
"size": 0,
"items": [],
"page_size": 100,
"index": 0,
"hidden": -1,
"classes": [],
"next": "https://coreapi.thinginthefuture.com/avatars/find?index=100&page_size=100"
}
Then with the good metadata set in the request, we pass the security check and retreive the avatar.
curl -X 'POST' \
'https://coreapi.thinginthefuture.com/avatars/find/' \
-H 'accept: application/json' \
-H 'Metadata: {"mykey":"password"}' \
-H 'Authorization: Bearer ???' \
-H 'Content-Type: application/json' \
-d '{
"query": {"$domain": "http://test.com/acl/", "$label" : {"$any_in": ["test:red"]}},
"view": {}
}'
Response:
{
"size": 1,
"items": [
{
"_uuid": "445d08fb-7950-4f7d-9b78-2c09361da250",
"_iri": "http://test.com/acl/obj1",
"_domain": "http://test.com/acl/",
"_classes": [],
"_static": false,
"_visibility": 255,
"_source": null,
"_last_updated": 1623164705593,
"_depth": 0,
"_owner": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"_acl": "912c261a-bec0-4401-80fc-bb8bcc7d68ea"
}
],
"page_size": 100,
"index": 0,
"hidden": 0,
"classes": [],
"next": "https://coreapi.thinginthefuture.com/avatars/find?index=100&page_size=100"
}