EC Project:  SocIoTal

The SocIoTal access control system is designed as a combination of different authorization technologies and tools in order to enable a suitable solution for IoT environments. Such system is based on the use of XACML access control policies, which are employed to generate authorization credentials in the form of capability tokens. Then, such tokens are used by smart objects to get access to services being provided by other IoT entities.

The design and implementation of this system have been realized through the convergence of technologies, and adapted to be integrated with other SocIoTal components. On the one hand, it has been integrated with the FI-WARE IdM, so authorization decisions are based on the identity attributes that are stored in the Keyrock IdM instance. On the other hand, part of this system is integrated in the SocIoTal Context Manager, which is also responsible for evaluating capability tokens to allow or not a specific NGSI action over a certain entity. Furthermore, it has been adapted to SocIoTal scenarios enabling the process to be carried out directly and through the Web User Environment without the need of certificates.

The SocIoTal Authorization scenario consists of the following main entities:

  • Capability Client. It is a HTTPS client, which is intended to making request to the Capability Manager to obtain capability tokens, which are used to get access to resources hosted by other devices.
  • Capability Evaluator. It is a library intended to evaluate capability tokens. Such evaluation is based on the action and device being requested and the use of KeyRock authentication credentials.
  • Capability Manager. It is a HTTPS server accepting requests for capability tokens generation. Additionally, this entity acts as a HTTP client requesting authorization decisions to the Policy Decision Point.
  • Policy Decision Point (PDP). It is a HTTPS server based on XACML. It accepts XACML requests, which are attached into HTTP requests within the body. The PDP is contacted by the Capability Manager before generating a capability token for the Capability Client.
  • Policy Administration Point (PAP). It is the entity responsible for managing the access control policies. It provides the functionality so users can define XACML policies in user-friendly way. The PAP has a GUI to facilitate the generation of XACML policies.

The PAP allows policies specifying subjects, resources and actions to be generated. Once the subjects, the resources and their associated actions are defined, the policies can be defined. After that, the policies are saved, to define the policies and then the apply button is used to generate the policy file. Once the policies are saved, a request can be made to the PDP which has the location of the policies set up, and the request is evaluated. The request sent is in JSON format. This allows a less verbose representation of the information and brings an improvement in terms of processing as well. If successfully resolved the PDP will return a response in the form of {“Result”:”Permit”}. The PDP can be set as web service to access by the Policy Enforcement Point. This is currently the case, as we receive an HTTP request with the XACML Request as payload and receive the response.

Process Flow

Taking into account the core entities of the process, the basic flow of the SocIoTal Authorization Manager is as follows:

  1. The Capability Client issues a HTTPS request to the Capability Manager. This request from the Capability Client contains the resource and NGSI action, for which it wants a capability token. In addition, in case of not using certificates, this request contains de clientID and authTokenID that can be obtained by using the IdM library functionality.
  2. The Capability Manager authenticates the client. Then, the clientID obtained from the request is used to make a request to the Keyrock IdM obtaining the identity attributes that are associated to such client.
  3. Then, the Capability Manager builds a XACML request making use of the resource, NGSI action contained within the client’s request, as well as the attributes obtained from the KeyRock IdM.
  4. The Capability Manager makes a HTTPS request to the Policy Decision Point, in which the XACML request is attached as body of the HTTPS request.
  5. The PDP evaluates the XACML request against the XACML authorization policies, and performs an authorization decision. These policies must be previously defined through the use of the PAP.
  6. The Capability Manager obtains an authorization decision from the PDP. In case of a “Permit” decision, a capability token is generated for the action and resource specified, and delivered to the Capability Client. The token validity period will depend on the use of the Obligations field in the PAP, where it can be managed.

It should be noticed the previous stage is only required in case the Capability Client does not possess a capability token for the resource and action specified. Regarding the use of capability tokens to get access an entity within the SocIoTal Context Manager, the flow is:

  1. The Capability Client issues a HTTPS request to the Context Manager. This request contains the entity and the NGSI action, as well as the capability token previously obtained. Furthermore, it contained the cliendID and authTokenID that were previously used for getting the capability token
  2. Then, the Context Manager, through the use of the Capability Evaluator library, carries out the evaluation and returns a response according the capability token evaluation. This process involves a request to the KeyRock IdM to validate the user’s authentication.
API Libraries
Capability Client library

To make use of the Capability Client library, below, a summary of such steps is also provided:

  • To use the library in your application, it is required to import the libs folder that is provided in the repository, as well as the certificates folder (certs_sociotal) for HTTPS communications.

Below, a summary of the Capability Client API is provided.

  • Settings (String keystore_file, String certs_folder, String [] trustedCerts, String capability_tokens_folder, String keystore_password, boolean cert_authentication, boolean useDelegation). It build a Settings object to configure the a HTTPS CapabilityClient instance.
  • HTTPSCapabilityClient (Settings settings). It builds a HTTPS Capability Client instance through the use of the Settings object.
  • Capability Token ownToken (NGSI_ACTION action, String entiy). This method checks if the capability client already has a capability token for the NGSI action and entity being specified.
  • Capability Token requestCapabilityToken (String user_id, String token_id, NGSI_ACTION ngsi_action, String entity, String ipCapabilityManager). It requests a capability token for a specific NGSI action and entity to the Capability Manager. It includes the userID and the tokenID (that can be obtained with the SocIoTal IdM API to validate authentication).
  • boolean tokenIsValid(). This method checks if a capability token is valid (if it is no expired)
  • HTTPSContextManagerClient (Settings settings). It builds a HTTPSContextManagerClient instance through the use of the Settings object.
  • String getAccess(CapabilityToken token, String cm_uri, String payload, String client_id, String token_id, String comm_id). It makes a HTTPS request to the Context Manager to perform a specific action (identified in the cm_uri parameter) on a particular entity (identified in the cm_uri or payload depending on the NGSI method being used), by making use of a capability token. It returns an answer from the Context Manager.

In addition, for the sake of clarity, a brief description of each field is provided:

  • Identifier (id). This field is used to unequivocally identify a capability token. A random or pseudorandom technique will be employed by the issuer to ensure this identifier is unique.
  • Issued-time (ii). It identifies the time at which the token was issued as the number of seconds from 1970-01-01T0:0:0Z.
  • Issuer (is). The entity that issued the token and, therefore, the signer of it.
  • Subject (su). It makes reference to the subject’s public key to which the rights from the token are granted.
  • Device (de). It is a URI used to unequivocally identify the device to which the token applies.
  • Signature (si). It carries the digital signature of the token encoded through Base64.
  • Access Rights (ar). This field represents the set of rights that the issuer has granted to the subject.
    • Action (ac). Its purpose is to identify a specific NGSI-9/NGSI-10 granted action (e.g. queryContext)
    • Resource (re). It represents the resource in the device for which the action is granted.
  • Not Before (nb). The time before which the token must not be accepted. Its value cannot be earlier than the II field and it implies the current time must be after or equal than NB.
  • Not After (na). It represents the time after which the token must not be accepted.
Capability Evaluator library

The library of the Capability Evaluator for evaluating capability tokens. This library is already used by the SocIoTal Context Manager to deny or permit the access to an entity. In case you are using your own HTTPS or CoAPS server you can use this library independently. For a description of the API:

  • **CapabilityEvaluator ** (String certsFolder, String certKeyRock, String keyrockpassword, String keyRockIP, String keyRockPort). It build a CapabilityEvaluator instance specifying the certificates folder path, the name of the KeyRock’s certificate, the KeyRock’s password, and the IP address and port of it.
  • CapabilityVerifierCode evaluateCapabilityToken(String capability_token, String signature, String cm_uri, String payload, String token_id, String client_id). It evaluates a capability token for the specified NGSI action (from cm_uri or payload depending on the NGSI action method) and entity (from cm_uri or payload depending on the NGSI action method). Optionally, it can use the signature, token_id and client_id parameters depending on the access if done with certificates or not.