Authentication and authorization
Pre-requisites
For all the API operations described in this page, the EGM's authorization context has to be included in every operation. These operations respect the rules of the section 6.3.5 of the NGSI-LD specifications ("JSON-LD @context resolution"), with the exception that the EGM's compound authorization context is considered as the default context for all operations found here.
Specific access policy
Stellio supports providing a specific property, called specificAccessPolicy, to allow any authenticated user to read or update an entity.
This property can be set at entity creation time and it can later be updated by any user who has admin rights on the entity. In case an unauthorized user tries to modify it, a 403 HTTP error is returned.
It currently supports the following two values (more may be added in the future):
AUTH_READ: any authenticated user can read the entityAUTH_WRITE: any authenticated user can update the entity (it of course implies theAUTH_READright)
Update the specific access policy of an entity
This endpoint allows an user to update the specific access policy set on a entity.
It is available under /ngsi-ld/v1/entityAccessControl/{entityId}/attrs/specificAccessPolicy and can be called with a POST request.
The expected request body is an NGSI-LD Attribute Fragment:
{
"type": "Property",
"value": "AUTH_READ"
}
Remove the specific access policy from an entity
This endpoint allows an user to remove the specific access policy set on a entity.
It is available under /ngsi-ld/v1/entityAccessControl/{entityId}/attrs/specificAccessPolicy and can be called with a DELETE request.
Endpoints for rights management
Stellio exposes endpoints that help in managing rights on entities inside the context broker.
Get authorized entites for the currently authenticated user
This endpoint allows an user to get the rights it has on entities.
It is available under /ngsi-ld/v1/entityAccessControl/entities and can be called with a GET request.
The following request parameters are supported:
attrs: restrict returned entities to the ones with a specific right. OnlyrCanRead,rCanWriteandrCanAdminare accepted. A list is accepted (e.g,attrs=rCanRead,rCanWrite). This request parameter has no effect when user has the stellio-admin roletype: restrict returned entities to given entity typesid: restrict returned entities to given ids (comma separated list of strings)
There are several possible answers:
- If user is not admin of the entity but it has a right on it (
rCanReadorrCanWrite), the response body will be under this form:
[
{
"id": "urn:ngsi-ld:Entity:01",
"type": "Entity",
"right": {
"type": "Property",
"value": "rCanWrite"
},
"specificAccessPolicy": {
"type": "Property",
"value": "AUTH_READ"
},
"@context": [ "https://easy-global-market.github.io/ngsild-api-data-models/authorization/jsonld-contexts/authorization.jsonld" ]
},
{
...
}
]
- If user is admin of the entity or has the stellio-admin role, the response body will be under this form:
[
{
"id": "urn:ngsi-ld:Entity:01",
"type": "Entity",
"right": {
"type": "Property",
"value": "rCanAdmin"
},
"specificAccessPolicy": {
"type": "Property",
"value": "AUTH_READ"
},
"rCanRead": [
{
"type": "Relationship",
"object": "urn:ngsi-ld:User:2194588E-D3CE-47F9-B060-B77DB6EAAAD8",
"datasetId": "urn:ngsi-ld:Dataset:2194588E-D3CE-47F9-B060-B77DB6EAAAD8",
"subjectInfo": {
"type": "Property",
"value": {
"kind": "User",
"username": "stellio-user"
}
}
},
{
"type": "Relationship",
"object": "urn:ngsi-ld:Client:D7A09461-4FD1-4B96-A15E-1DCABD11FE04",
"datasetId": "urn:ngsi-ld:Dataset:D7A09461-4FD1-4B96-A15E-1DCABD11FE04",
"subjectInfo": {
"type": "Property",
"value": {
"kind": "Client",
"clientId": "client-id"
}
}
},
{
"type": "Relationship",
"object": "urn:ngsi-ld:Group:5AD29EF5-5427-46DA-9573-7CA03F842701",
"datasetId": "urn:ngsi-ld:Dataset:5AD29EF5-5427-46DA-9573-7CA03F842701",
"subjectInfo": {
"type": "Property",
"value": {
"kind": "Group",
"name": "Stellio Team"
}
}
}
],
"rCanWrite": [
…
],
"rCanAdmin": [
…
],
"@context": [ "https://easy-global-market.github.io/ngsild-api-data-models/authorization/jsonld-contexts/authorization.jsonld" ]
},
{
...
}
]
The body also contains the other users who have a right on the entity.
- If authentication is not enabled, a 204 (No content) response is returned.
Get groups the currently authenticated user belongs to
This endpoint allows an user to get the groups it belongs to.
It is available under /ngsi-ld/v1/entityAccessControl/groups and can be called with a GET request.
There are several possible answers:
- If user is not stellio-admin:
[
{
"id": "urn:ngsi-ld:Group:01",
"type": "Group",
"name": {
"type": "Property",
"value": "EGM"
},
"@context": [ "https://easy-global-market.github.io/ngsild-api-data-models/authorization/jsonld-contexts/authorization.jsonld" ]
}
]
- If user is stellio-admin, all groups are returned:
[
{
"id": "urn:ngsi-ld:Group:01",
"type": "Group",
"name": {
"type": "Property",
"value": "EGM"
},
"isMemberOf": {
"type": "Property",
"value": true
},
"@context": [ "https://easy-global-market.github.io/ngsild-api-data-models/authorization/jsonld-contexts/authorization.jsonld" ]
}
]
The body also contains membership information.
- If authentication is not enabled, a 204 (No content) response is returned.
Get users
This endpoint allows an user with stellio-admin role to get a list of all users
It is available under /ngsi-ld/v1/entityAccessControl/users and can be called with a GET request.
- If user is not stellio-admin, an error 403 is returned
- If user is stellio-admin, all users are returned (
givenNameandfamilyNameare optional fields that may not be part of the response):
[
{
"id": "urn:ngsi-ld:User:01",
"type": "User",
"username": {
"type": "Property",
"value": "username"
},
"givenName": {
"type": "Property",
"value": "givenname"
},
"familyName": {
"type": "Property",
"value": "familyname"
},
"subjectInfo": {
"type": "Property",
"value": {
"gender": "Male",
"city": "Nantes"
}
},
"@context": [ "https://easy-global-market.github.io/ngsild-api-data-models/authorization/jsonld-contexts/authorization.jsonld" ]
}
]
The subjectInfo property is present only if other user attributes are known to the system.
- If authentication is not enabled, a 204 (No content) response is returned.
Add rights on entities for a Stellio User
This endpoint allows an user to give rights on entities it is admin of.
The rights will be given to another user or group. It is necessary to provide the sub of the target user or group (and not the pseudo entity id of an user or group).
It is available under /ngsi-ld/v1/entityAccessControl/{sub}/attrs and can be called with a POST request.
The expected request body is a JSON object containing NGSI-LD Relationships:
{
"rCanRead": [
{
"type": "Relationship",
"object": "entityId1",
"datasetId": "urn:ngsi-ld:Dataset:01"
},
{
"type": "Relationship",
"object": "entityId2",
"datasetId": "urn:ngsi-ld:Dataset:02"
}
],
"rCanWrite": [
…
],
"rCanAdmin": [
…
],
}
Only rCanRead and rCanWrite and rCanAdmin attributes are allowed by this operation.
It returns:
- 204 if all operations succeeded
- 207 if some failed (typically insufficient rights to perform the operation)
Remove rights on an entity for a Stellio User
This endpoint allows an user to remove rights of an user (or group) on an entity it is admin of.
As when adding rights, the user or group whose the right is to be removed is identified by its sub (and not by the pseudo entity id of an user or group). It is necessary to provide the entity_id of the target entity.
It is available under /ngsi-ld/v1/entityAccessControl/{sub}/attrs/{entityId} and can be called with a DELETE request.
It returns 204 if the operation succeeded.