-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #214 from telefonicaid/task/update_doc_r5_fiware
task/update_doc_r5_fiware
- Loading branch information
Showing
78 changed files
with
1,060 additions
and
2,653 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,163 +1,8 @@ | ||
| #<a name="top"></a>Cosmos Auth | ||
|
|
||
| * [What is cosmos-auth](#whatis) | ||
| * [Installation](#maininstall) | ||
| * [Prerequisites](#prerequisites) | ||
| * [Installation](#installation) | ||
| * [Unit tests](#unittests) | ||
| * [Configuration](#configuration) | ||
| * [Running](#running) | ||
| * [Administration](#administration) | ||
| * [Usage](#usage) | ||
| * [Annexes](#annexes) | ||
| * [Annex A: Creating a self-signed certificate](#annexa) | ||
| * [Reporting issues and contact information](#contact) | ||
|
|
||
| ##<a name="whatis"></a>What is cosmos-auth | ||
| #<a name="top"></a>Cosmos Auth server | ||
| cosmos-auth exposes a RESTful API for [OAuth2](http://oauth.net/2/) tokens generation. These tokens are used in other Cosmos RESTful APIs, such as [WebHDFS](http://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/WebHDFS.html) for authentication/authorization purposes. | ||
|
|
||
| In fact, tokens are not really generated by cosmos-auth, but by an Identity Manager (FIWARE's implementation is [Keyrock](http://catalogue.fiware.org/enablers/identity-management-keyrock)) which is accessed by this API. So why not directly accessing the Identity Manager? This is because some sensible information regarding the Cosmos application is needed when requesting a token to the Identity Manager; specifically the `client_id` and `client_secret` generated once the Cosmos application is registered. Thus, in order this information continues being secret, it is necessary this kind of intermediary service. | ||
|
|
||
| [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) is used to provide communications security through asymetric cryptography (public/private encryption keys). | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="maininstall"></a>Installation | ||
| This is a software written in JavaScript, specifically suited for [Node.js](https://nodejs.org) (<i>JavaScript on the server side</i>). JavaScript is an interpreted programming language thus it is not necessary to compile it nor build any package; having the source code downloaded somewhere in your machine is enough. | ||
|
|
||
| ###<a name="prerequisites"></a>Prerequisites | ||
| This REST API has no sense if an Identity Manager (Keyrock implementation can be found [here](http://catalogue.fiware.org/enablers/identity-management-keyrock)) is not installed. | ||
|
|
||
| As said, cosmos-auth is a Node.js application, therefore install it from the official [download](https://nodejs.org/download/). An advanced alternative is to install [Node Version Manager](https://github.com/creationix/nvm) (nvm) by creationix/Tim Caswell, which will allow you to have several versions of Node.js and switch among them. | ||
|
|
||
| Of course, common tools such as `git` and `curl` may be needed. | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ###<a name="installation"></a>Installation | ||
| Start by creating, if not yet created, a Unix user named `cosmos-auth`; it is needed for installing and running the application. You can only do this as root, or as another sudoer user: | ||
|
|
||
| $ sudo useradd cosmos-auth | ||
| $ sudo passwd cosmos-auth <choose_a_password> | ||
|
|
||
| While you are a sudoer user, create a folder for saving the cosmos-gui log traces under a path of your choice, typically `/var/log/cosmos/cosmos-auth`, and set `cosmos-auth` as the owner: | ||
|
|
||
| $ sudo mkdir -p /var/log/cosmos/cosmos-auth | ||
| $ sudo chown cosmos-auth:cosmos-auth /var/log/cosmos/cosmos-auth | ||
|
|
||
| Now, change to the new fresh `cosmos-auth` user: | ||
|
|
||
| $ su - cosmos-auth | ||
|
|
||
| Then, clone the Cosmos repository somewhere of your ownership: | ||
|
|
||
| $ git clone https://github.com/telefonicaid/fiware-cosmos.git | ||
|
|
||
| cosmos-auth code is located at `fiware-cosmos/cosmos-auth`. Change to that directory and execute the installation command: | ||
|
|
||
| $ cd fiware-cosmos/cosmos-auth | ||
| $ git checkout release/x.y.z | ||
| $ npm install | ||
|
|
||
| That must download all the dependencies under a `node_modules` directory. | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ###<a name="unittests"></a>Unit tests | ||
| To be done. | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="configuration"></a>Configuration | ||
| cosmos-auth is configured through a JSON file. These are the available parameters: | ||
|
|
||
| * **host**: FQDN or IP address of the host running the service. | ||
| * **port**: TCP listening port for incoming API methods invocation. 13000 by default. | ||
| * **private\_key\_file**: File name containing the private key used to encrypt the communications with the clients. | ||
| * **certificate\_file**: File name containing the self-signed X509 certificate used by the server to send the clients the public counterpart of the above private key. | ||
| * **idm**: | ||
| * **host**: FQDN or IP address where the Identity Manager runs. Do not write it in URL form! | ||
| * **port**: Port where the Identity Manager listens for requests. Typically 443. | ||
| * **path**: Path where the Identity Managers serves the tokens generation. Typically `/oauth2/token`. | ||
| * **cosmos_app**: | ||
| * **client\_id**: This value is given by the Identity Manager when the Cosmos application is registered. By configuring it here, the user has not the need to know about it. | ||
| * **client\_secret**: This value is given by the Identity Manager when the Cosmos application is registered. By configuring it here, the user has not the need to know about it. | ||
| * **log**: | ||
| * **file_name**: path of the file where the log traces will be saved in a daily rotation basis. This file must be within the logging folder owned by the the user `cosmos-auth`. | ||
| * **date_pattern**: data pattern to be appended to the log file name when the log file is rotated. | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="running"></a>Running | ||
| The Http server implemented by cosmos-auth is run as (assuming your current directory is `fiware-cosmos/cosmos-auth`): | ||
|
|
||
| $ npm start | ||
|
|
||
| If everything goes well, you should be able to remotely ask (using a web browser or `curl` tool) for the version of the software: | ||
|
|
||
| $ curl -X GET "https://<host_running_the_api>:13000/cosmos-auth/v1/version" | ||
| {version: 0.0.0} | ||
|
|
||
| cosmos-auth typically listens in the TCP/13000 port (TLS encryption), but you can change it by editing `conf/cosmos-auth.json`. | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="usage"></a>Usage | ||
| Apart from the version method, there is only one available operation in this RESTful API. Use curl this way in order to get an access token: | ||
|
|
||
| curl -k -X POST "https://<host_running_the_api>:13000/cosmos-auth/v1/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=<your_idm_username>&password=<your_idm_password>" | ||
|
|
||
| The response should have the following format (JSON encoding): | ||
|
|
||
| {"access_token": "M2ir2989wWhs5mAmj9OJLQdok0MeGl", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "nEy34Tc74HhlA6Hk34uCihUGRppLO9"} | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="administration"></a>Administration | ||
| Within cosmos-auth, there is a single source of information useful for administrating it: the logs. | ||
|
|
||
| Logging traces are typically saved under `/var/log/cosmos/cosmos-auth`. These traces are written in JSON format, having the following fields: level, message and timestamp. For instance: | ||
|
|
||
| {"level":"info","message":"cosmos-auth running at http://localhost:13000","timestamp":"2015-07-28T14:15:28.746Z"} | ||
|
|
||
| Logging levels follow this hierarchy: | ||
|
|
||
| debug < info < warn < error < fatal | ||
|
|
||
| Within the log it is expected to find many `info` messages, and a few of `warn` or `error` types. Of special interest are the errors: | ||
|
|
||
| * ***Some error occurred during the starting of the Hapi server***: This message may appear when starting cosmos-auth. Most probably the configured host IP address/FQDN does not belongs to the physical machine the service is running, or the configured port is already used . | ||
| * ***Could not connect to the IdM***: This message may appear when connecting to the identity server. Most probably the configured endpoint is not correct, or there is some network error like a port filtering, or the given credentials (cliend id and secret) regarding the application aimed to be authorized (in this case, any Cosmos REST API) are not valid. | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="annexes"></a>Annexes | ||
|
|
||
| ###<a name="annexa"></a>Annex A: Creating a self-signed certificate | ||
|
|
||
| First of all, create a private key; it may not be necessary if you already have one: | ||
|
|
||
| $ openssl genrsa -out private-key.pem 1024 | ||
|
|
||
| Second, create a Certificate Signing Request (CSR) using the private key: | ||
|
|
||
| $ openssl req -new -key private-key.pem -out csr.pem | ||
|
|
||
| Finally, create the self-signed certificate: | ||
|
|
||
| $ openssl x509 -req -in csr.pem -signkey private-key.pem -out public-cert.pem | ||
|
|
||
| [Top](#top) | ||
|
|
||
| ##<a name="contact"></a>Reporting issues and contact information | ||
| There are several channels suited for reporting issues and asking for doubts in general. Each one depends on the nature of the question: | ||
|
|
||
| * Use [stackoverflow.com](http://stackoverflow.com) for specific questions about the software. Typically, these will be related to installation problems, errors and bugs. Development questions when forking the code are welcome as well. Use the `fiware-cosmos` tag. | ||
| * Use [fiware-tech-help@lists.fi-ware.org](mailto:fiware-tech-help@lists.fi-ware.org) for general questions about the software. Typically, these will be related to the conceptual usage of the component, e.g. wether it suites for your project or not. It is worth to mention the issues reported to [fiware-tech-help@lists.fi-ware.org](mailto:fiware-tech-help@lists.fi-ware.org) are tracked under [http://jira.fiware.org](http://jira.fiware.org); use this Jira to see the status of the issue, who has been assigneed to, the exchanged emails, etc, nevertheless the answers will be sent to you via email too. | ||
| * Personal email: | ||
| * [francisco.romerobueno@telefonica.com](mailto:francisco.romerobueno@telefonica.com) **[Main contributor]** | ||
| * [german.torodelvalle@telefonica.com](german.torodelvalle@telefonica.com) **[Contributor]** | ||
|
|
||
| **NOTE**: Please try to avoid personally emailing the contributors unless they ask for it. In fact, if you send a private email you will probably receive an automatic response enforcing you to use [stackoverflow.com](http://stackoverflow.com) or [fiware-tech-help@lists.fi-ware.org](mailto:fiware-tech-help@lists.fi-ware.org). This is because using the mentioned methods will create a public database of knowledge that can be useful for future users; private email is just private and cannot be shared. | ||
|
|
||
| [Top](#top) | ||
| Further information can be found in the documentation at [fiware-cosmos.readthedocs.io](http://fiware-cosmos.readthedocs.io/en/latest/). |
Oops, something went wrong.