Skip to content

Latest commit

 

History

History
142 lines (92 loc) · 9.3 KB

README.md

File metadata and controls

142 lines (92 loc) · 9.3 KB
Raw

#Cosmos Auth

##What is cosmos-auth cosmos-auth exposes a RESTful API for OAuth2 tokens generation. These tokens are used in other Cosmos RESTful APIs, such as WebHDFS for authentication/authorization purposes.

In fact, tokens are not really generated by cosmos-auth, but by an Identity Manager (FIWARE's implementation is Keyrock) which is accessed by this API. So why not directy 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 (TLS) is used to provide communications security through asymetric cryptography (public/private encryption keys).

Top

##Installation This is a software written in JavaScript, specifically suited for Node.js (JavaScript on the server side). 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.

###Prerequisites This REST API has no sense if an Identity Manager (Keyrock implementation can be found here) is not installed.

As said, cosmos-auth is a Node.js application, therefore install it from the official download. An advanced alternative is to install Node Version Manager (nvm) by creationix/Tim Caswell, whcih 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

###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
$ npm install

That must download all the dependencies under a node_modules directory.

Top

###Unit tests To be done.

Top

##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 incomming 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. Typicaly /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

##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

##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 -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>"

Resposne have the following format (JSON encoding):

{"access_token": "M2ir2989wWhs5mAmj9OJLQdok0MeGl", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "nEy34Tc74HhlA6Hk34uCihUGRppLO9"}

Top

##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

##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 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 [email protected] 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 [email protected] are tracked under 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:

NOTE: Please try to avoid personaly 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 or [email protected]. 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