Dev Security

From AGILE IoT Wiki
Jump to: navigation, search

Configuring

There are two files used by the agile-security docker container taking care of identity management, policy administration, and policy decision points. The two files are located in the DATA folder under security/agile-idm-core-conf.js and security/agile-ui-conf.js.

Bootstrapping problem

To enable users to log in after agile-security has booted without requiring additional configurations, there is a field in the agile-idm-core.js configuration file that creates particular entities required for the Gateway to function properly in the configure_on_boot property. Agile-security generates all the entities by type required during boot, in case they are not already there. By default the following entities are included:

* Gateway: this entity is needed to place policies to enable actions on the gateway,e.g. turn on device discovery, etc.
* User : agile user created during boot, and he has an admin role (as it can be seen by its definition). This is the default user for the first login, if you want to change this, just update the values before booting, or if you have booted already and want to remove it, clean the database (i.e. remove the db folder inside the security folder in the host) and then update the configuration, and restart. In this way a different user would be generated. It is also possible to add users to this list to create new users during boot. If they were not there, they will be created.
* client: this entity allows us to log in using the OSJS client, also reinstalled on the agile-osjs continaer.

OAuth2 configurations and WebSecurity

Aspects related to authentication providers and Web Security is located on the agile-ui-conf file. To configure CORS domains to generate requests from the browser, enhance the list located under "cors" in the configuration file. This allows browser-side AJAX requests to agile-security from particular domains.

For authentication configuration (for configuring external providers) please see the following site https://github.com/Agile-IoT/agile-security/blob/master/docs/authentication.md


Special keywords

Since the security component behaves as an OAuth2 server towards applications using AGILE, it needs to recognize which applications a which users are interacting with the gateway. What makes this hard is that agile-security needes to know the "public" hostname of the gateway to configure these properties. To this end we have enabled a keyword to use a hostname provided by the AGILE_HOST environment variable or by the /etc/hostname file from the host where the agile-security docker image is running (if the hostname file is mounted in the docker-compose file).

The keyword used to specify the security component to take the AGILE_HOST or the /etc/hostname information (with precedence as they have been mentioned) is set-automatically. So, as it can be observed in the client creation, the url for it is http://set-automatically:8000/. Likewise, to enable CORS to generate requests to the gateway's location with a particular port, in this case 2000, the CORS field in the agile-ui-conf includes "http://set-automatically:2000".


Authentication Client Examples

To see how to let your application authenticate with the AGILE security framweork, have a look at the samples pubhishede here https://github.com/Agile-IoT/agile-idm-examples

Using the Policy Framework in your Application

There are some samples on how to integrate the policy framework within your business logic in a modular way. The code is a documented and available here: https://github.com/agile-iot/agile-policy-sample